/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package javax.xml.ws;

import javax.xml.ws.soap.Addressing;

import javax.xml.ws.spi.WebServiceFeatureAnnotation;

import java.lang.annotation.Documented;

import java.lang.annotation.Target;

import java.lang.annotation.ElementType;

import java.lang.annotation.Retention;

import java.lang.annotation.RetentionPolicy;

/**

 * The <code>WebServiceRef</code> annotation is used to

 * define a reference to a web service and

 * (optionally) an injection target for it.

 * It can be used to inject both service and proxy

 * instances. These injected references are not thread safe.

 * If the references are accessed by multiple threads,

 * usual synchronization techinques can be used to

 * support multiple threads.

 *

 * <p>

 * Web service references are resources in the Java EE 5 sense.

 * The annotations (for example, {@link Addressing}) annotated with

 * meta-annotation {@link WebServiceFeatureAnnotation}

 * can be used in conjunction with <code>WebServiceRef</code>.

 * The created reference MUST be configured with annotation's web service

 * feature.

 *

 * <p>

 * For example, in the code below, the injected

 * <code>StockQuoteProvider</code> proxy MUST

 * have WS-Addressing enabled as specifed by the

 * {@link Addressing}

 * annotation.

 *

 * <pre><code>

 *    public class MyClient {

 *       @Addressing

 *       @WebServiceRef(StockQuoteService.class)

 *       private StockQuoteProvider stockQuoteProvider;

 *       ...

 *    }

 * </code></pre>

 *

 * <p>

 * If a JAX-WS implementation encounters an unsupported or unrecognized

 * annotation annotated with the <code>WebServiceFeatureAnnotation</code>

 * that is specified with <code>WebServiceRef</code>, an ERROR MUST be given.

 *

 * @see javax.annotation.Resource

 * @see WebServiceFeatureAnnotation

 *

 * @since JAX-WS 2.0

 *

**/

@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD})

@Retention(RetentionPolicy.RUNTIME)

@Documented

public @interface WebServiceRef {

    /**

     * The JNDI name of the resource.  For field annotations,

     * the default is the field name.  For method annotations,

     * the default is the JavaBeans property name corresponding

     * to the method.  For class annotations, there is no default

     * and this MUST be specified.

     *

     * The JNDI name can be absolute(with any logical namespace) or relative

     * to JNDI <code>java:comp/env</code> namespace.

     */

    String name() default "";

    /**

     * The Java type of the resource.  For field annotations,

     * the default is the type of the field.  For method annotations,

     * the default is the type of the JavaBeans property.

     * For class annotations, there is no default and this MUST be

     * specified.

     */

    Class<?> type() default Object.class;

    /**

     * A product specific name that this resource should be mapped to.

     * The name of this resource, as defined by the <code>name</code>

     * element or defaulted, is a name that is local to the application

     * component using the resource.  (When a relative JNDI name

     * is specified, then it's a name in the JNDI

     * <code>java:comp/env</code> namespace.)  Many application servers

     * provide a way to map these local names to names of resources

     * known to the application server.  This mapped name is often a

     * <i>global</i> JNDI name, but may be a name of any form.

     * <p>

     * Application servers are not required to support any particular

     * form or type of mapped name, nor the ability to use mapped names.

     * The mapped name is product-dependent and often installation-dependent.

     * No use of a mapped name is portable.

     */

    String mappedName() default "";

    /**

     * The service class, alwiays a type extending

     * <code>javax.xml.ws.Service</code>. This element MUST be specified

     * whenever the type of the reference is a service endpoint interface.

     */

    // 2.1 has Class value() default Object.class;

    // Fixing this raw Class type correctly in 2.2 API. This shouldn't cause

    // any compatibility issues for applications.

    Class<? extends Service> value() default Service.class;

    /**

     * A URL pointing to the WSDL document for the web service.

     * If not specified, the WSDL location specified by annotations

     * on the resource type is used instead.

     */

    String wsdlLocation() default "";

    /**

     * A portable JNDI lookup name that resolves to the target

     * web service reference.

     *

     * @since JAX-WS 2.2

     */

    String lookup() default "";

}