Package: HandshakeRequest

HandshakeRequest

Coverage

1: /*
2: * Copyright (c) 2018, 2020 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.net.URI;
21: import java.security.Principal;
22: import java.util.List;
23: import java.util.Map;
24:
25: /**
26: * The handshake request represents the WebSocket defined HTTP GET request for the opening handshake of a WebSocket
27: * session.
28: *
29: * @author dannycoward
30: */
31: public interface HandshakeRequest {
32: /**
33: * The Sec-WebSocket-Key header name
34: */
35: static String SEC_WEBSOCKET_KEY = "Sec-WebSocket-Key";
36: /**
37: * The Sec-WebSocket-Protocol header name
38: */
39: static String SEC_WEBSOCKET_PROTOCOL = "Sec-WebSocket-Protocol";
40: /**
41: * The Sec-WebSocket-Version header name
42: */
43: static String SEC_WEBSOCKET_VERSION = "Sec-WebSocket-Version";
44: /**
45: * The Sec-WebSocket-Extensions header name
46: */
47: static String SEC_WEBSOCKET_EXTENSIONS = "Sec-WebSocket-Extensions";
48:
49: /**
50: * Return the read only map of HTTP headers to header values that came with the handshake request. Note that the
51: * lookup of header names will be performed in a case insensitive manner.
52: *
53: * @return the list of headers.
54: */
55: Map<String, List<String>> getHeaders();
56:
57: /**
58: * Return the authenticated user or {@code null} if no user is authenticated for this handshake.
59: *
60: * @return the user principal.
61: */
62: Principal getUserPrincipal();
63:
64: /**
65: * Return the request URI of the handshake request.
66: *
67: * @return the request uri of the handshake request.
68: */
69: URI getRequestURI();
70:
71: /**
72: * Checks whether the current user is in the given role. Roles and role membership can be defined using deployment
73: * descriptors of the containing WAR file, if running in a Java EE web container. If the user has not been
74: * authenticated, the method returns {@code false}.
75: *
76: * @param role the role being checked.
77: * @return whether the authenticated user is in the role, or false if the user has not been authenticated.
78: */
79: boolean isUserInRole(String role);
80:
81: /**
82: * Return a reference to the HttpSession that the web socket handshake that started this conversation was part of,
83: * if the implementation is part of a Java EE web container.
84: *
85: * @return the http session or {@code null} if either the websocket implementation is not part of a Java EE web
86: * container, or there is no HttpSession associated with the opening handshake request.
87: */
88: Object getHttpSession();
89:
90: /**
91: * Return the request parameters associated with the request.
92: *
93: * @return the unmodifiable map of the request parameters.
94: */
95: Map<String, List<String>> getParameterMap();
96:
97: /**
98: * Return the query string associated with the request.
99: *
100: * @return the query string.
101: */
102: String getQueryString();
103: }