1 /*
   2  * Copyright (c) 2005, 2017, 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.Repeatable;
  34 import java.lang.annotation.Retention;
  35 import java.lang.annotation.RetentionPolicy;
  36 import javax.annotation.Resource;
  37 
  38 /**
  39  * The {@code WebServiceRef} annotation is used to
  40  * define a reference to a web service and
  41  * (optionally) an injection target for it.
  42  * It can be used to inject both service and proxy
  43  * instances. These injected references are not thread safe.
  44  * If the references are accessed by multiple threads,
  45  * usual synchronization techinques can be used to
  46  * support multiple threads.
  47  *
  48  * <p>
  49  * Web service references are resources in the Java EE 5 sense.
  50  * The annotations (for example, {@link Addressing}) annotated with
  51  * meta-annotation {@link WebServiceFeatureAnnotation}
  52  * can be used in conjunction with {@code WebServiceRef}.
  53  * The created reference MUST be configured with annotation's web service
  54  * feature.
  55  *
  56  * <p>
  57  * For example, in the code below, the injected
  58  * {@code StockQuoteProvider} proxy MUST
  59  * have WS-Addressing enabled as specifed by the
  60  * {@link Addressing}
  61  * annotation.
  62  *
  63  * <pre><code>
  64  *    public class MyClient {
  65  *       {@literal @}Addressing
  66  *       {@literal @}WebServiceRef(StockQuoteService.class)
  67  *       private StockQuoteProvider stockQuoteProvider;
  68  *       ...
  69  *    }
  70  * </code></pre>
  71  *
  72  * <p>
  73  * If a JAX-WS implementation encounters an unsupported or unrecognized
  74  * annotation annotated with the {@code WebServiceFeatureAnnotation}
  75  * that is specified with {@code WebServiceRef}, an ERROR MUST be given.
  76  *
  77  * @see Resource
  78  * @see WebServiceFeatureAnnotation
  79  *
  80  * @since 1.6, JAX-WS 2.0
  81  *
  82  **/
  83 
  84 @Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD})
  85 @Retention(RetentionPolicy.RUNTIME)
  86 @Documented
  87 @Repeatable(WebServiceRefs.class)
  88 public @interface WebServiceRef {
  89     /**
  90      * The JNDI name of the resource.  For field annotations,
  91      * the default is the field name.  For method annotations,
  92      * the default is the JavaBeans property name corresponding
  93      * to the method.  For class annotations, there is no default
  94      * and this MUST be specified.
  95      *
  96      * The JNDI name can be absolute(with any logical namespace) or relative
  97      * to JNDI {@code java:comp/env} namespace.
  98      *
  99      * @return absolute or relative JNDI name
 100      */
 101     String name() default "";
 102 
 103     /**
 104      * The Java type of the resource.  For field annotations,
 105      * the default is the type of the field.  For method annotations,
 106      * the default is the type of the JavaBeans property.
 107      * For class annotations, there is no default and this MUST be
 108      * specified.
 109      *
 110      * @return type of the resource
 111      */
 112     Class<?> type() default Object.class;
 113 
 114     /**
 115      * A product specific name that this resource should be mapped to.
 116      * The name of this resource, as defined by the {@code name}
 117      * element or defaulted, is a name that is local to the application
 118      * component using the resource.  (When a relative JNDI name
 119      * is specified, then it's a name in the JNDI
 120      * {@code java:comp/env} namespace.)  Many application servers
 121      * provide a way to map these local names to names of resources
 122      * known to the application server.  This mapped name is often a
 123      * <i>global</i> JNDI name, but may be a name of any form.
 124      * <p>
 125      * Application servers are not required to support any particular
 126      * form or type of mapped name, nor the ability to use mapped names.
 127      * The mapped name is product-dependent and often installation-dependent.
 128      * No use of a mapped name is portable.
 129      *
 130      * @return product specific resource name
 131      */
 132     String mappedName() default "";
 133 
 134     /**
 135      * The service class, always a type extending
 136      * {@code javax.xml.ws.Service}. This element MUST be specified
 137      * whenever the type of the reference is a service endpoint interface.
 138      *
 139      * @return the service class extending {@code javax.xml.ws.Service}
 140      */
 141      // 2.1 has Class value() default Object.class;
 142      // Fixing this raw Class type correctly in 2.2 API. This shouldn't cause
 143      // any compatibility issues for applications.
 144     Class<? extends Service> value() default Service.class;
 145 
 146     /**
 147      * A URL pointing to the WSDL document for the web service.
 148      * If not specified, the WSDL location specified by annotations
 149      * on the resource type is used instead.
 150      *
 151      * @return a URL pointing to the WSDL document
 152      */
 153     String wsdlLocation() default "";
 154 
 155     /**
 156      * A portable JNDI lookup name that resolves to the target
 157      * web service reference.
 158      *
 159      * @return portable JNDI lookup name
 160      * @since 1.7, JAX-WS 2.2
 161      */
 162     String lookup() default "";
 163 
 164 }
--- EOF ---