1 /*
2 * Copyright (c) 2002-2026 Gargoyle Software Inc.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 * https://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15 package org.htmlunit.websocket;
16
17 import java.io.IOException;
18 import java.net.URI;
19 import java.util.List;
20
21 /**
22 * Helper to have no direct dependency to the WebSockt client
23 * implementation used by HtmlUnit.
24 *
25 * @author Ronald Brill
26 */
27 public interface WebSocketAdapter {
28
29 /**
30 * Starts the client.
31 *
32 * @throws Exception in case of error
33 */
34 void start() throws Exception;
35
36 /**
37 * Connects to the given {@link URI}.
38 *
39 * @param url the target url
40 * @throws Exception in case of error
41 */
42 void connect(URI url) throws Exception;
43
44 /**
45 * Connects to the given {@link URI} and offers the given sub-protocols in the handshake.
46 * The default implementation ignores the sub-protocols, so adapters without support keep working
47 * (no sub-protocol is selected then).
48 *
49 * @param url the target url
50 * @param protocols the sub-protocols to offer, may be empty
51 * @throws Exception in case of error
52 */
53 default void connect(final URI url, final List<String> protocols) throws Exception {
54 connect(url);
55 }
56
57 /**
58 * Returns the sub-protocol the server selected in the handshake. Only meaningful once the
59 * connection is open.
60 *
61 * @return the selected sub-protocol, or an empty string if the server did not select one
62 */
63 default String getSelectedProtocol() {
64 return "";
65 }
66
67 /**
68 * Sends the provided content.
69 *
70 * @param content the content to be sent
71 * @throws IOException in case of error
72 */
73 void send(Object content) throws IOException;
74
75 /**
76 * Close the incoming session.
77 *
78 * @throws Exception in case of error
79 */
80 void closeIncomingSession() throws Exception;
81
82 /**
83 * Close the outgoing session.
84 *
85 * @throws Exception in case of error
86 */
87 void closeOutgoingSession() throws Exception;
88
89 /**
90 * Close the outgoing session with the given status code and reason.
91 * The status code 1005 means that no status code at all is sent (an empty close frame), the reason
92 * is only sent together with a status code.
93 * The default implementation ignores the arguments and does the same as {@link #closeOutgoingSession()},
94 * so existing implementations keep working.
95 *
96 * @param statusCode the status code of the close frame
97 * @param reason the reason of the close frame, may be empty
98 * @throws Exception in case of error
99 */
100 default void closeOutgoingSession(final int statusCode, final String reason) throws Exception {
101 closeOutgoingSession();
102 }
103
104 /**
105 * Close the client.
106 *
107 * @throws Exception in case of error
108 */
109 void closeClient() throws Exception;
110 }