1/* 2 * Copyright (c) 1997, 2013, 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 26package com.sun.xml.internal.ws.api.server; 27 28import com.sun.istack.internal.NotNull; 29 30import javax.xml.ws.Provider; 31import javax.xml.ws.WebServiceContext; 32import java.util.concurrent.Executor; 33 34/** 35 * Asynchronous version of {@link Provider}. 36 * 37 * <p> 38 * Applications that use the JAX-WS RI can implement this interface instead of 39 * {@link Provider} to implement asynchronous web services (AWS.) AWS enables 40 * applications to perform operations with long latency without blocking a thread, 41 * and thus particularly suitable for highly scalable service implementation, 42 * at the expesnce of implementation complexity. 43 * 44 * <h2>Programming Model</h2> 45 * <p> 46 * Whenever a new reuqest arrives, the JAX-WS RI invokes the {@link #invoke} method 47 * to notify the application. Normally, the application then schedules an execution 48 * of this request, and exit from this method immediately (the point of AWS is not 49 * to use this calling thread for request processing.) 50 * 51 * <p> 52 * Unlike the synchronous version, which requires the response to be given as the return value, 53 * with AWS the JAX-WS RI will keep the connection with client open, until the application 54 * eventually notifies the JAX-WS RI via {@link AsyncProviderCallback}. When that 55 * happens that causes the JAX-WS RI to send back a response to the client. 56 * 57 * <p> 58 * The following code shows a very simple AWS example: 59 * 60 * <pre> 61 * @WebService 62 * class MyAsyncEchoService implements AsyncProvider<Source> { 63 * private static final {@link Executor} exec = ...; 64 * 65 * public void invoke( final Source request, final AsyncProviderCallback<Source> callback, final WebServiceContext context) { 66 * exec.execute(new {@link Runnable}() { 67 * public void run() { 68 * Thread.sleep(1000); // kill time. 69 * callback.send(request); // just echo back 70 * } 71 * }); 72 * } 73 * } 74 * </pre> 75 * 76 * <p> 77 * Please also check the {@link Provider} and its programming model for general 78 * provider programming model. 79 * 80 * 81 * <h2>WebServiceContext</h2> 82 * <p> 83 * In synchronous web services, the injected {@link WebServiceContext} instance uses 84 * the calling {@link Thread} to determine which request it should return information about. 85 * This no longer works with AWS, as you may need to call {@link WebServiceContext} 86 * much later, possibly from entirely different thread. 87 * 88 * <p> 89 * For this reason, {@link AsyncProvider} passes in {@link WebServiceContext} as 90 * a parameter. This object remains usable until you invoke {@link AsyncProviderCallback}, 91 * and it can be invoked from any thread, even concurrently. AWS must not use the injected 92 * {@link WebServiceContext}, as its behavior is undefined. 93 * 94 * @see Provider 95 * @author Jitendra Kotamraju 96 * @author Kohsuke Kawaguchi 97 * @since 2.1 98 */ 99public interface AsyncProvider<T> { 100 /** 101 * Schedules an execution of a request. 102 * 103 * @param request 104 * Represents the request message or payload. 105 * @param callback 106 * Application must notify this callback interface when the processing 107 * of a request is complete. 108 * @param context 109 * The web service context instance that can be used to retrieve 110 * context information about the given request. 111 */ 112 public void invoke( 113 @NotNull T request, 114 @NotNull AsyncProviderCallback<T> callback, 115 @NotNull WebServiceContext context); 116} 117