Tue, 07 Nov 2017 18:54:04 -0800
Added tag jdk8u162-b06 for changeset 6095742f8034
1 /*
2 * Copyright (c) 2005, 2010, Oracle and/or its affiliates. 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. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
26 package javax.xml.ws;
28 import java.util.concurrent.Future;
30 /** The <code>Dispatch</code> interface provides support
31 * for the dynamic invocation of a service endpoint operations. The
32 * <code>javax.xml.ws.Service</code>
33 * class acts as a factory for the creation of <code>Dispatch</code>
34 * instances.
35 *
36 * @since JAX-WS 2.0
37 **/
38 public interface Dispatch<T> extends BindingProvider {
40 /** Invoke a service operation synchronously.
41 *
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 a fault occurs during communication with
51 * the service
52 * @throws WebServiceException If there is any error in the configuration of
53 * the <code>Dispatch</code> instance
54 **/
55 public T invoke(T msg);
57 /** Invoke a service operation asynchronously. The
58 * method returns without waiting for the response to the operation
59 * invocation, the results of the operation are obtained by polling the
60 * returned <code>Response</code>.
61 * <p>
62 * The client is responsible for ensuring that the <code>msg</code> object
63 * when marshalled is formed according to the requirements of the protocol
64 * binding in use.
65 *
66 * @param msg An object that will form the message or payload of
67 * the message used to invoke the operation.
68 * @return The response message or message payload to the
69 * operation invocation.
70 * @throws WebServiceException If there is any error in the configuration of
71 * the <code>Dispatch</code> instance
72 **/
73 public Response<T> invokeAsync(T msg);
75 /** Invoke a service operation asynchronously. The
76 * method returns without waiting for the response to the operation
77 * invocation, the results of the operation are communicated to the client
78 * via the passed in <code>handler</code>.
79 * <p>
80 * The client is responsible for ensuring that the <code>msg</code> object
81 * when marshalled is formed according to the requirements of the protocol
82 * binding in use.
83 *
84 * @param msg An object that will form the message or payload of
85 * the message used to invoke the operation.
86 * @param handler The handler object that will receive the
87 * response to the operation invocation.
88 * @return A <code>Future</code> object that may be used to check the status
89 * of the operation invocation. This object MUST NOT be used to try to
90 * obtain the results of the operation - the object returned from
91 * <code>Future<?>.get()</code> is implementation dependent
92 * and any use of it will result in non-portable behaviour.
93 * @throws WebServiceException If there is any error in the configuration of
94 * the <code>Dispatch</code> instance
95 **/
96 public Future<?> invokeAsync(T msg, AsyncHandler<T> handler);
98 /** Invokes a service operation using the one-way
99 * interaction mode. The operation invocation is logically non-blocking,
100 * subject to the capabilities of the underlying protocol, no results
101 * are returned. When
102 * the protocol in use is SOAP/HTTP, this method MUST block until
103 * an HTTP response code has been received or an error occurs.
104 * <p>
105 * The client is responsible for ensuring that the <code>msg</code> object
106 * when marshalled is formed according to the requirements of the protocol
107 * binding in use.
108 *
109 * @param msg An object that will form the message or payload of
110 * the message used to invoke the operation.
111 * @throws WebServiceException If there is any error in the configuration of
112 * the <code>Dispatch</code> instance or if an error occurs during the
113 * invocation.
114 **/
115 public void invokeOneWay(T msg);
116 }