1 /*
2 * The contents of this file are subject to the terms of the Common Development and
3 * Distribution License (the License). You may not use this file except in compliance with the
4 * License.
5 *
6 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
7 * specific language governing permission and limitations under the License.
8 *
9 * When distributing Covered Software, include this CDDL Header Notice in each file and include
10 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
11 * Header, with the fields enclosed by brackets [] replaced by your own identifying
12 * information: "Portions copyright [year] [name of copyright owner]".
13 *
14 * Copyright 2012-2015 ForgeRock AS.
15 */
16
17 package org.forgerock.http.servlet;
18
19 /**
20 * An interface for implementing different synchronization strategies depending
21 * on the available Servlet container version and/or capabilities. These include:
22 * <ul>
23 * <li>2.5 (JavaEE 5) - synchronous processing and synchronous IO
24 * <li>3.0 (JavaEE 6) - asynchronous (non-blocking) processing and synchronous
25 * IO
26 * <li>3.1 (JavaEE 7) - asynchronous (non-blocking) processing and asynchronous
27 * IO (NIO)
28 * </ul>
29 *
30 * @see ServletVersionAdapter#createServletSynchronizer(jakarta.servlet.http.HttpServletRequest,
31 * jakarta.servlet.http.HttpServletResponse)
32 */
33 interface ServletSynchronizer {
34
35 /**
36 * If this synchronizer is non-blocking then this method registers an
37 * {@link jakarta.servlet.AsyncListener call-back} which will be invoked once
38 * the request has completed, failed, or timed out.
39 * <p>
40 * This method should be used to register call-backs for releasing resources
41 * after a request has been processed.
42 * <p>
43 * Calls to this method when the synchronizer is blocking have no effect.
44 *
45 * @param runnable
46 * The call-back to be invoked once the request has completed,
47 * failed, or timed out.
48 */
49 void setAsyncListener(Runnable runnable);
50
51 /**
52 * Waits for this synchronizer to be signalled but only if this synchronizer
53 * is a blocking implementation.
54 *
55 * @throws InterruptedException
56 * If an unexpected error occurred while waiting to be
57 * signalled.
58 */
59 void awaitIfNeeded() throws InterruptedException;
60
61 /**
62 * Releases any waiting threads blocked on {@link #awaitIfNeeded()}, as well
63 * as completing the underlying {@link jakarta.servlet.AsyncContext
64 * AsyncContext} if this synchronizer is non-blocking. This method should be
65 * called after a writing out content and setting the response status.
66 */
67 void signalAndComplete();
68 }