1 /*
2 * Copyright 2005-2006 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package javax.xml.ws;
27
28 import javax.xml.namespace.QName;
29 import java.util.Iterator;
30 import javax.xml.ws.handler.HandlerResolver;
31 import javax.xml.bind.JAXBContext;
32 import javax.xml.ws.spi.ServiceDelegate;
33 import javax.xml.ws.spi.Provider;
34
35 /**
36 * <code>Service</code> objects provide the client view of a Web service.
37 * <p><code>Service</code> acts as a factory of the following:
38 * <ul>
39 * <li>Proxies for a target service endpoint.
40 * <li>Instances of <code>javax.xml.ws.Dispatch</code> for
41 * dynamic message-oriented invocation of a remote
42 * operation.
43 * </li>
44 *
45 * <p>The ports available on a service can be enumerated using the
46 * <code>getPorts</code> method. Alternatively, you can pass a
47 * service endpoint interface to the unary <code>getPort</code> method
48 * and let the runtime select a compatible port.
49 *
50 * <p>Handler chains for all the objects created by a <code>Service</code>
51 * can be set by means of a <code>HandlerResolver</code>.
52 *
53 * <p>An <code>Executor</code> may be set on the service in order
54 * to gain better control over the threads used to dispatch asynchronous
55 * callbacks. For instance, thread pooling with certain parameters
56 * can be enabled by creating a <code>ThreadPoolExecutor</code> and
57 * registering it with the service.
58 *
59 * @since JAX-WS 2.0
60 *
61 * @see javax.xml.ws.spi.Provider
62 * @see javax.xml.ws.handler.HandlerResolver
63 * @see java.util.concurrent.Executor
64 **/
65 public class Service {
66
67 private ServiceDelegate delegate;
68 /**
69 * The orientation of a dynamic client or service. MESSAGE provides
70 * access to entire protocol message, PAYLOAD to protocol message
71 * payload only.
72 **/
73 public enum Mode { MESSAGE, PAYLOAD };
74
75 protected Service(java.net.URL wsdlDocumentLocation, QName serviceName)
76 {
77 delegate = Provider.provider().createServiceDelegate(wsdlDocumentLocation,
78 serviceName,
79 this.getClass());
80 }
81
82
83 /** The getPort method returns a stub. A service client
84 * uses this stub to invoke operations on the target
85 * service endpoint. The <code>serviceEndpointInterface</code>
86 * specifies the service endpoint interface that is supported by
87 * the created dynamic proxy or stub instance.
88 *
89 * @param portName Qualified name of the service endpoint in
90 * the WSDL service description
91 * @param serviceEndpointInterface Service endpoint interface
92 * supported by the dynamic proxy or stub
93 * instance
94 * @return Object Proxy instance that
95 * supports the specified service endpoint
96 * interface
97 * @throws WebServiceException This exception is thrown in the
98 * following cases:
99 * <UL>
100 * <LI>If there is an error in creation of
101 * the proxy
102 * <LI>If there is any missing WSDL metadata
103 * as required by this method
104 * <LI>Optionally, if an illegal
105 * <code>serviceEndpointInterface</code>
106 * or <code>portName</code> is specified
107 * </UL>
108 * @see java.lang.reflect.Proxy
109 * @see java.lang.reflect.InvocationHandler
110 **/
111 public <T> T getPort(QName portName,
112 Class<T> serviceEndpointInterface)
113 {
114 return delegate.getPort(portName, serviceEndpointInterface);
115 }
116
117 /** The getPort method returns a stub. The parameter
118 * <code>serviceEndpointInterface</code> specifies the service
119 * endpoint interface that is supported by the returned proxy.
120 * In the implementation of this method, the JAX-WS
121 * runtime system takes the responsibility of selecting a protocol
122 * binding (and a port) and configuring the proxy accordingly.
123 * The returned proxy should not be reconfigured by the client.
124 *
125 * @param serviceEndpointInterface Service endpoint interface
126 * @return Object instance that supports the
127 * specified service endpoint interface
128 * @throws WebServiceException
129 * <UL>
130 * <LI>If there is an error during creation
131 * of the proxy
132 * <LI>If there is any missing WSDL metadata
133 * as required by this method
134 * <LI>Optionally, if an illegal
135 * <code>serviceEndpointInterface</code>
136 * is specified
137 * </UL>
138 **/
139 public <T> T getPort(Class<T> serviceEndpointInterface) {
140 return delegate.getPort(serviceEndpointInterface);
141 }
142
143 /** Creates a new port for the service. Ports created in this way contain
144 * no WSDL port type information and can only be used for creating
145 * <code>Dispatch</code>instances.
146 *
147 * @param portName Qualified name for the target service endpoint
148 * @param bindingId A String identifier of a binding.
149 * @param endpointAddress Address of the target service endpoint as a URI
150 * @throws WebServiceException If any error in the creation of
151 * the port
152 *
153 * @see javax.xml.ws.soap.SOAPBinding#SOAP11HTTP_BINDING
154 * @see javax.xml.ws.soap.SOAPBinding#SOAP12HTTP_BINDING
155 * @see javax.xml.ws.http.HTTPBinding#HTTP_BINDING
156 **/
157 public void addPort(QName portName, String bindingId, String endpointAddress)
158 {
159 delegate.addPort(portName, bindingId, endpointAddress);
160 }
161
162 /** Creates a <code>Dispatch</code> instance for use with objects of
163 * the users choosing.
164 *
165 * @param portName Qualified name for the target service endpoint
166 * @param type The class of object used to messages or message
167 * payloads. Implementations are required to support
168 * <code>javax.xml.transform.Source</code>, <code>javax.xml.soap.SOAPMessage</code>
169 * and <code>javax.activation.DataSource</code>, depending on
170 * the binding in use.
171 * @param mode Controls whether the created dispatch instance is message
172 * or payload oriented, i.e. whether the user will work with complete
173 * protocol messages or message payloads. E.g. when using the SOAP
174 * protocol, this parameter controls whether the user will work with
175 * SOAP messages or the contents of a SOAP body. Mode must be MESSAGE
176 * when type is SOAPMessage.
177 *
178 * @return Dispatch instance
179 * @throws WebServiceException If any error in the creation of
180 * the <code>Dispatch</code> object
181 * @see javax.xml.transform.Source
182 * @see javax.xml.soap.SOAPMessage
183 **/
184 public <T> Dispatch<T> createDispatch(QName portName, Class<T> type, Mode mode)
185 {
186 return delegate.createDispatch(portName, type, mode);
187 }
188
189 /** Creates a <code>Dispatch</code> instance for use with JAXB
190 * generated objects.
191 *
192 * @param portName Qualified name for the target service endpoint
193 * @param context The JAXB context used to marshall and unmarshall
194 * messages or message payloads.
195 * @param mode Controls whether the created dispatch instance is message
196 * or payload oriented, i.e. whether the user will work with complete
197 * protocol messages or message payloads. E.g. when using the SOAP
198 * protocol, this parameter controls whether the user will work with
199 * SOAP messages or the contents of a SOAP body.
200 *
201 * @return Dispatch instance
202 * @throws ServiceException If any error in the creation of
203 * the <code>Dispatch</code> object
204 *
205 * @see javax.xml.bind.JAXBContext
206 **/
207 public Dispatch<Object> createDispatch(QName portName, JAXBContext context,
208 Mode mode)
209 {
210 return delegate.createDispatch(portName, context, mode);
211 }
212
213
214
215 /** Gets the name of this service.
216 * @return Qualified name of this service
217 **/
218 public QName getServiceName() {
219 return delegate.getServiceName();
220 }
221
222 /** Returns an <code>Iterator</code> for the list of
223 * <code>QName</code>s of service endpoints grouped by this
224 * service
225 *
226 * @return Returns <code>java.util.Iterator</code> with elements
227 * of type <code>javax.xml.namespace.QName</code>
228 * @throws WebServiceException If this Service class does not
229 * have access to the required WSDL metadata
230 **/
231 public Iterator<javax.xml.namespace.QName> getPorts() {
232 return delegate.getPorts();
233 }
234
235 /** Gets the location of the WSDL document for this Service.
236 *
237 * @return URL for the location of the WSDL document for
238 * this service
239 **/
240 public java.net.URL getWSDLDocumentLocation() {
241 return delegate.getWSDLDocumentLocation();
242 }
243
244 /**
245 * Returns the configured handler resolver.
246 *
247 * @return HandlerResolver The <code>HandlerResolver</code> being
248 * used by this <code>Service</code> instance, or <code>null</code>
249 * if there isn't one.
250 **/
251 public HandlerResolver getHandlerResolver() {
252 return delegate.getHandlerResolver();
253 }
254
255 /**
256 * Sets the <code>HandlerResolver</code> for this <code>Service</code>
257 * instance.
258 * <p>
259 * The handler resolver, if present, will be called once for each
260 * proxy or dispatch instance that is created, and the handler chain
261 * returned by the resolver will be set on the instance.
262 *
263 * @param handlerResolver The <code>HandlerResolver</code> to use
264 * for all subsequently created proxy/dispatch objects.
265 *
266 * @see javax.xml.ws.handler.HandlerResolver
267 **/
268 public void setHandlerResolver(HandlerResolver handlerResolver) {
269 delegate.setHandlerResolver(handlerResolver);
270 }
271
272 /**
273 * Returns the executor for this <code>Service</code>instance.
274 *
275 * The executor is used for all asynchronous invocations that
276 * require callbacks.
277 *
278 * @return The <code>java.util.concurrent.Executor</code> to be
279 * used to invoke a callback.
280 *
281 * @see java.util.concurrent.Executor
282 **/
283 public java.util.concurrent.Executor getExecutor() {
284 return delegate.getExecutor();
285 }
286
287 /**
288 * Sets the executor for this <code>Service</code> instance.
289 *
290 * The executor is used for all asynchronous invocations that
291 * require callbacks.
292 *
293 * @param executor The <code>java.util.concurrent.Executor</code>
294 * to be used to invoke a callback.
295 *
296 * @throws SecurityException If the instance does not support
297 * setting an executor for security reasons (e.g. the
298 * necessary permissions are missing).
299 *
300 * @see java.util.concurrent.Executor
301 **/
302 public void setExecutor(java.util.concurrent.Executor executor) {
303 delegate.setExecutor(executor);
304 }
305
306 /**
307 * Create a <code>Service</code> instance.
308 *
309 * The specified WSDL document location and service qualified name must
310 * uniquely identify a <code>wsdl:service</code> element.
311 *
312 * @param wsdlDocumentLocation URL for the WSDL document location
313 * for the service
314 * @param serviceName QName for the service
315 * @throws WebServiceException If any error in creation of the
316 * specified service
317 **/
318 public static Service create(
319 java.net.URL wsdlDocumentLocation,
320 QName serviceName)
321 {
322 return new Service(wsdlDocumentLocation, serviceName);
323 }
324
325 /**
326 * Create a <code>Service</code> instance.
327 *
328 * @param serviceName QName for the service
329 * @throws WebServiceException If any error in creation of the
330 * specified service
331 */
332 public static Service create(QName serviceName) {
333 return new Service(null, serviceName);
334 }
335 }
Save This Page