01: /*
02: * Copyright 2007 Sun Microsystems, Inc. All rights reserved.
03: * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
04: */
05:
06: package javax.xml.ws;
07:
08: import java.util.concurrent.Future;
09:
10: /** The <code>Dispatch</code> interface provides support
11: * for the dynamic invocation of a service endpoint operations. The
12: * <code>javax.xml.ws.Service</code>
13: * interface acts as a factory for the creation of <code>Dispatch</code>
14: * instances.
15: *
16: * @since JAX-WS 2.0
17: **/
18: public interface Dispatch<T> extends BindingProvider {
19:
20: /** Invoke a service operation synchronously.
21: *
22: * The client is responsible for ensuring that the <code>msg</code> object
23: * when marshalled is formed according to the requirements of the protocol
24: * binding in use.
25: *
26: * @param msg An object that will form the message or payload of
27: * the message used to invoke the operation.
28: * @return The response message or message payload to the
29: * operation invocation.
30: * @throws WebServiceException If a fault occurs during communication with
31: * the service
32: * @throws WebServiceException If there is any error in the configuration of
33: * the <code>Dispatch</code> instance
34: **/
35: public T invoke(T msg);
36:
37: /** Invoke a service operation asynchronously. The
38: * method returns without waiting for the response to the operation
39: * invocation, the results of the operation are obtained by polling the
40: * returned <code>Response</code>.
41: * <p>
42: * The client is responsible for ensuring that the <code>msg</code> object
43: * when marshalled is formed according to the requirements of the protocol
44: * binding in use.
45: *
46: * @param msg An object that will form the message or payload of
47: * the message used to invoke the operation.
48: * @return The response message or message payload to the
49: * operation invocation.
50: * @throws WebServiceException If there is any error in the configuration of
51: * the <code>Dispatch</code> instance
52: **/
53: public Response<T> invokeAsync(T msg);
54:
55: /** Invoke a service operation asynchronously. The
56: * method returns without waiting for the response to the operation
57: * invocation, the results of the operation are communicated to the client
58: * via the passed in <code>handler</code>.
59: * <p>
60: * The client is responsible for ensuring that the <code>msg</code> object
61: * when marshalled is formed according to the requirements of the protocol
62: * binding in use.
63: *
64: * @param msg An object that will form the message or payload of
65: * the message used to invoke the operation.
66: * @param handler The handler object that will receive the
67: * response to the operation invocation.
68: * @return A <code>Future</code> object that may be used to check the status
69: * of the operation invocation. This object MUST NOT be used to try to
70: * obtain the results of the operation - the object returned from
71: * <code>Future<?>.get()</code> is implementation dependent
72: * and any use of it will result in non-portable behaviour.
73: * @throws WebServiceException If there is any error in the configuration of
74: * the <code>Dispatch</code> instance
75: **/
76: public Future<?> invokeAsync(T msg, AsyncHandler<T> handler);
77:
78: /** Invokes a service operation using the one-way
79: * interaction mode. The operation invocation is logically non-blocking,
80: * subject to the capabilities of the underlying protocol, no results
81: * are returned. When
82: * the protocol in use is SOAP/HTTP, this method MUST block until
83: * an HTTP response code has been received or an error occurs.
84: * <p>
85: * The client is responsible for ensuring that the <code>msg</code> object
86: * when marshalled is formed according to the requirements of the protocol
87: * binding in use.
88: *
89: * @param msg An object that will form the message or payload of
90: * the message used to invoke the operation.
91: * @throws WebServiceException If there is any error in the configuration of
92: * the <code>Dispatch</code> instance or if an error occurs during the
93: * invocation.
94: **/
95: public void invokeOneWay(T msg);
96: }
|