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 }