javax.websocket
Interface RemoteEndpoint

public interface RemoteEndpoint

The RemoteEndpoint object is supplied by the container and represents the 'other end' of the Web Socket conversation. In particular, objects of this kind include numerous ways to send web socket messages. There is no guarantee of the success of receipt of a web socket message, but if the action of sending a message causes a known error, the API throws it. This object includes a variety of ways to send messages to the other end of a web socket session: by whole message, in parts and asynchronously, where the point of completion is defined when all the supplied data had been written to the underlying connection. The completion handlers for the asynchronous methods are always called with a different thread from that which initiated the send.

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.

Since:

DRAFT 001

Author:

dannycoward

Method Summary

void	flushBatch() This method is only used when batching is allowed for this RemoteEndpint.
long	getAsyncSendTimeout() Return the number of milliseconds the implementation will timeout attempting to send a websocket message.
boolean	getBatchingAllowed() Return whether the implementation is allowed to batch outgoing messages before sending.
OutputStream	getSendStream() Opens an output stream on which a binary message may be sent.
Writer	getSendWriter() Opens an character stream on which a text message may be sent.
void	sendBytes(ByteBuffer data) Send a binary message, returning when all of the message has been transmitted.
void	sendBytesByCompletion(ByteBuffer data, SendHandler completion) Initiates the asynchronous transmission of a binary message.
Future<SendResult>	sendBytesByFuture(ByteBuffer data) Initiates the asynchronous transmission of a binary message.
void	sendObject(Object o) Sends a custom developer object, blocking until it has been transmitted.
void	sendObjectByCompletion(Object o, SendHandler handler) Initiates the asynchronous transmission of a custom developer object.
Future<SendResult>	sendObjectByFuture(Object o) Initiates the asynchronous transmission of a custom developer object.
void	sendPartialBytes(ByteBuffer partialByte, boolean isLast) Send a binary message in parts, blocking until all of the message has been transmitted.
void	sendPartialString(String partialMessage, boolean isLast) Send a text message in parts, blocking until all of the message has been transmitted.
void	sendPing(ByteBuffer applicationData) Send a Ping message containing the given application data to the remote endpoint.
void	sendPong(ByteBuffer 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.
void	sendString(String text) Send a text message, blocking until all of the message has been transmitted.
void	sendStringByCompletion(String text, SendHandler completion) Initiates the asynchronous transmission of a text message.
Future<SendResult>	sendStringByFuture(String text) Initiates the asynchronous transmission of a text message.
void	setAsyncSendTimeout(long timeoutmillis) Sets the number of milliseconds the implementation will timeout attempting to send a websocket message.
void	setBatchingAllowed(boolean allowed) Indicate to the implementation that it is allowed to batch outgoing messages before sending.

Method Detail

setBatchingAllowed

void setBatchingAllowed(boolean allowed)

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. If 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 - whether the implementation is allowed to batch messages.

getBatchingAllowed

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.

flushBatch

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.

Throws:

IOException

getAsyncSendTimeout

long getAsyncSendTimeout()

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

Returns:

the timeout time in milliseconds.

setAsyncSendTimeout

void setAsyncSendTimeout(long timeoutmillis)

Sets the number of milliseconds the implementation will timeout attempting to send a websocket message. A non-positive number 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 - The number of milliseconds this RemoteEndpoint will wait before timing out an incomplete asynchronous message send.

sendString

void sendString(String text)
                throws IOException

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

Parameters:

text - the message to be sent.

Throws:

IOException - if there is a problem delivering the message.

sendBytes

void sendBytes(ByteBuffer data)
               throws IOException

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

Parameters:

data - the message to be sent.

Throws:

IOException - if there is a problem delivering the message.

sendPartialString

void sendPartialString(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 - the parts of the message being sent.

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

Throws:

IOException - if there is a problem delivering the message fragment.

sendPartialBytes

void sendPartialBytes(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.

Parameters:

partialByte - the part of the message being sent.

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

Throws:

IOException - if there is a problem delivering the partial message.

getSendStream

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.

Returns:

the output stream to which the message will be written.

Throws:

IOException - if there is a problem obtaining the OutputStream to write the binary message.

getSendWriter

Writer getSendWriter()
                     throws IOException

Opens an 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.

Returns:

the writer to which the message will be written.

Throws:

IOException - if there is a problem obtaining the Writer to write the text message.

sendObject

void sendObject(Object o)
                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, their object equivalents, and arrays or collections thereof. The developer will have provided an encoder for this object type in the endpoint configuration.

Parameters:

o - the object to be sent.

Throws:

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.

sendStringByCompletion

void sendStringByCompletion(String text,
                            SendHandler completion)

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 - the text being sent.

completion - the handler which will be notified of progress.

sendStringByFuture

Future<SendResult> sendStringByFuture(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. Errors in transmission are given to the developer in the SendResult object.

Parameters:

text - the text being sent.

Returns:

the Future object representing the send operation.

sendBytesByFuture

Future<SendResult> sendBytesByFuture(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. Errors in transmission are given to the developer in the SendResult object.

Parameters:

data - the data being sent.

Returns:

the Future object representing the send operation.

sendBytesByCompletion

void sendBytesByCompletion(ByteBuffer data,
                           SendHandler completion)

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.

Parameters:

data - the data being sent.

completion - the handler that will be notified of progress.

sendObjectByFuture

Future<SendResult> sendObjectByFuture(Object o)

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, their object equivalents, and arrays or collections thereof. Progress is be tracked using the Future object.

Parameters:

o - the object being sent.

Returns:

the Future object representing the send operation.

sendObjectByCompletion

void sendObjectByCompletion(Object o,
                            SendHandler handler)

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, their object equivalents, and arrays or collections thereof. Developers are notified when transmission is complete through the supplied callback object.

Parameters:

o - the object being sent.

handler - the handler that will be notified of progress.

sendPing

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.

Parameters:

applicationData - the data to be carried in the ping request.

Throws:

IOException - if the ping failed to be sent

IllegalArgumentException - if the applicationData exceeds the maximum allowed payload of 125 bytes

sendPong

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.

Parameters:

applicationData - the application data to be carried in the pong response.

Throws:

IOException - if the pong failed to be sent

IllegalArgumentException - if the applicationData exceeds the maximum allowed payload of 125 bytes