public abstract class WebSocket extends Object implements Closeable
Refer to http://www.w3.org/TR/websockets/
for the published standard
W3C WebSocket API specification.
Instances of WebSocket
can be created using
WebSocketFactory.createWebSocket(java.net.URI, String...)
API.
Constructor and Description |
---|
WebSocket() |
Modifier and Type | Method and Description |
---|---|
abstract void |
close()
Disconnects with the server.
|
abstract void |
close(int code)
Disconnects with the server with code.
|
abstract void |
close(int code,
String reason)
Disconnects with the server with code and reason.
|
abstract void |
connect()
Connects with the server using an endpoint.
|
abstract ChallengeHandler |
getChallengeHandler()
Gets the
ChallengeHandler that is used during authentication
both at the connect-time as well as at subsequent revalidation-time that
occurs at regular intervals. |
abstract int |
getConnectTimeout()
Gets the connect timeout in milliseconds.
|
abstract Collection<String> |
getEnabledExtensions()
Gets the names of all the extensions that have been enabled for this
connection.
|
abstract <T> T |
getEnabledParameter(WebSocketExtension.Parameter<T> parameter)
Gets the value of the specified
WebSocketExtension.Parameter defined in an enabled
extension. |
abstract Collection<String> |
getEnabledProtocols()
Gets the names of all the protocols that are enabled for this
connection.
|
abstract InputStream |
getInputStream()
Returns the
InputStream to receive binary messages. |
abstract WebSocketMessageReader |
getMessageReader()
Returns a
WebSocketMessageReader that can be used to receive
binary and text messages based on the
WebSocketMessageType . |
abstract WebSocketMessageWriter |
getMessageWriter()
Returns a
WebSocketMessageWriter that can be used to send
binary and text messages. |
abstract Collection<String> |
getNegotiatedExtensions()
Gets names of all the enabled extensions that have been successfully
negotiated between the client and the server during the initial
handshake.
|
abstract <T> T |
getNegotiatedParameter(WebSocketExtension.Parameter<T> parameter)
Returns the value of the specified
WebSocketExtension.Parameter of a negotiated
extension. |
abstract String |
getNegotiatedProtocol()
Gets the protocol that the client and the server have successfully
negotiated.
|
abstract OutputStream |
getOutputStream()
Returns the
OutputStream to send binary messages. |
abstract Reader |
getReader()
Returns a
Reader to receive text messages from this
connection. |
abstract HttpRedirectPolicy |
getRedirectPolicy()
Returns
HttpRedirectPolicy indicating the policy for
following HTTP redirects (status code 3xx). |
abstract Collection<String> |
getSupportedExtensions()
Returns the names of supported extensions that have been discovered.
|
abstract Writer |
getWriter()
Returns a
Writer to send text messages from this
connection. |
abstract void |
setChallengeHandler(ChallengeHandler challengeHandler)
Sets the
ChallengeHandler that is used during authentication
both at the connect-time as well as at subsequent revalidation-time that
occurs at regular intervals. |
abstract void |
setConnectTimeout(int connectTimeout)
Sets the connect timeout in milliseconds.
|
abstract void |
setEnabledExtensions(Collection<String> extensions)
Registers the names of all the extensions that must be negotiated between
the client and the server during the handshake.
|
abstract <T> void |
setEnabledParameter(WebSocketExtension.Parameter<T> parameter,
T value)
Sets the value of the specified
WebSocketExtension.Parameter defined in an enabled
extension. |
abstract void |
setEnabledProtocols(Collection<String> protocols)
Registers the protocols to be negotiated with the server during the
handshake.
|
abstract void |
setRedirectPolicy(HttpRedirectPolicy option)
Sets
HttpRedirectPolicy indicating the policy for
following HTTP redirects (3xx). |
public abstract void close() throws IOException
close
in interface Closeable
close
in interface AutoCloseable
IOException
- if the disconnect did not succeedpublic abstract void close(int code) throws IOException
code
- the error code for closingIOException
- if the disconnect did not succeedIllegalArgumentException
- if the code isn't 1000 or out of
range 3000 - 4999.public abstract void close(int code, String reason) throws IOException
code
- the error code for closingreason
- the reason for closingIOException
- if the disconnect did not succeedIllegalArgumentException
- if the code isn't 1000 or out of
range 3000 - 4999 OR if the reason
is more than 123 bytespublic abstract void connect() throws IOException
If the connection cannot be established, then an IOException is thrown and the thread is unblocked.
An IllegalStateException is thrown if required parameters of an enabled extension has not been set/enabled.
IOException
- if the connection cannot be establishedIllegalStateException
- if the required parameters of an enabled
extension are not set/enabledpublic abstract ChallengeHandler getChallengeHandler()
ChallengeHandler
that is used during authentication
both at the connect-time as well as at subsequent revalidation-time that
occurs at regular intervals.public abstract int getConnectTimeout()
public abstract Collection<String> getEnabledExtensions()
getNegotiatedExtensions()
API. An empty Collection is returned
if no extensions have been enabled for this connection. The enabled
extensions will be a subset of the supported extensions.public abstract <T> T getEnabledParameter(WebSocketExtension.Parameter<T> parameter)
WebSocketExtension.Parameter
defined in an enabled
extension. If the parameter is not defined for this connection but a
default value for the parameter is set using the method
WebSocketFactory#setDefaultParameter(Parameter, Object)
,
then the default value is returned.
Setting the parameter value when the connection is successfully established will result in an IllegalStateException.
T
- Generic type of the value of the Parameterparameter
- Parameter whose value needs to be setpublic abstract Collection<String> getEnabledProtocols()
public abstract HttpRedirectPolicy getRedirectPolicy()
HttpRedirectPolicy
indicating the policy for
following HTTP redirects (status code 3xx). The default options is
HttpRedirectPolicy.ALWAYS
.public abstract InputStream getInputStream() throws IOException
InputStream
to receive binary messages. The
methods on InputStream
will block till the message arrives. The
InputStream
must be used to only receive binary
messages.
An IOException is thrown if this method is invoked when the connection
has not been established. Receiving a text message using the
InputStream
will result in an IOException.
Once the connection is closed, a new InputStream
should be
obtained using this method after the connection has been established.
Using the old InputStream will result in an IOException.
IOException
- if the method is invoked before the connection is
successfully opened; if a text message is being
read using the InputStreampublic abstract WebSocketMessageReader getMessageReader() throws IOException
WebSocketMessageReader
that can be used to receive
binary and text messages based on the
WebSocketMessageType
.
If this method is invoked before a connection is established successfully, then an IOException is thrown.
Once the connection is closed, a new WebSocketMessageReader
should be obtained using this method after the connection has been
established. Using the old WebSocketMessageReader will result in an
IOException.
IOException
- if invoked before the connection is openedpublic abstract WebSocketMessageWriter getMessageWriter() throws IOException
WebSocketMessageWriter
that can be used to send
binary and text messages.
If this method is invoked before a connection is established successfully, then an IOException is thrown.
Once the connection is closed, a new WebSocketMessageWriter
should be obtained using this method after the connection has been
established. Using the old WebSocketMessageWriter will result in an
IOException.
IOException
- if invoked before the connection is openedpublic abstract Collection<String> getNegotiatedExtensions()
Returns an empty Collection if no extensions were negotiated between the client and the server. The negotiated extensions will be a subset of the enabled extensions.
If this method is invoked before a connection is successfully established, an IllegalStateException is thrown.
IllegalStateException
- if invoked before the connect()
completespublic abstract <T> T getNegotiatedParameter(WebSocketExtension.Parameter<T> parameter)
WebSocketExtension.Parameter
of a negotiated
extension.
If this method is invoked before the connection is successfully established, an IllegalStateException is thrown.
Once the connection is closed, the negotiated parameters are cleared. Trying to retrieve the value will result in an IllegalStateException.
T
- parameter typeparameter
- parameter of a negotiated extensionIllegalStateException
- if invoked before the connect()
completespublic abstract String getNegotiatedProtocol()
If this method is invoked before the connection is successfully established, an IllegalStateException is thrown.
Once the connection is closed, trying to retrieve the negotiated protocol will result in an IllegalStateException.
IllegalStateException
- if invoked before the connect()
completespublic abstract OutputStream getOutputStream() throws IOException
OutputStream
to send binary messages. The
message is put on the wire only when OutputStream.flush()
is
invoked.
If this method is invoked before connect()
is complete, an
IOException is thrown.
Once the connection is closed, a new OutputStream
should
be obtained using this method after the connection has been
established. Using the old OutputStream will result in IOException.
IOException
- if the method is invoked before the connection is
successfully openedpublic abstract Reader getReader() throws IOException
Reader
to receive text messages from this
connection. This method should be used to only to receive text
messages. Methods on Reader
will block till a message arrives.
If the Reader is used to receive binary messages, then an IOException is thrown.
If this method is invoked before a connection is established successfully, then an IOException is thrown.
Once the connection is closed, a new Reader
should be obtained
using this method after the connection has been established. Using the
old Reader will result in an IOException.
IOException
- if the method is invoked before the connection is
successfully openedpublic abstract Collection<String> getSupportedExtensions()
public abstract Writer getWriter() throws IOException
Writer
to send text messages from this
connection. The message is put on the wire only when
Writer.flush()
is invoked.
An IOException is thrown if this method is invoked when the connection has not been established.
Once the connection is closed, a new Writer
should be obtained
using this method after the connection has been established. Using the
old Writer will result in an IOException.
IOException
- if the method is invoked before the connection is
successfully openedpublic abstract void setChallengeHandler(ChallengeHandler challengeHandler)
ChallengeHandler
that is used during authentication
both at the connect-time as well as at subsequent revalidation-time that
occurs at regular intervals.challengeHandler
- ChallengeHandler used for authenticationpublic abstract void setConnectTimeout(int connectTimeout)
connectTimeout
- timeout value in millisecondsIllegalStateException
- if the connect timeout is being set
after the connection has been establishedIllegalArgumentException
- if connectTimeout is negativepublic abstract void setEnabledExtensions(Collection<String> extensions)
connect()
method. The
enabled extensions should be a subset of the supported extensions. Only
the extensions that are explicitly enabled are put on the wire even
though there could be more supported extensions on this connection.
If this method is invoked after connection is successfully established, an IllegalStateException is thrown. If an enabled extension is not discovered as a supported extension, then IllegalStateException is thrown.
extensions
- list of extensions to be negotiated with the server
during the handshakepublic abstract <T> void setEnabledParameter(WebSocketExtension.Parameter<T> parameter, T value)
WebSocketExtension.Parameter
defined in an enabled
extension. The application developer should set the extension
parameters of the enabled extensions before invoking the
connect()
method.
Setting the parameter value when the connection is successfully established will result in an IllegalStateException.
If the parameter has a default value that was specified usingWebSocketFactory#setDefaultParameter(Parameter, Object)
,
then setting the same parameter using this method will override the
default value.
T
- extension parameter typeparameter
- Parameter whose value needs to be setvalue
- of the specified parameterpublic abstract void setEnabledProtocols(Collection<String> protocols)
connect()
is
called.
If this method is invoked after a connection has been successfully established, an IllegalStateException is thrown.
extensions
- list of extensions to be negotiated with the server
during the handshakepublic abstract void setRedirectPolicy(HttpRedirectPolicy option)
HttpRedirectPolicy
indicating the policy for
following HTTP redirects (3xx).option
- HttpRedirectOption to used for following the
redirectsCopyright © 2014. All Rights Reserved.