KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > xml > ws > spi > ServiceDelegate


1 /*
2  * Copyright 2007 Sun Microsystems, Inc. All rights reserved.
3  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
4  */

5
6 package javax.xml.ws.spi;
7
8 import java.util.Iterator JavaDoc;
9 import javax.xml.namespace.QName JavaDoc;
10 import javax.xml.ws.Dispatch;
11 import javax.xml.ws.Service;
12 import javax.xml.ws.handler.HandlerResolver;
13 import javax.xml.ws.WebServiceFeature;
14 import javax.xml.bind.JAXBContext;
15 import javax.xml.ws.EndpointReference;
16 import javax.xml.ws.WebServiceException;
17
18
19 /**
20  * Service delegates are used internally by <code>Service</code> objects
21  * to allow pluggability of JAX-WS implementations.
22  * <p>
23  * Every <code>Service</code> object has its own delegate, created using
24  * the {@link javax.xml.ws.spi.Provider#createServiceDelegate} method. A <code>Service</code>
25  * object delegates all of its instance methods to its delegate.
26  *
27  * @see javax.xml.ws.Service
28  * @see javax.xml.ws.spi.Provider
29  *
30  * @since JAX-WS 2.0
31  */

32 public abstract class ServiceDelegate {
33     
34     protected ServiceDelegate() {
35     }
36     
37     /**
38      * The <code>getPort</code> method returns a proxy. A service client
39      * uses this proxy to invoke operations on the target
40      * service endpoint. The <code>serviceEndpointInterface</code>
41      * specifies the service endpoint interface that is supported by
42      * the created dynamic proxy instance.
43      *
44      * @param portName Qualified name of the service endpoint in
45      * the WSDL service description
46      * @param serviceEndpointInterface Service endpoint interface
47      * supported by the dynamic proxy
48      * @return Object Proxy instance that
49      * supports the specified service endpoint
50      * interface
51      * @throws WebServiceException This exception is thrown in the
52      * following cases:
53      * <UL>
54      * <LI>If there is an error in creation of
55      * the proxy
56      * <LI>If there is any missing WSDL metadata
57      * as required by this method
58      * <LI>If an illegal
59      * <code>serviceEndpointInterface</code>
60      * or <code>portName</code> is specified
61      * </UL>
62      * @see java.lang.reflect.Proxy
63      * @see java.lang.reflect.InvocationHandler
64      **/

65     public abstract <T> T getPort(QName JavaDoc portName,
66             Class JavaDoc<T> serviceEndpointInterface);
67     
68     /**
69      * The <code>getPort</code> method returns a proxy. A service client
70      * uses this proxy to invoke operations on the target
71      * service endpoint. The <code>serviceEndpointInterface</code>
72      * specifies the service endpoint interface that is supported by
73      * the created dynamic proxy instance.
74      *
75      * @param portName Qualified name of the service endpoint in
76      * the WSDL service description
77      * @param serviceEndpointInterface Service endpoint interface
78      * supported by the dynamic proxy or instance
79      * @param features A list of WebServiceFeatures to configure on the
80      * proxy. Supported features not in the <code>features
81      * </code> parameter will have their default values.
82      * @return Object Proxy instance that
83      * supports the specified service endpoint
84      * interface
85      * @throws WebServiceException This exception is thrown in the
86      * following cases:
87      * <UL>
88      * <LI>If there is an error in creation of
89      * the proxy
90      * <LI>If there is any missing WSDL metadata
91      * as required by this method
92      * <LI>If an illegal
93      * <code>serviceEndpointInterface</code>
94      * or <code>portName</code> is specified
95      * <LI>If a feature is enabled that is not compatible
96      * with this port or is unsupported.
97      * </UL>
98      * @see java.lang.reflect.Proxy
99      * @see java.lang.reflect.InvocationHandler
100      * @see WebServiceFeature
101      *
102      * @since JAX-WS 2.1
103      **/

104     public abstract <T> T getPort(QName JavaDoc portName,
105             Class JavaDoc<T> serviceEndpointInterface, WebServiceFeature... features);
106     
107     /**
108      * The <code>getPort</code> method returns a proxy.
109      * The parameter <code>endpointReference</code> specifies the
110      * endpoint that will be invoked by the returned proxy. If there
111      * are any reference parameters in the
112      * <code>endpointReference</code>, then those reference
113      * parameters MUST appear as SOAP headers, indicating them to be
114      * reference parameters, on all messages sent to the endpoint.
115      * The <code>endpointReference's</code> address MUST be used
116      * for invocations on the endpoint.
117      * The parameter <code>serviceEndpointInterface</code> specifies
118      * the service endpoint interface that is supported by the
119      * 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 from
123      * the WSDL associated with this <code>Service</code> instance or
124      * from the metadata from the <code>endpointReference</code>.
125      * If this <code>Service</code> instance has a WSDL and
126      * the <code>endpointReference</code> metadata
127      * also has a WSDL, then the WSDL from this instance MUST be used.
128      * If this <code>Service</code> instance does not have a WSDL and
129      * the <code>endpointReference</code> does have a WSDL, then the
130      * WSDL from the <code>endpointReference</code> MAY be used.
131      * The returned proxy should not be reconfigured by the client.
132      * If this <code>Service</code> instance has a known proxy
133      * port that matches the information contained in
134      * the WSDL,
135      * then that proxy is returned, otherwise a WebServiceException
136      * is thrown.
137      * <p>
138      * Calling this method has the same behavior as the following
139      * <pre>
140      * <code>port = service.getPort(portName, serviceEndpointInterface);</code>
141      * </pre>
142      * where the <code>portName</code> is retrieved from the
143      * metadata of the <code>endpointReference</code> or from the
144      * <code>serviceEndpointInterface</code> and the WSDL
145      * associated with this <code>Service</code> instance.
146      *
147      * @param endpointReference The <code>EndpointReference</code>
148      * for the target service endpoint that will be invoked by the
149      * returned proxy.
150      * @param serviceEndpointInterface Service endpoint interface.
151      * @param features A list of <code>WebServiceFeatures</code> to configure on the
152      * proxy. Supported features not in the <code>features
153      * </code> parameter will have their default values.
154      * @return Object Proxy instance that supports the
155      * specified service endpoint interface.
156      * @throws WebServiceException
157      * <UL>
158      * <LI>If there is an error during creation
159      * of the proxy.
160      * <LI>If there is any missing WSDL metadata
161      * as required by this method.
162      * <LI>If the <code>endpointReference</code> metadata does
163      * not match the <code>serviceName</code> of this
164      * <code>Service</code> instance.
165      * <LI>If a <code>portName</code> cannot be extracted
166      * from the WSDL or <code>endpointReference</code> metadata.
167      * <LI>If an invalid
168      * <code>endpointReference</code>
169      * is specified.
170      * <LI>If an invalid
171      * <code>serviceEndpointInterface</code>
172      * is specified.
173      * <LI>If a feature is enabled that is not compatible
174      * with this port or is unsupported.
175      * </UL>
176      *
177      * @since JAX-WS 2.1
178      **/

179     public abstract <T> T getPort(EndpointReference endpointReference,
180            Class JavaDoc<T> serviceEndpointInterface, WebServiceFeature... features);
181
182     
183     /**
184      * The <code>getPort</code> method returns a proxy. The parameter
185      * <code>serviceEndpointInterface</code> specifies the service
186      * endpoint interface that is supported by the returned proxy.
187      * In the implementation of this method, the JAX-WS
188      * runtime system takes the responsibility of selecting a protocol
189      * binding (and a port) and configuring the proxy accordingly.
190      * The returned proxy should not be reconfigured by the client.
191      *
192      * @param serviceEndpointInterface Service endpoint interface
193      * @return Object instance that supports the
194      * specified service endpoint interface
195      * @throws WebServiceException
196      * <UL>
197      * <LI>If there is an error during creation
198      * of the proxy
199      * <LI>If there is any missing WSDL metadata
200      * as required by this method
201      * <LI>If an illegal
202      * <code>serviceEndpointInterface</code>
203      * is specified
204      * </UL>
205      **/

206     public abstract <T> T getPort(Class JavaDoc<T> serviceEndpointInterface);
207
208     
209     /**
210      * The <code>getPort</code> method returns a proxy. The parameter
211      * <code>serviceEndpointInterface</code> specifies the service
212      * endpoint interface that is supported by the returned proxy.
213      * In the implementation of this method, the JAX-WS
214      * runtime system takes the responsibility of selecting a protocol
215      * binding (and a port) and configuring the proxy accordingly.
216      * The returned proxy should not be reconfigured by the client.
217      *
218      * @param serviceEndpointInterface Service endpoint interface
219      * @param features An array of <code>WebServiceFeatures</code> to configure on the
220      * proxy. Supported features not in the <code>features
221      * </code> parameter will have their default values.
222      * @return Object instance that supports the
223      * specified service endpoint interface
224      * @throws WebServiceException
225      * <UL>
226      * <LI>If there is an error during creation
227      * of the proxy
228      * <LI>If there is any missing WSDL metadata
229      * as required by this method
230      * <LI>If an illegal
231      * <code>serviceEndpointInterface</code>
232      * is specified
233      * <LI>If a feature is enabled that is not compatible
234      * with this port or is unsupported.
235      * </UL>
236      *
237      * @see WebServiceFeature
238      *
239      * @since JAX-WS 2.1
240      **/

241     public abstract <T> T getPort(Class JavaDoc<T> serviceEndpointInterface,
242             WebServiceFeature... features);
243     
244     
245     /**
246      * Creates a new port for the service. Ports created in this way contain
247      * no WSDL port type information and can only be used for creating
248      * <code>Dispatch</code>instances.
249      *
250      * @param portName Qualified name for the target service endpoint
251      * @param bindingId A URI identifier of a binding.
252      * @param endpointAddress Address of the target service endpoint as a URI
253      * @throws WebServiceException If any error in the creation of
254      * the port
255      *
256      * @see javax.xml.ws.soap.SOAPBinding#SOAP11HTTP_BINDING
257      * @see javax.xml.ws.soap.SOAPBinding#SOAP12HTTP_BINDING
258      * @see javax.xml.ws.http.HTTPBinding#HTTP_BINDING
259      **/

260     public abstract void addPort(QName JavaDoc portName, String JavaDoc bindingId,
261             String JavaDoc endpointAddress);
262     
263    
264     
265     /**
266      * Creates a <code>Dispatch</code> instance for use with objects of
267      * the user's choosing.
268      *
269      * @param portName Qualified name for the target service endpoint
270      * @param type The class of object used for messages or message
271      * payloads. Implementations are required to support
272      * <code>javax.xml.transform.Source</code> and <code>javax.xml.soap.SOAPMessage</code>.
273      * @param mode Controls whether the created dispatch instance is message
274      * or payload oriented, i.e. whether the user will work with complete
275      * protocol messages or message payloads. E.g. when using the SOAP
276      * protocol, this parameter controls whether the user will work with
277      * SOAP messages or the contents of a SOAP body. Mode MUST be <code>MESSAGE</code>
278      * when type is <code>SOAPMessage</code>.
279      *
280      * @return Dispatch instance
281      * @throws WebServiceException If any error in the creation of
282      * the <code>Dispatch</code> object
283      * @see javax.xml.transform.Source
284      * @see javax.xml.soap.SOAPMessage
285      **/

286     public abstract <T> Dispatch<T> createDispatch(QName JavaDoc portName, Class JavaDoc<T> type,
287             Service.Mode mode);
288     
289     /**
290      * Creates a <code>Dispatch</code> instance for use with objects of
291      * the user's choosing.
292      *
293      * @param portName Qualified name for the target service endpoint
294      * @param type The class of object used for messages or message
295      * payloads. Implementations are required to support
296      * <code>javax.xml.transform.Source</code> and <code>javax.xml.soap.SOAPMessage</code>.
297      * @param mode Controls whether the created dispatch instance is message
298      * or payload oriented, i.e. whether the user will work with complete
299      * protocol messages or message payloads. E.g. when using the SOAP
300      * protocol, this parameter controls whether the user will work with
301      * SOAP messages or the contents of a SOAP body. Mode MUST be <code>MESSAGE</code>
302      * when type is <code>SOAPMessage</code>.
303      * @param features A list of <code>WebServiceFeatures</code> to configure on the
304      * proxy. Supported features not in the <code>features
305      * </code> parameter will have their default values.
306      *
307      * @return Dispatch instance
308      * @throws WebServiceException If any error in the creation of
309      * the <code>Dispatch</code> object or if a
310      * feature is enabled that is not compatible with
311      * this port or is unsupported.
312      *
313      * @see javax.xml.transform.Source
314      * @see javax.xml.soap.SOAPMessage
315      * @see WebServiceFeature
316      *
317      * @since JAX-WS 2.1
318      **/

319     public abstract <T> Dispatch<T> createDispatch(QName JavaDoc portName, Class JavaDoc<T> type,
320             Service.Mode mode, WebServiceFeature... features);
321     
322     /**
323      * Creates a <code>Dispatch</code> instance for use with objects of
324      * the user's choosing. If there
325      * are any reference parameters in the
326      * <code>endpointReference</code>, then those reference
327      * parameters MUST appear as SOAP headers, indicating them to be
328      * reference parameters, on all messages sent to the endpoint.
329      * The <code>endpointReference's</code> address MUST be used
330      * for invocations on the endpoint.
331      * In the implementation of this method, the JAX-WS
332      * runtime system takes the responsibility of selecting a protocol
333      * binding (and a port) and configuring the dispatch accordingly from
334      * the WSDL associated with this <code>Service</code> instance or
335      * from the metadata from the <code>endpointReference</code>.
336      * If this <code>Service</code> instance has a WSDL and
337      * the <code>endpointReference</code>
338      * also has a WSDL in its metadata, then the WSDL from this instance MUST be used.
339      * If this <code>Service</code> instance does not have a WSDL and
340      * the <code>endpointReference</code> does have a WSDL, then the
341      * WSDL from the <code>endpointReference</code> MAY be used.
342      * An implementation MUST be able to retrieve the <code>portName</code> from the
343      * <code>endpointReference</code> metadata.
344      * <p>
345      * This method behaves the same as calling
346      * <pre>
347      * <code>dispatch = service.createDispatch(portName, type, mode, features);</code>
348      * </pre>
349      * where the <code>portName</code> is retrieved from the
350      * WSDL or <code>EndpointReference</code> metadata.
351      *
352      * @param endpointReference The <code>EndpointReference</code>
353      * for the target service endpoint that will be invoked by the
354      * returned <code>Dispatch</code> object.
355      * @param type The class of object used to messages or message
356      * payloads. Implementations are required to support
357      * <code>javax.xml.transform.Source</code> and <code>javax.xml.soap.SOAPMessage</code>.
358      * @param mode Controls whether the created dispatch instance is message
359      * or payload oriented, i.e. whether the user will work with complete
360      * protocol messages or message payloads. E.g. when using the SOAP
361      * protocol, this parameter controls whether the user will work with
362      * SOAP messages or the contents of a SOAP body. Mode MUST be <code>MESSAGE</code>
363      * when type is <code>SOAPMessage</code>.
364      * @param features An array of <code>WebServiceFeatures</code> to configure on the
365      * proxy. Supported features not in the <code>features
366      * </code> parameter will have their default values.
367      *
368      * @return Dispatch instance
369      * @throws WebServiceException
370      * <UL>
371      * <LI>If there is any missing WSDL metadata
372      * as required by this method.
373      * <li>If the <code>endpointReference</code> metadata does
374      * not match the <code>serviceName</code> or <code>portName</code>
375      * of a WSDL associated
376      * with this <code>Service</code> instance.
377      * <li>If the <code>portName</code> cannot be determined
378      * from the <code>EndpointReference</code> metadata.
379      * <li>If any error in the creation of
380      * the <code>Dispatch</code> object.
381      * <li>If a feature is enabled that is not
382      * compatible with this port or is unsupported.
383      * </UL>
384      *
385      * @see javax.xml.transform.Source
386      * @see javax.xml.soap.SOAPMessage
387      * @see WebServiceFeature
388      *
389      * @since JAX-WS 2.1
390      **/

391     public abstract <T> Dispatch<T> createDispatch(EndpointReference endpointReference,
392             Class JavaDoc<T> type, Service.Mode mode,
393             WebServiceFeature... features);
394
395
396     
397     /**
398      * Creates a <code>Dispatch</code> instance for use with JAXB
399      * generated objects.
400      *
401      * @param portName Qualified name for the target service endpoint
402      * @param context The JAXB context used to marshall and unmarshall
403      * messages or message payloads.
404      * @param mode Controls whether the created dispatch instance is message
405      * or payload oriented, i.e. whether the user will work with complete
406      * protocol messages or message payloads. E.g. when using the SOAP
407      * protocol, this parameter controls whether the user will work with
408      * SOAP messages or the contents of a SOAP body.
409      *
410      * @return Dispatch instance
411      * @throws WebServiceException If any error in the creation of
412      * the <code>Dispatch</code> object
413      *
414      * @see javax.xml.bind.JAXBContext
415      **/

416     public abstract Dispatch<Object JavaDoc> createDispatch(QName JavaDoc portName,
417             JAXBContext context, Service.Mode mode);
418     
419
420     /**
421      * Creates a <code>Dispatch</code> instance for use with JAXB
422      * generated objects.
423      *
424      * @param portName Qualified name for the target service endpoint
425      * @param context The JAXB context used to marshall and unmarshall
426      * messages or message payloads.
427      * @param mode Controls whether the created dispatch instance is message
428      * or payload oriented, i.e. whether the user will work with complete
429      * protocol messages or message payloads. E.g. when using the SOAP
430      * protocol, this parameter controls whether the user will work with
431      * SOAP messages or the contents of a SOAP body.
432      * @param features A list of <code>WebServiceFeatures</code> to configure on the
433      * proxy. Supported features not in the <code>features
434      * </code> parameter will have their default values.
435      *
436      * @return Dispatch instance
437      * @throws WebServiceException If any error in the creation of
438      * the <code>Dispatch</code> object or if a
439      * feature is enabled that is not compatible with
440      * this port or is unsupported.
441      *
442      * @see javax.xml.bind.JAXBContext
443      * @see WebServiceFeature
444      *
445      * @since JAX-WS 2.1
446      **/

447     public abstract Dispatch<Object JavaDoc> createDispatch(QName JavaDoc portName,
448             JAXBContext context, Service.Mode mode, WebServiceFeature... features);
449    
450     /**
451      * Creates a <code>Dispatch</code> instance for use with JAXB
452      * generated objects. If there
453      * are any reference parameters in the
454      * <code>endpointReference</code>, then those reference
455      * parameters MUST appear as SOAP headers, indicating them to be
456      * reference parameters, on all messages sent to the endpoint.
457      * The <code>endpointReference's</code> address MUST be used
458      * for invocations on the endpoint.
459      * In the implementation of this method, the JAX-WS
460      * runtime system takes the responsibility of selecting a protocol
461      * binding (and a port) and configuring the dispatch accordingly from
462      * the WSDL associated with this <code>Service</code> instance or
463      * from the metadata from the <code>endpointReference</code>.
464      * If this <code>Service</code> instance has a WSDL and
465      * the <code>endpointReference</code>
466      * also has a WSDL in its metadata, then the WSDL from this instance
467      * MUST be used.
468      * If this <code>Service</code> instance does not have a WSDL and
469      * the <code>endpointReference</code> does have a WSDL, then the
470      * WSDL from the <code>endpointReference</code> MAY be used.
471      * An implementation MUST be able to retrieve the <code>portName</code> from the
472      * <code>endpointReference</code> metadata.
473      * <p>
474      * This method behavies the same as calling
475      * <pre>
476      * <code>dispatch = service.createDispatch(portName, context, mode, features);</code>
477      * </pre>
478      * where the <code>portName</code> is retrieved from the
479      * WSDL or <code>endpointReference</code> metadata.
480      *
481      * @param endpointReference The <code>EndpointReference</code>
482      * for the target service endpoint that will be invoked by the
483      * returned <code>Dispatch</code> object.
484      * @param context The JAXB context used to marshall and unmarshall
485      * messages or message payloads.
486      * @param mode Controls whether the created dispatch instance is message
487      * or payload oriented, i.e. whether the user will work with complete
488      * protocol messages or message payloads. E.g. when using the SOAP
489      * protocol, this parameter controls whether the user will work with
490      * SOAP messages or the contents of a SOAP body.
491      * @param features An array of <code>WebServiceFeatures</code> to configure on the
492      * proxy. Supported features not in the <code>features
493      * </code> parameter will have their default values.
494      *
495      * @return Dispatch instance
496      * @throws WebServiceException
497      * <UL>
498      * <li>If there is any missing WSDL metadata
499      * as required by this method.
500      * <li>If the <code>endpointReference</code> metadata does
501      * not match the <code>serviceName</code> or <code>portName</code>
502      * of a WSDL associated
503      * with this <code>Service</code> instance.
504      * <li>If the <code>portName</code> cannot be determined
505      * from the <code>EndpointReference</code> metadata.
506      * <li>If any error in the creation of
507      * the <code>Dispatch</code> object.
508      * <li>if a feature is enabled that is not
509      * compatible with this port or is unsupported.
510      * </UL>
511      *
512      * @see javax.xml.bind.JAXBContext
513      * @see WebServiceFeature
514      *
515      * @since JAX-WS 2.1
516     **/

517     public abstract Dispatch<Object JavaDoc> createDispatch(EndpointReference endpointReference,
518             JAXBContext context, Service.Mode mode,
519             WebServiceFeature... features);
520         
521     
522     /**
523      * Gets the name of this service.
524      * @return Qualified name of this service
525      **/

526     public abstract QName JavaDoc getServiceName();
527     
528     /**
529      * Returns an <code>Iterator</code> for the list of
530      * <code>QName</code>s of service endpoints grouped by this
531      * service
532      *
533      * @return Returns <code>java.util.Iterator</code> with elements
534      * of type <code>javax.xml.namespace.QName</code>
535      * @throws WebServiceException If this Service class does not
536      * have access to the required WSDL metadata
537      **/

538     public abstract Iterator JavaDoc<javax.xml.namespace.QName JavaDoc> getPorts();
539     
540     /**
541      * Gets the location of the WSDL document for this Service.
542      *
543      * @return URL for the location of the WSDL document for
544      * this service
545      **/

546     public abstract java.net.URL JavaDoc getWSDLDocumentLocation();
547     
548     /**
549      * Returns the configured handler resolver.
550      *
551      * @return HandlerResolver The <code>HandlerResolver</code> being
552      * used by this <code>Service</code> instance, or <code>null</code>
553      * if there isn't one.
554      **/

555     public abstract HandlerResolver getHandlerResolver();
556     
557     /**
558      * Sets the <code>HandlerResolver</code> for this <code>Service</code>
559      * instance.
560      * <p>
561      * The handler resolver, if present, will be called once for each
562      * proxy or dispatch instance that is created, and the handler chain
563      * returned by the resolver will be set on the instance.
564      *
565      * @param handlerResolver The <code>HandlerResolver</code> to use
566      * for all subsequently created proxy/dispatch objects.
567      *
568      * @see javax.xml.ws.handler.HandlerResolver
569      **/

570     public abstract void setHandlerResolver(HandlerResolver handlerResolver);
571     
572     /**
573      * Returns the executor for this <code>Service</code>instance.
574      *
575      * The executor is used for all asynchronous invocations that
576      * require callbacks.
577      *
578      * @return The <code>java.util.concurrent.Executor</code> to be
579      * used to invoke a callback.
580      *
581      * @see java.util.concurrent.Executor
582      **/

583     public abstract java.util.concurrent.Executor JavaDoc getExecutor();
584     
585     /**
586      * Sets the executor for this <code>Service</code> instance.
587      *
588      * The executor is used for all asynchronous invocations that
589      * require callbacks.
590      *
591      * @param executor The <code>java.util.concurrent.Executor</code>
592      * to be used to invoke a callback.
593      *
594      * @throws SecurityException If the instance does not support
595      * setting an executor for security reasons (e.g. the
596      * necessary permissions are missing).
597      *
598      * @see java.util.concurrent.Executor
599      **/

600     public abstract void setExecutor(java.util.concurrent.Executor JavaDoc executor);
601     
602 }
603
Popular Tags