Package: WebServiceRef

WebServiceRef

Coverage

1: /*
2: * Copyright (c) 2005, 2020 Oracle and/or its affiliates. All rights reserved.
3: *
4: * This program and the accompanying materials are made available under the
5: * terms of the Eclipse Distribution License v. 1.0, which is available at
6: * http://www.eclipse.org/org/documents/edl-v10.php.
7: *
8: * SPDX-License-Identifier: BSD-3-Clause
9: */
10:
11: package jakarta.xml.ws;
12:
13: import jakarta.xml.ws.soap.Addressing;
14: import jakarta.xml.ws.spi.WebServiceFeatureAnnotation;
15: import java.lang.annotation.Documented;
16: import java.lang.annotation.Target;
17: import java.lang.annotation.ElementType;
18: import java.lang.annotation.Repeatable;
19: import java.lang.annotation.Retention;
20: import java.lang.annotation.RetentionPolicy;
21:
22: /**
23: * The {@code WebServiceRef} annotation is used to
24: * define a reference to a web service and
25: * (optionally) an injection target for it.
26: * It can be used to inject both service and proxy
27: * instances. These injected references are not thread safe.
28: * If the references are accessed by multiple threads,
29: * usual synchronization techinques can be used to
30: * support multiple threads.
31: *
32: * <p>
33: * Web service references are resources in the Jakarta EE sense.
34: * The annotations (for example, {@link Addressing}) annotated with
35: * meta-annotation {@link WebServiceFeatureAnnotation}
36: * can be used in conjunction with {@code WebServiceRef}.
37: * The created reference MUST be configured with annotation's web service
38: * feature.
39: *
40: * <p>
41: * For example, in the code below, the injected
42: * {@code StockQuoteProvider} proxy MUST
43: * have WS-Addressing enabled as specifed by the
44: * {@link Addressing}
45: * annotation.
46: *
47: * <pre><code>
48: * public class MyClient {
49: * {@literal @}Addressing
50: * {@literal @}WebServiceRef(StockQuoteService.class)
51: * private StockQuoteProvider stockQuoteProvider;
52: * ...
53: * }
54: * </code></pre>
55: *
56: * <p>
57: * If a Jakarta XML Web Services implementation encounters an unsupported or unrecognized
58: * annotation annotated with the {@code WebServiceFeatureAnnotation}
59: * that is specified with {@code WebServiceRef}, an ERROR MUST be given.
60: *
61: * @see "jakarta.annotation.Resource"
62: * @see WebServiceFeatureAnnotation
63: *
64: * @since 1.6, JAX-WS 2.0
65: *
66: **/
67:
68: @Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD})
69: @Retention(RetentionPolicy.RUNTIME)
70: @Documented
71: @Repeatable(WebServiceRefs.class)
72: public @interface WebServiceRef {
73: /**
74: * The JNDI name of the resource. For field annotations,
75: * the default is the field name. For method annotations,
76: * the default is the JavaBeans property name corresponding
77: * to the method. For class annotations, there is no default
78: * and this MUST be specified.
79: *
80: * The JNDI name can be absolute(with any logical namespace) or relative
81: * to JNDI {@code java:comp/env} namespace.
82: *
83: * @return absolute or relative JNDI name
84: */
85: String name() default "";
86:
87: /**
88: * The Java type of the resource. For field annotations,
89: * the default is the type of the field. For method annotations,
90: * the default is the type of the JavaBeans property.
91: * For class annotations, there is no default and this MUST be
92: * specified.
93: *
94: * @return type of the resource
95: */
96: Class<?> type() default Object.class;
97:
98: /**
99: * A product specific name that this resource should be mapped to.
100: * The name of this resource, as defined by the {@code name}
101: * element or defaulted, is a name that is local to the application
102: * component using the resource. (When a relative JNDI name
103: * is specified, then it's a name in the JNDI
104: * {@code java:comp/env} namespace.) Many application servers
105: * provide a way to map these local names to names of resources
106: * known to the application server. This mapped name is often a
107: * <i>global</i> JNDI name, but may be a name of any form.
108: * <p>
109: * Application servers are not required to support any particular
110: * form or type of mapped name, nor the ability to use mapped names.
111: * The mapped name is product-dependent and often installation-dependent.
112: * No use of a mapped name is portable.
113: *
114: * @return product specific resource name
115: */
116: String mappedName() default "";
117:
118: /**
119: * The service class, always a type extending
120: * {@code jakarta.xml.ws.Service}. This element MUST be specified
121: * whenever the type of the reference is a service endpoint interface.
122: *
123: * @return the service class extending {@code jakarta.xml.ws.Service}
124: */
125: // 2.1 has Class value() default Object.class;
126: // Fixing this raw Class type correctly in 2.2 API. This shouldn't cause
127: // any compatibility issues for applications.
128: Class<? extends Service> value() default Service.class;
129:
130: /**
131: * A URL pointing to the WSDL document for the web service.
132: * If not specified, the WSDL location specified by annotations
133: * on the resource type is used instead.
134: *
135: * @return a URL pointing to the WSDL document
136: */
137: String wsdlLocation() default "";
138:
139: /**
140: * A portable JNDI lookup name that resolves to the target
141: * web service reference.
142: *
143: * @return portable JNDI lookup name
144: * @since 1.7, JAX-WS 2.2
145: */
146: String lookup() default "";
147:
148: }