1 /*
   2  * Copyright (c) 2005, 2014, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.xml.ws;
  27 
  28 import javax.xml.ws.soap.Addressing;
  29 import javax.xml.ws.spi.WebServiceFeatureAnnotation;
  30 import java.lang.annotation.Documented;
  31 import java.lang.annotation.Target;
  32 import java.lang.annotation.ElementType;
  33 import java.lang.annotation.Retention;
  34 import java.lang.annotation.RetentionPolicy;
  35 
  36 /**
  37  * The <code>WebServiceRef</code> annotation is used to
  38  * define a reference to a web service and
  39  * (optionally) an injection target for it.
  40  * It can be used to inject both service and proxy
  41  * instances. These injected references are not thread safe.
  42  * If the references are accessed by multiple threads,
  43  * usual synchronization techinques can be used to
  44  * support multiple threads.
  45  *
  46  * <p>
  47  * Web service references are resources in the Java EE 5 sense.
  48  * The annotations (for example, {@link Addressing}) annotated with
  49  * meta-annotation {@link WebServiceFeatureAnnotation}
  50  * can be used in conjunction with <code>WebServiceRef</code>.
  51  * The created reference MUST be configured with annotation's web service
  52  * feature.
  53  *
  54  * <p>
  55  * For example, in the code below, the injected
  56  * <code>StockQuoteProvider</code> proxy MUST
  57  * have WS-Addressing enabled as specifed by the
  58  * {@link Addressing}
  59  * annotation.
  60  *
  61  * <pre><code>
  62  *    public class MyClient {
  63  *       @Addressing
  64  *       @WebServiceRef(StockQuoteService.class)
  65  *       private StockQuoteProvider stockQuoteProvider;
  66  *       ...
  67  *    }
  68  * </code></pre>
  69  *
  70  * <p>
  71  * If a JAX-WS implementation encounters an unsupported or unrecognized
  72  * annotation annotated with the <code>WebServiceFeatureAnnotation</code>
  73  * that is specified with <code>WebServiceRef</code>, an ERROR MUST be given.
  74  *
  75  * @see javax.annotation.Resource
  76  * @see WebServiceFeatureAnnotation
  77  *
  78  * @since 1.6, JAX-WS 2.0
  79  *
  80 **/
  81 
  82 @Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD})
  83 @Retention(RetentionPolicy.RUNTIME)
  84 @Documented
  85 public @interface WebServiceRef {
  86     /**
  87      * The JNDI name of the resource.  For field annotations,
  88      * the default is the field name.  For method annotations,
  89      * the default is the JavaBeans property name corresponding
  90      * to the method.  For class annotations, there is no default
  91      * and this MUST be specified.
  92      *
  93      * The JNDI name can be absolute(with any logical namespace) or relative
  94      * to JNDI <code>java:comp/env</code> namespace.
  95      */
  96     String name() default "";
  97 
  98     /**
  99      * The Java type of the resource.  For field annotations,
 100      * the default is the type of the field.  For method annotations,
 101      * the default is the type of the JavaBeans property.
 102      * For class annotations, there is no default and this MUST be
 103      * specified.
 104      */
 105     Class<?> type() default Object.class;
 106 
 107     /**
 108      * A product specific name that this resource should be mapped to.
 109      * The name of this resource, as defined by the <code>name</code>
 110      * element or defaulted, is a name that is local to the application
 111      * component using the resource.  (When a relative JNDI name
 112      * is specified, then it's a name in the JNDI
 113      * <code>java:comp/env</code> namespace.)  Many application servers
 114      * provide a way to map these local names to names of resources
 115      * known to the application server.  This mapped name is often a
 116      * <i>global</i> JNDI name, but may be a name of any form.
 117      * <p>
 118      * Application servers are not required to support any particular
 119      * form or type of mapped name, nor the ability to use mapped names.
 120      * The mapped name is product-dependent and often installation-dependent.
 121      * No use of a mapped name is portable.
 122      */
 123     String mappedName() default "";
 124 
 125     /**
 126      * The service class, always a type extending
 127      * <code>javax.xml.ws.Service</code>. This element MUST be specified
 128      * whenever the type of the reference is a service endpoint interface.
 129      */
 130     // 2.1 has Class value() default Object.class;
 131     // Fixing this raw Class type correctly in 2.2 API. This shouldn't cause
 132     // any compatibility issues for applications.
 133     Class<? extends Service> value() default Service.class;
 134 
 135     /**
 136      * A URL pointing to the WSDL document for the web service.
 137      * If not specified, the WSDL location specified by annotations
 138      * on the resource type is used instead.
 139      */
 140     String wsdlLocation() default "";
 141 
 142     /**
 143      * A portable JNDI lookup name that resolves to the target
 144      * web service reference.
 145      *
 146      * @since 1.7, JAX-WS 2.2
 147      */
 148     String lookup() default "";
 149 
 150 }