Top Description Inners Methods
jakarta.websocket

public Interface RemoteEndpoint

Known Direct Subinterfaces
jakarta.websocket.RemoteEndpoint.Async, jakarta.websocket.RemoteEndpoint.Basic
Imports
java.io.IOException, .OutputStream, .Writer, java.nio.ByteBuffer, java.util.concurrent.Future
The RemoteEndpoint object is supplied by the container and represents the 'other end' or peer of the Web Socket conversation. Instances of the RemoteEndpoint are obtained from the Session using Session#getBasicRemote() or Session#getAsyncRemote(). Objects of this kind include numerous ways to send web socket messages. There are two kinds of RemoteEndpoint objects: RemoteEndpoint.Basic for synchronous sending of websocket messages, and RemoteEndpoint.Async for sending messages asynchronously.

There is no guarantee of the successful delivery of a web socket message to the peer, but if the action of sending a message causes an error known to the container, the API throws it. RemoteEndpoints include a variety of ways to send messages: by whole message, in parts, and in various data formats including websocket pings and pongs.

Implementations may or may not support batching of messages. More detail of the expected semantics of implementations that do support batching are laid out in RemoteEndpoint#setBatchingAllowed(boolean).

Note

Implementations may choose their own schemes for sending large messages in smaller parts. These schemes may or may not bear a relationship to the underlying websocket dataframes in which the message is ultimately sent on the wire.

If the underlying connection is closed and methods on the RemoteEndpoint are attempted to be called, they will result in an error being generated. For the methods that send messages, this will be an IOException, for the methods that alter configuration of the endpoint, this will be runtime IllegalArgumentExceptions.

Author
dannycoward

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static interface
RemoteEndpoint.Async

This representation of the peer of a web socket conversation has the ability to send messages asynchronously.

public static interface
RemoteEndpoint.Basic

This representation of the peer of a web socket conversation has the ability to send messages synchronously.

Method Summary

Modifier and TypeMethod and Description
public void
flushBatch()

This method is only used when batching is allowed for this RemoteEndpint.

public boolean

Returns:

true if the implementation is allowed to batch outgoing messages before sending, otherwise false
getBatchingAllowed()

Return whether the implementation is allowed to batch outgoing messages before sending.

public void
sendPing(ByteBuffer
the data to be carried in the ping request.
applicationData)

Send a Ping message containing the given application data to the remote endpoint.

public void
sendPong(ByteBuffer
the application data to be carried in the pong response.
applicationData)

Allows the developer to send an unsolicited Pong message containing the given application data in order to serve as a unidirectional heartbeat for the session.

public void
setBatchingAllowed(boolean
whether the implementation is allowed to batch messages.
allowed)

Indicate to the implementation that it is allowed to batch outgoing messages before sending.

Method Detail

flushBatchback to summary
public void flushBatch() throws IOException

This method is only used when batching is allowed for this RemoteEndpint. Calling this method forces the implementation to send any unsent messages it has been batching.

Exceptions
IOException:
if the sending of any unsent messages failed
getBatchingAllowedback to summary
public boolean getBatchingAllowed()

Return whether the implementation is allowed to batch outgoing messages before sending. The default mode for RemoteEndpoints is false. The value may be changed by calling setBatchingAllowed.

Returns:boolean

true if the implementation is allowed to batch outgoing messages before sending, otherwise false

sendPingback to summary
public void sendPing(ByteBuffer applicationData) throws IOException, IllegalArgumentException

Send a Ping message containing the given application data to the remote endpoint. The corresponding Pong message may be picked up using the MessageHandler.Pong handler.

It is not safe for other threads to use the ByteBuffer until the sending of this message is complete. If the sending of the message completes successfully, the buffer's limit will be unchanged and the buffer's position will be equal to the limit. If the sending of the message does not complete successfully, the state of the buffer is undefined.

Parameters
applicationData:ByteBuffer

the data to be carried in the ping request.

Exceptions
IOException:
if the ping failed to be sent
IllegalArgumentException:
if the applicationData exceeds the maximum allowed payload of 125 bytes
sendPongback to summary
public void sendPong(ByteBuffer applicationData) throws IOException, IllegalArgumentException

Allows the developer to send an unsolicited Pong message containing the given application data in order to serve as a unidirectional heartbeat for the session.

It is not safe for other threads to use the ByteBuffer until the sending of this message is complete. If the sending of the message completes successfully, the buffer's limit will be unchanged and the buffer's position will be equal to the limit. If the sending of the message does not complete successfully, the state of the buffer is undefined.

Parameters
applicationData:ByteBuffer

