001// Licensed under the Apache License, Version 2.0 (the "License");
002// you may not use this file except in compliance with the License.
003// You may obtain a copy of the License at
004//
005// http://www.apache.org/licenses/LICENSE-2.0
006//
007// Unless required by applicable law or agreed to in writing, software
008// distributed under the License is distributed on an "AS IS" BASIS,
009// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
010// See the License for the specific language governing permissions and
011// limitations under the License.
012package org.apache.tapestry5.http;
013
014import java.util.concurrent.Executor;
015import java.util.concurrent.ExecutorService;
016import java.util.concurrent.Executors;
017
018import javax.servlet.AsyncListener;
019import javax.servlet.http.HttpServletRequest;
020import javax.servlet.http.HttpServletResponse;
021
022import org.apache.tapestry5.http.internal.AsyncRequestService;
023
024/**
025 * <p>
026 * Service whose implementations define whether a given request should be handled
027 * asynchronously or not and, if yes, which {@link Executor} (usually, a thread pool,
028 * but not necessarily) should handle it, possibly different {@link HttpServletRequest}
029 * and {@link HttpServletResponse} objects to be used when calling 
030 * {@linkplain} HttpServletRequest#startAsync()} and an optional {@linkplain AsyncListener}.
031 * </p>
032 * <p>
033 * If one {@link AsyncRequestHandler} doesn't tells the request should be asynchronous,
034 * the next one contributed to {@link AsyncRequestService} will be called
035 * and so on until one says the request should be asynchronous or all of them
036 * were called and the request will be synchronous.
037 * </p>
038 * @see AsyncRequestService
039 * @see Executor
040 * @see ExecutorService
041 * @see Executors
042 */
043public interface AsyncRequestHandler 
044{
045    
046    /**
047     * Returns whether this request is handled by this handler. If not,
048     * it should return {@link AsyncRequestHandlerResponse#notHandled()}. 
049     * @return a non-null {@linkplain AsyncRequestHandlerResponse}.
050     */
051    AsyncRequestHandlerResponse handle(HttpServletRequest request, HttpServletResponse response);
052
053}