001: /*
002: * Copyright 2007 Sun Microsystems, Inc. All rights reserved.
003: * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
004: */
005:
006: package javax.xml.ws.spi;
007:
008: import java.util.Iterator;
009: import javax.xml.namespace.QName;
010: import javax.xml.ws.Dispatch;
011: import javax.xml.ws.Service;
012: import javax.xml.ws.handler.HandlerResolver;
013: import javax.xml.ws.WebServiceFeature;
014: import javax.xml.bind.JAXBContext;
015: import javax.xml.ws.EndpointReference;
016: import javax.xml.ws.WebServiceException;
017:
018: /**
019: * Service delegates are used internally by <code>Service</code> objects
020: * to allow pluggability of JAX-WS implementations.
021: * <p>
022: * Every <code>Service</code> object has its own delegate, created using
023: * the {@link javax.xml.ws.spi.Provider#createServiceDelegate} method. A <code>Service</code>
024: * object delegates all of its instance methods to its delegate.
025: *
026: * @see javax.xml.ws.Service
027: * @see javax.xml.ws.spi.Provider
028: *
029: * @since JAX-WS 2.0
030: */
031: public abstract class ServiceDelegate {
032:
033: protected ServiceDelegate() {
034: }
035:
036: /**
037: * The <code>getPort</code> method returns a proxy. A service client
038: * uses this proxy to invoke operations on the target
039: * service endpoint. The <code>serviceEndpointInterface</code>
040: * specifies the service endpoint interface that is supported by
041: * the created dynamic proxy instance.
042: *
043: * @param portName Qualified name of the service endpoint in
044: * the WSDL service description
045: * @param serviceEndpointInterface Service endpoint interface
046: * supported by the dynamic proxy
047: * @return Object Proxy instance that
048: * supports the specified service endpoint
049: * interface
050: * @throws WebServiceException This exception is thrown in the
051: * following cases:
052: * <UL>
053: * <LI>If there is an error in creation of
054: * the proxy
055: * <LI>If there is any missing WSDL metadata
056: * as required by this method
057: * <LI>If an illegal
058: * <code>serviceEndpointInterface</code>
059: * or <code>portName</code> is specified
060: * </UL>
061: * @see java.lang.reflect.Proxy
062: * @see java.lang.reflect.InvocationHandler
063: **/
064: public abstract <T> T getPort(QName portName,
065: Class<T> serviceEndpointInterface);
066:
067: /**
068: * The <code>getPort</code> method returns a proxy. A service client
069: * uses this proxy to invoke operations on the target
070: * service endpoint. The <code>serviceEndpointInterface</code>
071: * specifies the service endpoint interface that is supported by
072: * the created dynamic proxy instance.
073: *
074: * @param portName Qualified name of the service endpoint in
075: * the WSDL service description
076: * @param serviceEndpointInterface Service endpoint interface
077: * supported by the dynamic proxy or instance
078: * @param features A list of WebServiceFeatures to configure on the
079: * proxy. Supported features not in the <code>features
080: * </code> parameter will have their default values.
081: * @return Object Proxy instance that
082: * supports the specified service endpoint
083: * interface
084: * @throws WebServiceException This exception is thrown in the
085: * following cases:
086: * <UL>
087: * <LI>If there is an error in creation of
088: * the proxy
089: * <LI>If there is any missing WSDL metadata
090: * as required by this method
091: * <LI>If an illegal
092: * <code>serviceEndpointInterface</code>
093: * or <code>portName</code> is specified
094: * <LI>If a feature is enabled that is not compatible
095: * with this port or is unsupported.
096: * </UL>
097: * @see java.lang.reflect.Proxy
098: * @see java.lang.reflect.InvocationHandler
099: * @see WebServiceFeature
100: *
101: * @since JAX-WS 2.1
102: **/
103: public abstract <T> T getPort(QName portName,
104: Class<T> serviceEndpointInterface,
105: 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<T> serviceEndpointInterface,
181: WebServiceFeature... features);
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<T> serviceEndpointInterface);
207:
208: /**
209: * The <code>getPort</code> method returns a proxy. The parameter
210: * <code>serviceEndpointInterface</code> specifies the service
211: * endpoint interface that is supported by the returned proxy.
212: * In the implementation of this method, the JAX-WS
213: * runtime system takes the responsibility of selecting a protocol
214: * binding (and a port) and configuring the proxy accordingly.
215: * The returned proxy should not be reconfigured by the client.
216: *
217: * @param serviceEndpointInterface Service endpoint interface
218: * @param features An array of <code>WebServiceFeatures</code> to configure on the
219: * proxy. Supported features not in the <code>features
220: * </code> parameter will have their default values.
221: * @return Object instance that supports the
222: * specified service endpoint interface
223: * @throws WebServiceException
224: * <UL>
225: * <LI>If there is an error during creation
226: * of the proxy
227: * <LI>If there is any missing WSDL metadata
228: * as required by this method
229: * <LI>If an illegal
230: * <code>serviceEndpointInterface</code>
231: * is specified
232: * <LI>If a feature is enabled that is not compatible
233: * with this port or is unsupported.
234: * </UL>
235: *
236: * @see WebServiceFeature
237: *
238: * @since JAX-WS 2.1
239: **/
240: public abstract <T> T getPort(Class<T> serviceEndpointInterface,
241: WebServiceFeature... features);
242:
243: /**
244: * Creates a new port for the service. Ports created in this way contain
245: * no WSDL port type information and can only be used for creating
246: * <code>Dispatch</code>instances.
247: *
248: * @param portName Qualified name for the target service endpoint
249: * @param bindingId A URI identifier of a binding.
250: * @param endpointAddress Address of the target service endpoint as a URI
251: * @throws WebServiceException If any error in the creation of
252: * the port
253: *
254: * @see javax.xml.ws.soap.SOAPBinding#SOAP11HTTP_BINDING
255: * @see javax.xml.ws.soap.SOAPBinding#SOAP12HTTP_BINDING
256: * @see javax.xml.ws.http.HTTPBinding#HTTP_BINDING
257: **/
258: public abstract void addPort(QName portName, String bindingId,
259: String endpointAddress);
260:
261: /**
262: * Creates a <code>Dispatch</code> instance for use with objects of
263: * the user's choosing.
264: *
265: * @param portName Qualified name for the target service endpoint
266: * @param type The class of object used for messages or message
267: * payloads. Implementations are required to support
268: * <code>javax.xml.transform.Source</code> and <code>javax.xml.soap.SOAPMessage</code>.
269: * @param mode Controls whether the created dispatch instance is message
270: * or payload oriented, i.e. whether the user will work with complete
271: * protocol messages or message payloads. E.g. when using the SOAP
272: * protocol, this parameter controls whether the user will work with
273: * SOAP messages or the contents of a SOAP body. Mode MUST be <code>MESSAGE</code>
274: * when type is <code>SOAPMessage</code>.
275: *
276: * @return Dispatch instance
277: * @throws WebServiceException If any error in the creation of
278: * the <code>Dispatch</code> object
279: * @see javax.xml.transform.Source
280: * @see javax.xml.soap.SOAPMessage
281: **/
282: public abstract <T> Dispatch<T> createDispatch(QName portName,
283: Class<T> type, Service.Mode mode);
284:
285: /**
286: * Creates a <code>Dispatch</code> instance for use with objects of
287: * the user's choosing.
288: *
289: * @param portName Qualified name for the target service endpoint
290: * @param type The class of object used for messages or message
291: * payloads. Implementations are required to support
292: * <code>javax.xml.transform.Source</code> and <code>javax.xml.soap.SOAPMessage</code>.
293: * @param mode Controls whether the created dispatch instance is message
294: * or payload oriented, i.e. whether the user will work with complete
295: * protocol messages or message payloads. E.g. when using the SOAP
296: * protocol, this parameter controls whether the user will work with
297: * SOAP messages or the contents of a SOAP body. Mode MUST be <code>MESSAGE</code>
298: * when type is <code>SOAPMessage</code>.
299: * @param features A list of <code>WebServiceFeatures</code> to configure on the
300: * proxy. Supported features not in the <code>features
301: * </code> parameter will have their default values.
302: *
303: * @return Dispatch instance
304: * @throws WebServiceException If any error in the creation of
305: * the <code>Dispatch</code> object or if a
306: * feature is enabled that is not compatible with
307: * this port or is unsupported.
308: *
309: * @see javax.xml.transform.Source
310: * @see javax.xml.soap.SOAPMessage
311: * @see WebServiceFeature
312: *
313: * @since JAX-WS 2.1
314: **/
315: public abstract <T> Dispatch<T> createDispatch(QName portName,
316: Class<T> type, Service.Mode mode,
317: WebServiceFeature... features);
318:
319: /**
320: * Creates a <code>Dispatch</code> instance for use with objects of
321: * the user's choosing. If there
322: * are any reference parameters in the
323: * <code>endpointReference</code>, then those reference
324: * parameters MUST appear as SOAP headers, indicating them to be
325: * reference parameters, on all messages sent to the endpoint.
326: * The <code>endpointReference's</code> address MUST be used
327: * for invocations on the endpoint.
328: * In the implementation of this method, the JAX-WS
329: * runtime system takes the responsibility of selecting a protocol
330: * binding (and a port) and configuring the dispatch accordingly from
331: * the WSDL associated with this <code>Service</code> instance or
332: * from the metadata from the <code>endpointReference</code>.
333: * If this <code>Service</code> instance has a WSDL and
334: * the <code>endpointReference</code>
335: * also has a WSDL in its metadata, then the WSDL from this instance MUST be used.
336: * If this <code>Service</code> instance does not have a WSDL and
337: * the <code>endpointReference</code> does have a WSDL, then the
338: * WSDL from the <code>endpointReference</code> MAY be used.
339: * An implementation MUST be able to retrieve the <code>portName</code> from the
340: * <code>endpointReference</code> metadata.
341: * <p>
342: * This method behaves the same as calling
343: * <pre>
344: * <code>dispatch = service.createDispatch(portName, type, mode, features);</code>
345: * </pre>
346: * where the <code>portName</code> is retrieved from the
347: * WSDL or <code>EndpointReference</code> metadata.
348: *
349: * @param endpointReference The <code>EndpointReference</code>
350: * for the target service endpoint that will be invoked by the
351: * returned <code>Dispatch</code> object.
352: * @param type The class of object used to messages or message
353: * payloads. Implementations are required to support
354: * <code>javax.xml.transform.Source</code> and <code>javax.xml.soap.SOAPMessage</code>.
355: * @param mode Controls whether the created dispatch instance is message
356: * or payload oriented, i.e. whether the user will work with complete
357: * protocol messages or message payloads. E.g. when using the SOAP
358: * protocol, this parameter controls whether the user will work with
359: * SOAP messages or the contents of a SOAP body. Mode MUST be <code>MESSAGE</code>
360: * when type is <code>SOAPMessage</code>.
361: * @param features An array of <code>WebServiceFeatures</code> to configure on the
362: * proxy. Supported features not in the <code>features
363: * </code> parameter will have their default values.
364: *
365: * @return Dispatch instance
366: * @throws WebServiceException
367: * <UL>
368: * <LI>If there is any missing WSDL metadata
369: * as required by this method.
370: * <li>If the <code>endpointReference</code> metadata does
371: * not match the <code>serviceName</code> or <code>portName</code>
372: * of a WSDL associated
373: * with this <code>Service</code> instance.
374: * <li>If the <code>portName</code> cannot be determined
375: * from the <code>EndpointReference</code> metadata.
376: * <li>If any error in the creation of
377: * the <code>Dispatch</code> object.
378: * <li>If a feature is enabled that is not
379: * compatible with this port or is unsupported.
380: * </UL>
381: *
382: * @see javax.xml.transform.Source
383: * @see javax.xml.soap.SOAPMessage
384: * @see WebServiceFeature
385: *
386: * @since JAX-WS 2.1
387: **/
388: public abstract <T> Dispatch<T> createDispatch(
389: EndpointReference endpointReference, Class<T> type,
390: Service.Mode mode, WebServiceFeature... features);
391:
392: /**
393: * Creates a <code>Dispatch</code> instance for use with JAXB
394: * generated objects.
395: *
396: * @param portName Qualified name for the target service endpoint
397: * @param context The JAXB context used to marshall and unmarshall
398: * messages or message payloads.
399: * @param mode Controls whether the created dispatch instance is message
400: * or payload oriented, i.e. whether the user will work with complete
401: * protocol messages or message payloads. E.g. when using the SOAP
402: * protocol, this parameter controls whether the user will work with
403: * SOAP messages or the contents of a SOAP body.
404: *
405: * @return Dispatch instance
406: * @throws WebServiceException If any error in the creation of
407: * the <code>Dispatch</code> object
408: *
409: * @see javax.xml.bind.JAXBContext
410: **/
411: public abstract Dispatch<Object> createDispatch(QName portName,
412: JAXBContext context, Service.Mode mode);
413:
414: /**
415: * Creates a <code>Dispatch</code> instance for use with JAXB
416: * generated objects.
417: *
418: * @param portName Qualified name for the target service endpoint
419: * @param context The JAXB context used to marshall and unmarshall
420: * messages or message payloads.
421: * @param mode Controls whether the created dispatch instance is message
422: * or payload oriented, i.e. whether the user will work with complete
423: * protocol messages or message payloads. E.g. when using the SOAP
424: * protocol, this parameter controls whether the user will work with
425: * SOAP messages or the contents of a SOAP body.
426: * @param features A list of <code>WebServiceFeatures</code> to configure on the
427: * proxy. Supported features not in the <code>features
428: * </code> parameter will have their default values.
429: *
430: * @return Dispatch instance
431: * @throws WebServiceException If any error in the creation of
432: * the <code>Dispatch</code> object or if a
433: * feature is enabled that is not compatible with
434: * this port or is unsupported.
435: *
436: * @see javax.xml.bind.JAXBContext
437: * @see WebServiceFeature
438: *
439: * @since JAX-WS 2.1
440: **/
441: public abstract Dispatch<Object> createDispatch(QName portName,
442: JAXBContext context, Service.Mode mode,
443: WebServiceFeature... features);
444:
445: /**
446: * Creates a <code>Dispatch</code> instance for use with JAXB
447: * generated objects. If there
448: * are any reference parameters in the
449: * <code>endpointReference</code>, then those reference
450: * parameters MUST appear as SOAP headers, indicating them to be
451: * reference parameters, on all messages sent to the endpoint.
452: * The <code>endpointReference's</code> address MUST be used
453: * for invocations on the endpoint.
454: * In the implementation of this method, the JAX-WS
455: * runtime system takes the responsibility of selecting a protocol
456: * binding (and a port) and configuring the dispatch accordingly from
457: * the WSDL associated with this <code>Service</code> instance or
458: * from the metadata from the <code>endpointReference</code>.
459: * If this <code>Service</code> instance has a WSDL and
460: * the <code>endpointReference</code>
461: * also has a WSDL in its metadata, then the WSDL from this instance
462: * MUST be used.
463: * If this <code>Service</code> instance does not have a WSDL and
464: * the <code>endpointReference</code> does have a WSDL, then the
465: * WSDL from the <code>endpointReference</code> MAY be used.
466: * An implementation MUST be able to retrieve the <code>portName</code> from the
467: * <code>endpointReference</code> metadata.
468: * <p>
469: * This method behavies the same as calling
470: * <pre>
471: * <code>dispatch = service.createDispatch(portName, context, mode, features);</code>
472: * </pre>
473: * where the <code>portName</code> is retrieved from the
474: * WSDL or <code>endpointReference</code> metadata.
475: *
476: * @param endpointReference The <code>EndpointReference</code>
477: * for the target service endpoint that will be invoked by the
478: * returned <code>Dispatch</code> object.
479: * @param context The JAXB context used to marshall and unmarshall
480: * messages or message payloads.
481: * @param mode Controls whether the created dispatch instance is message
482: * or payload oriented, i.e. whether the user will work with complete
483: * protocol messages or message payloads. E.g. when using the SOAP
484: * protocol, this parameter controls whether the user will work with
485: * SOAP messages or the contents of a SOAP body.
486: * @param features An array of <code>WebServiceFeatures</code> to configure on the
487: * proxy. Supported features not in the <code>features
488: * </code> parameter will have their default values.
489: *
490: * @return Dispatch instance
491: * @throws WebServiceException
492: * <UL>
493: * <li>If there is any missing WSDL metadata
494: * as required by this method.
495: * <li>If the <code>endpointReference</code> metadata does
496: * not match the <code>serviceName</code> or <code>portName</code>
497: * of a WSDL associated
498: * with this <code>Service</code> instance.
499: * <li>If the <code>portName</code> cannot be determined
500: * from the <code>EndpointReference</code> metadata.
501: * <li>If any error in the creation of
502: * the <code>Dispatch</code> object.
503: * <li>if a feature is enabled that is not
504: * compatible with this port or is unsupported.
505: * </UL>
506: *
507: * @see javax.xml.bind.JAXBContext
508: * @see WebServiceFeature
509: *
510: * @since JAX-WS 2.1
511: **/
512: public abstract Dispatch<Object> createDispatch(
513: EndpointReference endpointReference, JAXBContext context,
514: Service.Mode mode, WebServiceFeature... features);
515:
516: /**
517: * Gets the name of this service.
518: * @return Qualified name of this service
519: **/
520: public abstract QName getServiceName();
521:
522: /**
523: * Returns an <code>Iterator</code> for the list of
524: * <code>QName</code>s of service endpoints grouped by this
525: * service
526: *
527: * @return Returns <code>java.util.Iterator</code> with elements
528: * of type <code>javax.xml.namespace.QName</code>
529: * @throws WebServiceException If this Service class does not
530: * have access to the required WSDL metadata
531: **/
532: public abstract Iterator<javax.xml.namespace.QName> getPorts();
533:
534: /**
535: * Gets the location of the WSDL document for this Service.
536: *
537: * @return URL for the location of the WSDL document for
538: * this service
539: **/
540: public abstract java.net.URL getWSDLDocumentLocation();
541:
542: /**
543: * Returns the configured handler resolver.
544: *
545: * @return HandlerResolver The <code>HandlerResolver</code> being
546: * used by this <code>Service</code> instance, or <code>null</code>
547: * if there isn't one.
548: **/
549: public abstract HandlerResolver getHandlerResolver();
550:
551: /**
552: * Sets the <code>HandlerResolver</code> for this <code>Service</code>
553: * instance.
554: * <p>
555: * The handler resolver, if present, will be called once for each
556: * proxy or dispatch instance that is created, and the handler chain
557: * returned by the resolver will be set on the instance.
558: *
559: * @param handlerResolver The <code>HandlerResolver</code> to use
560: * for all subsequently created proxy/dispatch objects.
561: *
562: * @see javax.xml.ws.handler.HandlerResolver
563: **/
564: public abstract void setHandlerResolver(
565: HandlerResolver handlerResolver);
566:
567: /**
568: * Returns the executor for this <code>Service</code>instance.
569: *
570: * The executor is used for all asynchronous invocations that
571: * require callbacks.
572: *
573: * @return The <code>java.util.concurrent.Executor</code> to be
574: * used to invoke a callback.
575: *
576: * @see java.util.concurrent.Executor
577: **/
578: public abstract java.util.concurrent.Executor getExecutor();
579:
580: /**
581: * Sets the executor for this <code>Service</code> instance.
582: *
583: * The executor is used for all asynchronous invocations that
584: * require callbacks.
585: *
586: * @param executor The <code>java.util.concurrent.Executor</code>
587: * to be used to invoke a callback.
588: *
589: * @throws SecurityException If the instance does not support
590: * setting an executor for security reasons (e.g. the
591: * necessary permissions are missing).
592: *
593: * @see java.util.concurrent.Executor
594: **/
595: public abstract void setExecutor(
596: java.util.concurrent.Executor executor);
597:
598: }
|