the application data to be carried in the pong response.

Exceptions
IOException:
if the pong failed to be sent
IllegalArgumentException:
if the applicationData exceeds the maximum allowed payload of 125 bytes
setBatchingAllowedback to summary
public void setBatchingAllowed(boolean allowed) throws IOException

Indicate to the implementation that it is allowed to batch outgoing messages before sending. Not all implementations support batching of outgoing messages. The default mode for RemoteEndpoints is false. If the developer has indicated that batching of outgoing messages is permitted, then the developer must call flushBatch() in order to be sure that all the messages passed into the send methods of this RemoteEndpoint are sent. When batching is allowed, the implementations send operations are considered to have completed if the message has been written to the local batch, in the case when there is still room in the batch for the message, and are considered to have completed if the batch has been send to the peer and the remainder written to the new batch, in the case when writing the message causes the batch to need to be sent. The blocking and asynchronous send methods use this notion of completion in order to complete blocking calls, notify SendHandlers and complete Futures respectively. When batching is allowed, if the developer has called send methods on this RemoteEndpoint without calling flushBatch(), then the implementation may not have sent all the messages the developer has asked to be sent. If the parameter value is false and the implementation has a batch of unsent messages, then the implementation must immediately send the batch of unsent messages.

Parameters
allowed:boolean

whether the implementation is allowed to batch messages.

Exceptions
IOException:
if batching is being disabled and there are unsent messages this error may be thrown as the implementation sends the batch of unsent messages if there is a problem.
jakarta.websocket back to summary

public Interface RemoteEndpoint.Async

extends RemoteEndpoint
This representation of the peer of a web socket conversation has the ability to send messages asynchronously. The point of completion of the send is defined when all the supplied data has been written to the underlying connection. The completion handlers for the asynchronous methods may be called with a different thread from that which initiated the send.

Method Summary

Modifier and TypeMethod and Description
public long

Returns:

the timeout time in milliseconds.
getSendTimeout()

Return the number of milliseconds the implementation will timeout attempting to send a websocket message.

public Future<Void>

Returns:

the Future object representing the send operation.
sendBinary(ByteBuffer
the data being sent.
data)

Initiates the asynchronous transmission of a binary message.

public void
sendBinary(ByteBuffer
the data being sent, must not be null.
data, SendHandler
the handler that will be notified of progress, must not be null.
handler)

Initiates the asynchronous transmission of a binary message.

public Future<Void>

Returns:

the Future object representing the send operation.
sendObject(Object
the object being sent.
data)

Initiates the asynchronous transmission of a custom developer object.

public void
sendObject(Object
the object being sent.
data, SendHandler
the handler that will be notified of progress, must not be null.
handler)

Initiates the asynchronous transmission of a custom developer object.

public void
sendText(String
the text being sent.
text, SendHandler
the handler which will be notified of progress.
handler)

Initiates the asynchronous transmission of a text message.

public Future<Void>

Returns:

the Future object representing the send operation.
sendText(String
the text being sent.
text)

Initiates the asynchronous transmission of a text message.

public void
setSendTimeout(long
The number of milliseconds this RemoteEndpoint will wait before timing out an incomplete asynchronous message send.
timeoutmillis)

Sets the number of milliseconds the implementation will timeout attempting to send a websocket message.

Inherited from jakarta.websocket.RemoteEndpoint:
flushBatchgetBatchingAllowedsendPingsendPongsetBatchingAllowed

Method Detail

getSendTimeoutback to summary
public long getSendTimeout()

Return the number of milliseconds the implementation will timeout attempting to send a websocket message. A zero or negative value indicates the implementation will not timeout attempting to send a websocket message asynchronously. This value overrides the default value assigned in the WebSocketContainer.

Returns:long

the timeout time in milliseconds.

sendBinaryback to summary
public Future<Void> sendBinary(ByteBuffer data)

Initiates the asynchronous transmission of a binary message. This method returns before the message is transmitted. Developers use the returned Future object to track progress of the transmission. The Future's get() method returns null upon successful completion. Errors in transmission are wrapped in the java.util.concurrent.ExecutionException thrown when querying the Future object.

It is not safe for other threads to use the ByteBuffer until the sending of this message is complete. If the sending of the message completes successfully, the buffer's limit will be unchanged and the buffer's position will be equal to the limit. If the sending of the message does not complete successfully, the state of the buffer is undefined.

Parameters
data:ByteBuffer

the data being sent.

Returns:Future<Void>

the Future object representing the send operation.

Exceptions
IllegalArgumentException:
if the data is null.
sendBinaryback to summary
public void sendBinary(ByteBuffer data, SendHandler handler)

