001 /*
002 * Copyright 2005 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.xml.ws;
027
028 import java.util.concurrent.Future;
029
030 /** The <code>Dispatch</code> interface provides support
031 * for the dynamic invocation of a service endpoint operations. The
032 * <code>javax.xml.ws.Service</code>
033 * interface acts as a factory for the creation of <code>Dispatch</code>
034 * instances.
035 *
036 * @since JAX-WS 2.0
037 **/
038 public interface Dispatch<T> extends BindingProvider {
039
040 /** Invoke a service operation synchronously.
041 *
042 * The client is responsible for ensuring that the <code>msg</code> object
043 * when marshalled is formed according to the requirements of the protocol
044 * binding in use.
045 *
046 * @param msg An object that will form the message or payload of
047 * the message used to invoke the operation.
048 * @return The response message or message payload to the
049 * operation invocation.
050 * @throws WebServiceException If a fault occurs during communication with
051 * the service
052 * @throws WebServiceException If there is any error in the configuration of
053 * the <code>Dispatch</code> instance
054 **/
055 public T invoke(T msg);
056
057 /** Invoke a service operation asynchronously. The
058 * method returns without waiting for the response to the operation
059 * invocation, the results of the operation are obtained by polling the
060 * returned <code>Response</code>.
061 *
062 * The client is responsible for ensuring that the <code>msg</code> object
063 * when marshalled is formed according to the requirements of the protocol
064 * binding in use.
065 *
066 * @param msg An object that will form the message or payload of
067 * the message used to invoke the operation.
068 * @return The response message or message payload to the
069 * operation invocation.
070 * @throws WebServiceException If there is any error in the configuration of
071 * the <code>Dispatch</code> instance
072 **/
073 public Response<T> invokeAsync(T msg);
074
075 /** Invoke a service operation asynchronously. The
076 * method returns without waiting for the response to the operation
077 * invocation, the results of the operation are communicated to the client
078 * via the passed in handler.
079 *
080 * The client is responsible for ensuring that the <code>msg</code> object
081 * when marshalled is formed according to the requirements of the protocol
082 * binding in use.
083 *
084 * @param msg An object that will form the message or payload of
085 * the message used to invoke the operation.
086 * @param handler The handler object that will receive the
087 * response to the operation invocation.
088 * @return A <code>Future</code> object that may be used to check the status
089 * of the operation invocation. This object must not be used to try to
090 * obtain the results of the operation - the object returned from
091 * <code>Future<?>.get()</code> is implementation dependent
092 * and any use of it will result in non-portable behaviour.
093 * @throws WebServiceException If there is any error in the configuration of
094 * the <code>Dispatch</code> instance
095 **/
096 public Future<?> invokeAsync(T msg, AsyncHandler<T> handler);
097
098 /** Invokes a service operation using the one-way
099 * 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 *
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 }
|