org.glassfish.jersey.server.Uri Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of jaxrs-ri Show documentation

A bundle project producing JAX-RS RI bundles. The primary artifact is an "all-in-one" OSGi-fied JAX-RS RI bundle (jaxrs-ri.jar). Attached to that are two compressed JAX-RS RI archives. The first archive (jaxrs-ri.zip) consists of binary RI bits and contains the API jar (under "api" directory), RI libraries (under "lib" directory) as well as all external RI dependencies (under "ext" directory). The secondary archive (jaxrs-ri-src.zip) contains buildable JAX-RS RI source bundle and contains the API jar (under "api" directory), RI sources (under "src" directory) as well as all external RI dependencies (under "ext" directory). The second archive also contains "build.xml" ANT script that builds the RI sources. To build the JAX-RS RI simply unzip the archive, cd to the created jaxrs-ri directory and invoke "ant" from the command line.

There is a newer version: 3.1.9

Show newest version

/*
 * Copyright (c) 2011, 2020 Oracle and/or its affiliates. All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0, which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 *
 * This Source Code may also be made available under the following Secondary
 * Licenses when the conditions for such availability set forth in the
 * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
 * version 2 with the GNU Classpath Exception, which is available at
 * https://www.gnu.org/software/classpath/license.html.
 *
 * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
 */

package org.glassfish.jersey.server;

import java.lang.annotation.Documented;
import java.lang.annotation.Retention;

import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.ElementType.PARAMETER;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

/**
 * Injects a {@link jakarta.ws.rs.client.WebTarget resource target} pointing at
 * a resource identified by the resolved URI into a method parameter,
 * class field or a bean property.
 * 
 * Injected variable must be of type {@link jakarta.ws.rs.client.WebTarget}.
 *
 * @author Marek Potociar
 * @see jakarta.ws.rs.client.WebTarget
 * @since 2.0
 */
@java.lang.annotation.Target({PARAMETER, FIELD, METHOD})
@Retention(RUNTIME)
@Documented
public @interface Uri {

    /**
     * Specifies the URI of the injected {@link jakarta.ws.rs.client.WebTarget
     * resource target}.
     *
     * The value must be in the form of absolute URI if not used from inside of
     * a JAX-RS component class. For example:
     * 
     * public class AuditingFilter implements RequestFilter {
     *    @Uri("users/{name}/orders")
     *    WebTarget userOrders;
     *
     *    // An external resource target
     *    @Uri("http://mail.acme.com/accounts/{name}")
     *    WebTarget userEmailAccount;
     *
     *    // An external, template-based resource target
     *    @Uri("http://{audit-host}:{audit-port}/auditlogs/")
     *    WebTarget auditLogs;
     *    ...
     * }
     * 
     *
     * If used from within a JAX-RS component class (e.g. resource, filter, provider … ),
     * the value can take a form of absolute or relative URI.
     * A relative URI is resolved using the context path of the application as the base URI.
     * For example:
     *      * public class AuditingFilter implements RequestFilter {
     *    @Uri("audit/logs")
     *    WebTarget applicationLogs;
     *
     *    @Uri("http://sales.acme.com/audit/logs")
     *    WebTarget domainLogs;
     *
     *    ...
     * }
     * 
     *
     * In case the annotation is used from a JAX-RS resource class, an absolute
     * or relative URI template value may be provided. The template parameter (e.g. {@code {id}})
     * values are automatically resolved in the context of the enclosing resource class
     * {@link jakarta.ws.rs.Path path template} as well as the context of the processed request.
     * Other defined template parameters have to be resolved before invocation of managed web target.
     * For example:
     *      * @Path("users/{name}")
     * public class MyResource {
     *    @Uri("users/{name}/orders")
     *    WebTarget userOrders;
     *
     *    @Uri("http://mail.acme.com/accounts/{name}")
     *    WebTarget userEmailAccount;
     *
     *    ...
     * }
     * 
     *
     * @see jakarta.ws.rs.client.WebTarget
     * @see jakarta.ws.rs.Path
     */
    String value();
}