Initiates the asynchronous transmission of a binary message. This method returns before the message is transmitted. Developers provide a callback to be notified when the message has been transmitted. Errors in transmission are given to the developer in the SendResult object.

It is not safe for other threads to use the ByteBuffer until the sending of this message is complete. If the sending of the message completes successfully, the buffer's limit will be unchanged and the buffer's position will be equal to the limit. If the sending of the message does not complete successfully, the state of the buffer is undefined.

Parameters
data:ByteBuffer

the data being sent, must not be null.

handler:SendHandler

the handler that will be notified of progress, must not be null.

Exceptions
IllegalArgumentException:
if either the data or the handler are null.
sendObjectback to summary
public Future<Void> sendObject(Object data)

Initiates the asynchronous transmission of a custom developer object. The developer will have provided an encoder for this object type in the endpoint configuration. Containers will by default be able to encode java primitive types and their object equivalents, otherwise the developer must have provided an encoder for the object type in the endpoint configuration. A developer-provided encoder for a Java primitive type and its object equivalent overrides the container default encoder. Progress may be tracked using the Future object. The Future's get() methods return null upon successful completion. Errors in transmission are wrapped in the java.util.concurrent.ExecutionException thrown when querying the Future object.

Parameters
data:Object

the object being sent.

Returns:Future<Void>

the Future object representing the send operation.

Exceptions
IllegalArgumentException:
if the data is null.
sendObjectback to summary
public void sendObject(Object data, SendHandler handler)

Initiates the asynchronous transmission of a custom developer object. Containers will by default be able to encode java primitive types and their object equivalents, otherwise the developer must have provided an encoder for the object type in the endpoint configuration. A developer-provided encoder for a Java primitive type and its object equivalent overrides the container default encoder. Developers are notified when transmission is complete through the supplied callback object.

Parameters
data:Object

the object being sent.

handler:SendHandler

the handler that will be notified of progress, must not be null.

Exceptions
IllegalArgumentException:
if either the data or the handler are null.
sendTextback to summary
public void sendText(String text, SendHandler handler)

Initiates the asynchronous transmission of a text message. This method returns before the message is transmitted. Developers provide a callback to be notified when the message has been transmitted. Errors in transmission are given to the developer in the SendResult object.

Parameters
text:String

the text being sent.

handler:SendHandler

the handler which will be notified of progress.

Exceptions
IllegalArgumentException:
if the text or the handler is null.
sendTextback to summary
public Future<Void> sendText(String text)

Initiates the asynchronous transmission of a text message. This method returns before the message is transmitted. Developers use the returned Future object to track progress of the transmission. The Future's get() method returns null upon successful completion. Errors in transmission are wrapped in the java.util.concurrent.ExecutionException thrown when querying the Future object.

Parameters
text:String

the text being sent.

Returns:Future<Void>

the Future object representing the send operation.

Exceptions
IllegalArgumentException:
if the text is null.
setSendTimeoutback to summary
public void setSendTimeout(long timeoutmillis)

Sets the number of milliseconds the implementation will timeout attempting to send a websocket message. A zero or negative value indicates the implementation will not timeout attempting to send a websocket message asynchronously. This value overrides the default value assigned in the WebSocketContainer.

Parameters
timeoutmillis:long

The number of milliseconds this RemoteEndpoint will wait before timing out an incomplete asynchronous message send.

jakarta.websocket back to summary

public Interface RemoteEndpoint.Basic

extends RemoteEndpoint
This representation of the peer of a web socket conversation has the ability to send messages synchronously. The point of completion of the send is defined when all the supplied data has been written to the underlying connection. The methods for sending messages on the RemoteEndpoint.Basic block until this point of completion is reached, except for getSendStream and getSendWriter which present traditional blocking I/O streams to write messages.

If the websocket connection underlying this RemoteEndpoint is busy sending a message when a call is made to send another one, for example if two threads attempt to call a send method concurrently, or if a developer attempts to send a new message while in the middle of sending an existing one, the send method called while the connection is already busy may throw an java.lang.IllegalStateException.

Method Summary

Modifier and TypeMethod and Description
public OutputStream

Returns:

the output stream to which the message will be written.
getSendStream()

Opens an output stream on which a binary message may be sent.

public Writer

Returns:

the writer to which the message will be written.
getSendWriter()

Opens a character stream on which a text message may be sent.

public void
sendBinary(ByteBuffer
the message to be sent.
data)

Send a binary message, returning when all of the message has been transmitted.

