Package: Dispatch

Dispatch

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