Package: ServerContainer

ServerContainer

Coverage

1: /*
2: * Copyright (c) 2018, 2021 Oracle and/or its affiliates and others.
3: * All rights reserved.
4: *
5: * This program and the accompanying materials are made available under the
6: * terms of the Eclipse Public License v. 2.0, which is available at
7: * http://www.eclipse.org/legal/epl-2.0.
8: *
9: * This Source Code may also be made available under the following Secondary
10: * Licenses when the conditions for such availability set forth in the
11: * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
12: * version 2 with the GNU Classpath Exception, which is available at
13: * https://www.gnu.org/software/classpath/license.html.
14: *
15: * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
16: */
17:
18: package jakarta.websocket.server;
19:
20: import java.io.IOException;
21: import java.util.Map;
22:
23: import jakarta.websocket.*;
24:
25: /**
26: * The ServerContainer is the specialized view of the WebSocketContainer available in server-side deployments. There is
27: * one ServerContainer instance per websocket application. The ServerContainer holds the methods to be able to register
28: * server endpoints.
29: * <p>
30: * For websocket enabled web containers, developers may obtain a reference to the ServerContainer instance by retrieving
31: * it as an attribute named <code>jakarta.websocket.server.ServerContainer</code> on the ServletContext. This way, the
32: * registration methods held on this interface may be called to register server endpoints from a ServletContextListener
33: * during the deployment of the WAR file containing the endpoint. Server endpoints may also be registered after the web
34: * application has started.
35: * </p>
36: * <p>
37: * WebSocket implementations that run outside the web container may have other means by which to provide a
38: * ServerContainer instance to the developer at application deployment time.
39: * </p>
40: * <p>
41: * Once the application deployment phase is complete, and the websocket application has begun accepting incoming
42: * connections, the registration methods may no longer be called.
43: *
44: * @author dannycoward
45: */
46: public interface ServerContainer extends WebSocketContainer {
47:
48: /**
49: * Deploys the given annotated endpoint into this ServerContainer.
50: *
51: * @param endpointClass the class of the annotated endpoint
52: * @throws DeploymentException if the annotated endpoint was badly formed.
53: * @throws IllegalStateException if the containing websocket application has already been deployed.
54: */
55: public void addEndpoint(Class<?> endpointClass) throws DeploymentException;
56:
57: /**
58: * Deploys the given endpoint described by the provided configuration into this ServerContainer.
59: *
60: * @param serverConfig the configuration instance representing the logical endpoint that will be registered.
61: * @throws DeploymentException if the endpoint was badly formed.
62: * @throws IllegalStateException if the containing websocket application has already been deployed.
63: */
64: public void addEndpoint(ServerEndpointConfig serverConfig) throws DeploymentException;
65:
66: /**
67: * Upgrade the HTTP connection represented by the {@code HttpServletRequest} and {@code HttpServletResponse} to the
68: * WebSocket protocol and establish a WebSocket connection as per the provided {@link ServerEndpointConfig}.
69: * <p>
70: * This method is primarily intended to be used by frameworks that implement the front-controller pattern. It does
71: * not deploy the provided endpoint.
72: * <p>
73: * If the WebSocket implementation is not deployed as part of a Jakarta Servlet container, this method will throw an
74: * {@link UnsupportedOperationException}.
75: *
76: * @param httpServletRequest The {@code HttpServletRequest} to be processed as a WebSocket handshake as per
77: * section 4.0 of RFC 6455.
78: * @param httpServletResponse The {@code HttpServletResponse} to be used when processing the
79: * {@code httpServletRequest} as a WebSocket handshake as per section 4.0 of RFC 6455.
80: * @param sec The server endpoint configuration to use to configure the WebSocket endpoint
81: * @param pathParameters Provides a mapping of path parameter names and values, if any, to be used for the
82: * WebSocket connection established by the call to this method. If no such mapping is
83: * defined, an empty Map must be passed.
84: *
85: * @throws IllegalStateException if the provided request does not meet the requirements of the WebSocket handshake
86: * @throws UnsupportedOperationException if the WebSocket implementation is not deployed as part of a Jakarta
87: * Servlet container
88: * @throws IOException if an I/O error occurs during the establishment of a WebSocket connection
89: * @throws DeploymentException if a configuration error prevents the establishment of a WebSocket connection
90: *
91: * @since WebSocket 2.1
92: */
93: public void upgradeHttpToWebSocket(Object httpServletRequest, Object httpServletResponse, ServerEndpointConfig sec,
94: Map<String,String> pathParameters) throws IOException, DeploymentException;
95: }