public void
sendBinary(ByteBuffer
the part of the message being sent.
partialByte, boolean
Whether the partial message being sent is the last part of the message.
isLast)

Send a binary message in parts, blocking until all of the message has been transmitted.

public void
sendObject(Object
the object to be sent.
data)

Sends a custom developer object, blocking until it has been transmitted.

public void
sendText(String
the message to be sent.
text)

Send a text message, blocking until all of the message has been transmitted.

public void
sendText(String
the parts of the message being sent.
partialMessage, boolean
Whether the partial message being sent is the last part of the message.
isLast)

Send a text message in parts, blocking until all of the message has been transmitted.

Inherited from jakarta.websocket.RemoteEndpoint:
flushBatchgetBatchingAllowedsendPingsendPongsetBatchingAllowed

Method Detail

getSendStreamback to summary
public OutputStream getSendStream() throws IOException

Opens an output stream on which a binary message may be sent. The developer must close the output stream in order to indicate that the complete message has been placed into the output stream. If no calls are made to one of the write() methods before the output stream is closed then no WebSocket binary messages will be sent. If at least one call is made to one of the write() methods before the output stream is closed then at least one WebSocket binary message will be sent even if that message is of zero length.

Returns:OutputStream

the output stream to which the message will be written.

Exceptions
IOException:
if there is a problem obtaining the OutputStream to write the binary message.
getSendWriterback to summary
public Writer getSendWriter() throws IOException

Opens a character stream on which a text message may be sent. The developer must close the writer in order to indicate that the complete message has been placed into the character stream. If no calls are made to one of the write() or append() methods before the writer is closed then no WebSocket text messages will be sent. If at least one call is made to one of the write() or append() methods before the writer is closed then at least one WebSocket text message will be sent even if that message is of zero length.

Returns:Writer

the writer to which the message will be written.

Exceptions
IOException:
if there is a problem obtaining the Writer to write the text message.
sendBinaryback to summary
public void sendBinary(ByteBuffer data) throws IOException

Send a binary message, returning when all of the message has been transmitted.

It is not safe for other threads to use the ByteBuffer until the sending of this message is complete. If the sending of the message completes successfully, the buffer's limit will be unchanged and the buffer's position will be equal to the limit. If the sending of the message does not complete successfully, the state of the buffer is undefined.

Parameters
data:ByteBuffer

the message to be sent.

Exceptions
IOException:
if there is a problem delivering the message.
IllegalArgumentException:
if the data is null.
sendBinaryback to summary
public void sendBinary(ByteBuffer partialByte, boolean isLast) throws IOException

Send a binary message in parts, blocking until all of the message has been transmitted. The runtime reads the message in order. Non-final parts are sent with isLast set to false. The final piece must be sent with isLast set to true.

It is not safe for other threads to use the ByteBuffer until the sending of this partial message is complete. If the sending of the partial message completes successfully, the buffer's limit will be unchanged and the buffer's position will be equal to the limit. If the sending of the partial message does not complete successfully, the state of the buffer is undefined.

Parameters
partialByte:ByteBuffer

the part of the message being sent.

isLast:boolean

Whether the partial message being sent is the last part of the message.

Exceptions
IOException:
if there is a problem delivering the partial message.
IllegalArgumentException:
if the partialByte is null.
sendObjectback to summary
public void sendObject(Object data) throws IOException, EncodeException

Sends a custom developer object, blocking until it has been transmitted. Containers will by default be able to encode java primitive types and their object equivalents, otherwise the developer must have provided an encoder for the object type in the endpoint configuration. A developer-provided encoder for a Java primitive type and its object equivalent overrides the container default encoder.

Parameters
data:Object

the object to be sent.

Exceptions
IOException:
if there is a communication error sending the message object.
EncodeException:
if there was a problem encoding the message object into the form of a native websocket message.
IllegalArgumentException:
if the data parameter is null
sendTextback to summary
public void sendText(String text) throws IOException

Send a text message, blocking until all of the message has been transmitted.

Parameters
text:String

the message to be sent.

Exceptions
IOException:
if there is a problem delivering the message.
IllegalArgumentException:
if the text is null.
sendTextback to summary
public void sendText(String partialMessage, boolean isLast) throws IOException

Send a text message in parts, blocking until all of the message has been transmitted. The runtime reads the message in order. Non-final parts of the message are sent with isLast set to false. The final part must be sent with isLast set to true.

Parameters
partialMessage:String

the parts of the message being sent.

isLast:boolean

Whether the partial message being sent is the last part of the message.

Exceptions
IOException:
if there is a problem delivering the message fragment.
IllegalArgumentException:
if the partialMessage is null.