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