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