1 /* 2 * Copyright (c) 2005, 2012, 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 /** The {@code Dispatch} interface provides support 31 * for the dynamic invocation of a service endpoint operations. The 32 * {@code javax.xml.ws.Service} 33 * class acts as a factory for the creation of {@code Dispatch} 34 * instances. 35 * 36 * @since 1.6, JAX-WS 2.0 37 **/ 38 public interface Dispatch<T> extends BindingProvider { 39 40 /** Invoke a service operation synchronously. 41 * 42 * The client is responsible for ensuring that the {@code msg} 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} instance 54 **/ 55 public T invoke(T msg); 56 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}. 61 * <p> 62 * The client is responsible for ensuring that the {@code msg} 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} instance 72 **/ 73 public Response<T> invokeAsync(T msg); 74 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}. 79 * <p> 80 * The client is responsible for ensuring that the {@code msg} 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} 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()} 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} instance 95 **/ 96 public Future<?> invokeAsync(T msg, AsyncHandler<T> handler); 97 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} 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} instance or if an error occurs during the 113 * invocation. 114 **/ 115 public void invokeOneWay(T msg); 116 }