org.glassfish.grizzly.websockets.WebSocket Maven / Gradle / Ivy
/*
* Copyright (c) 2010, 2020 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0, which is available at
* http://www.eclipse.org/legal/epl-2.0.
*
* This Source Code may also be made available under the following Secondary
* Licenses when the conditions for such availability set forth in the
* Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
* version 2 with the GNU Classpath Exception, which is available at
* https://www.gnu.org/software/classpath/license.html.
*
* SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
*/
package org.glassfish.grizzly.websockets;
import org.glassfish.grizzly.GrizzlyFuture;
/**
* General WebSocket unit interface.
*
* @author Alexey Stashok
*/
public interface WebSocket {
/**
* Indicates a normal closure, meaning whatever purpose the connection was established for has been fulfilled.
*/
int NORMAL_CLOSURE = 1000;
/**
* Indicates that an endpoint is "going away", such as a server going down, or a browser having navigated away from a
* page.
*/
int END_POINT_GOING_DOWN = 1001;
/**
* Indicates that an endpoint is terminating the connection due to a protocol error.
*/
int PROTOCOL_ERROR = 1002;
/**
* Indicates that an endpoint is terminating the connection because it has received a type of data it cannot accept
* (e.g. an endpoint that understands only text data may send this if it receives a binary message.)
*/
int INVALID_DATA = 1003;
/**
* indicates that an endpoint is terminating the connection because it has received a message that is too large.
*/
int MESSAGE_TOO_LARGE = 1004;
/**
* a reserved value and MUST NOT be set as a status code in a Close control frame by an endpoint. It is designated for
* use in applications expecting a status code to indicate that no status code was actually present.
*/
int NO_STATUS_CODE = 1005;
/**
* a reserved value and MUST NOT be set as a status code in a Close control frame by an endpoint. It is designated for
* use in applications expecting a status code to indicate that the connection was closed abnormally, e.g. without
* sending or receiving a Close control frame.
*/
int ABNORMAL_CLOSE = 1006;
/**
*
* Send a text frame to the remote end-point.
*
*
* @return {@link GrizzlyFuture} which could be used to control/check the sending completion state.
*/
GrizzlyFuture send(String data);
/**
*
* Send a binary frame to the remote end-point.
*
*
* @return {@link GrizzlyFuture} which could be used to control/check the sending completion state.
*/
GrizzlyFuture send(byte[] data);
/**
*
* Broadcasts the data to the remote end-point set.
*
*
* @param recipients
* @param data
*/
void broadcast(final Iterable recipients, String data);
/**
*
* Broadcasts the data to the remote end-point set.
*
*
* @param recipients
* @param data
*/
void broadcast(final Iterable recipients, byte[] data);
/**
*
* Broadcasts the data fragment to the remote end-point set.
*
*
* @param recipients
* @param data
*/
void broadcastFragment(final Iterable recipients, String data, boolean last);
/**
*
* Broadcasts the data fragment to the remote end-point set.
*
*
* @param recipients
* @param data
*/
void broadcastFragment(final Iterable recipients, byte[] data, boolean last);
/**
* Sends a ping frame with the specified payload (if any).
*
*
* @param data optional payload. Note that payload length is restricted to 125 bytes or less.
*
* @return {@link GrizzlyFuture} which could be used to control/check the sending completion state.
*
* @since 2.1.9
*/
GrizzlyFuture sendPing(byte[] data);
/**
*
* Sends a ping frame with the specified payload (if any).
*
*
*
* It may seem odd to send a pong frame, however, RFC-6455 states:
*
*
*
* "A Pong frame MAY be sent unsolicited. This serves as a unidirectional heartbeat. A response to an unsolicited Pong
* frame is not expected."
*
*
* @param data optional payload. Note that payload length is restricted to 125 bytes or less.
*
* @return {@link GrizzlyFuture} which could be used to control/check the sending completion state.
*
* @since 2.1.9
*/
GrizzlyFuture sendPong(byte[] data);
/**
*
* Sends a fragment of a complete message.
*
*
* @param last boolean indicating if this message fragment is the last.
* @param fragment the textual fragment to send.
*
* @return {@link GrizzlyFuture} which could be used to control/check the sending completion state.
*/
GrizzlyFuture stream(boolean last, String fragment);
/**
*
* Sends a fragment of a complete message.
*
*
* @param last boolean indicating if this message fragment is the last.
* @param fragment the binary fragment to send.
* @param off the offset within the fragment to send.
* @param len the number of bytes of the fragment to send.
*
* @return {@link GrizzlyFuture} which could be used to control/check the sending completion state.
*/
GrizzlyFuture stream(boolean last, byte[] fragment, int off, int len);
/**
*
* Closes this {@link WebSocket}.
*
*/
void close();
/**
*
* Closes this {@link WebSocket} using the specified status code.
*
*
* @param code the closing status code.
*/
void close(int code);
/**
*
* Closes this {@link WebSocket} using the specified status code and reason.
*
*
* @param code the closing status code.
* @param reason the reason, if any.
*/
void close(int code, String reason);
/**
*
* Convenience method to determine if this {@link WebSocket} is connected.
*
*
* @return true if the {@link WebSocket} is connected, otherwise false
*/
boolean isConnected();
/**
*
* This callback will be invoked when the opening handshake between both endpoints has been completed.
*
*/
void onConnect();
/**
*
* This callback will be invoked when a text message has been received.
*
*
* @param text the text received from the remote end-point.
*/
void onMessage(String text);
/**
*
* This callback will be invoked when a binary message has been received.
*
*
* @param data the binary data received from the remote end-point.
*/
void onMessage(byte[] data);
/**
*
* This callback will be invoked when a fragmented textual message has been received.
*
*
* @param last flag indicating whether or not the payload received is the final fragment of a message.
* @param payload the text received from the remote end-point.
*/
void onFragment(boolean last, String payload);
/**
*
* This callback will be invoked when a fragmented binary message has been received.
*
*
* @param last flag indicating whether or not the payload received is the final fragment of a message.
* @param payload the binary data received from the remote end-point.
*/
void onFragment(boolean last, byte[] payload);
/**
*
* This callback will be invoked when the remote end-point sent a closing frame.
*
*
* @param frame the close frame from the remote end-point.
*
* @see DataFrame
*/
void onClose(DataFrame frame);
/**
*
* This callback will be invoked when the remote end-point has sent a ping frame.
*
*
* @param frame the ping frame from the remote end-point.
*
* @see DataFrame
*/
void onPing(DataFrame frame);
/**
*
* This callback will be invoked when the remote end-point has sent a pong frame.
*
*
* @param frame the pong frame from the remote end-point.
*
* @see DataFrame
*/
void onPong(DataFrame frame);
/**
* Adds a {@link WebSocketListener} to be notified of events of interest.
*
* @param listener the {@link WebSocketListener} to add.
*
* @return true if the listener was added, otherwise false
*
* @see WebSocketListener
*/
boolean add(WebSocketListener listener);
/**
* Removes the specified {@link WebSocketListener} as a target of event notification.
*
* @param listener the {@link WebSocketListener} to remote.
*
* @return true if the listener was removed, otherwise false
*
* @see WebSocketListener
*/
boolean remove(WebSocketListener listener);
}