WebSocketClient (Jetty :: Aggregate :: All core Jetty 7.6.8.v20121106 API)
Date: 2012-11-06

org.eclipse.jetty.websocket

## Class WebSocketClient

- java.lang.Object
- - org.eclipse.jetty.websocket.WebSocketClient

-     public class WebSocketClient
      extends Object

  `WebSocketClient` allows to create multiple connections to multiple destinations that can speak the websocket protocol.

  When creating websocket connections, `WebSocketClient` accepts a `WebSocket` object (to receive events from the server), and returns a `WebSocket.Connection` to send data to the server.

  Example usage is as follows:

         WebSocketClientFactory factory = new WebSocketClientFactory();
         factory.start();

         WebSocketClient client = factory.newWebSocketClient();
         // Configure the client

         WebSocket.Connection connection = client.open(new URI("ws://127.0.0.1:8080/"), new WebSocket.OnTextMessage()
         {
           public void onOpen(Connection connection)
           {
             // open notification
           }

           public void onClose(int closeCode, String message)
           {
             // close notification
           }

           public void onMessage(String data)
           {
             // handle incoming message
           }
         }).get(5, TimeUnit.SECONDS);

         connection.sendMessage("Hello World");

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `WebSocketClient()` Deprecated. Use `WebSocketClientFactory.newWebSocketClient()`
    `WebSocketClient(WebSocketClientFactory factory)` Creates a WebSocketClient with shared WebSocketClientFactory.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `SocketAddress` | `getBindAddress()`
    `Map<String,String>` | `getCookies()` Returns the map of the cookies that are sent during the initial HTTP handshake that upgrades to the websocket protocol.
    `List<String>` | `getExtensions()`
    `WebSocketClientFactory` | `getFactory()`
    `MaskGen` | `getMaskGen()`
    `int` | `getMaxBinaryMessageSize()`
    `int` | `getMaxIdleTime()`
    `int` | `getMaxTextMessageSize()`
    `String` | `getOrigin()`
    `String` | `getProtocol()`
    `Future<WebSocket.Connection>` | `open(URI uri, WebSocket websocket)` Asynchronously opens a websocket connection and returns a `Future` to obtain the connection.
    `WebSocket.Connection` | `open(URI uri, WebSocket websocket, long maxConnectTime, TimeUnit units)` Opens a websocket connection to the URI and blocks until the connection is accepted or there is an error.
    `void` | `setBindAddress(SocketAddress bindAddress)`
    `void` | `setMaskGen(MaskGen maskGen)`
    `void` | `setMaxBinaryMessageSize(int maxBinaryMessageSize)` Set the initial maximum binary message size for a connection.
    `void` | `setMaxIdleTime(int maxIdleTime)`
    `void` | `setMaxTextMessageSize(int maxTextMessageSize)` Set the initial maximum text message size for a connection.
    `void` | `setOrigin(String origin)`
    `void` | `setProtocol(String protocol)`
    `static InetSocketAddress` | `toSocketAddress(URI uri)`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### WebSocketClient

          @Deprecated
          public WebSocketClient()
                          throws Exception

      Deprecated. Use `WebSocketClientFactory.newWebSocketClient()`

      Creates a WebSocketClient from a private WebSocketClientFactory.

      This can be wasteful of resources if many clients are created.

      Throws:
        `Exception` - if the private WebSocketClientFactory fails to start

    - #### WebSocketClient

          public WebSocketClient(WebSocketClientFactory factory)

      Creates a WebSocketClient with shared WebSocketClientFactory.

      Parameters:
        `factory` - the shared `WebSocketClientFactory`

  - ### Method Detail

    - #### getFactory

          public WebSocketClientFactory getFactory()

      Returns:
        The WebSocketClientFactory this client was created with.

    - #### getBindAddress

          public SocketAddress getBindAddress()

      Returns:
        the address to bind the socket channel to
      See Also:
        `setBindAddress(SocketAddress)`

    - #### setBindAddress

          public void setBindAddress(SocketAddress bindAddress)

      Parameters:
        `bindAddress` - the address to bind the socket channel to
      See Also:
        `getBindAddress()`

    - #### getMaxIdleTime

          public int getMaxIdleTime()

      Returns:
        The maxIdleTime in ms for connections opened by this client, or -1 if the default from `WebSocketClientFactory.getSelectorManager()` is used.
      See Also:
        `setMaxIdleTime(int)`

    - #### setMaxIdleTime

          public void setMaxIdleTime(int maxIdleTime)

      Parameters:
        `maxIdleTime` - The max idle time in ms for connections opened by this client
      See Also:
        `getMaxIdleTime()`

    - #### getProtocol

          public String getProtocol()

      Returns:
        The subprotocol string for connections opened by this client.
      See Also:
        `setProtocol(String)`

    - #### setProtocol

          public void setProtocol(String protocol)

      Parameters:
        `protocol` - The subprotocol string for connections opened by this client.
      See Also:
        `getProtocol()`

    - #### getOrigin

          public String getOrigin()

      Returns:
        The origin URI of the client
      See Also:
        `setOrigin(String)`

    - #### setOrigin

          public void setOrigin(String origin)

      Parameters:
        `origin` - The origin URI of the client (eg "http://example.com")
      See Also:
        `getOrigin()`

    - #### getCookies

          public Map<String,String> getCookies()

      Returns the map of the cookies that are sent during the initial HTTP handshake that upgrades to the websocket protocol.

      Returns:
        The read-write cookie map

    - #### getExtensions

          public List<String> getExtensions()

      Returns:
        The list of websocket protocol extensions

    - #### getMaskGen

          public MaskGen getMaskGen()

      Returns:
        the mask generator to use, or null if not mask generator should be used
      See Also:
        `setMaskGen(MaskGen)`

    - #### setMaskGen

          public void setMaskGen(MaskGen maskGen)

      Parameters:
        `maskGen` - the mask generator to use, or null if not mask generator should be used
      See Also:
        `getMaskGen()`

    - #### getMaxTextMessageSize

          public int getMaxTextMessageSize()

      Returns:
        The initial maximum text message size (in characters) for a connection

    - #### setMaxTextMessageSize

          public void setMaxTextMessageSize(int maxTextMessageSize)

      Set the initial maximum text message size for a connection. This can be changed by the application calling `WebSocket.Connection.setMaxTextMessageSize(int)`.
      Parameters:
        `maxTextMessageSize` - The default maximum text message size (in characters) for a connection

    - #### getMaxBinaryMessageSize

          public int getMaxBinaryMessageSize()

      Returns:
        The initial maximum binary message size (in bytes) for a connection

    - #### setMaxBinaryMessageSize

          public void setMaxBinaryMessageSize(int maxBinaryMessageSize)

      Set the initial maximum binary message size for a connection. This can be changed by the application calling `WebSocket.Connection.setMaxBinaryMessageSize(int)`.
      Parameters:
        `maxBinaryMessageSize` - The default maximum binary message size (in bytes) for a connection

    - #### open

          public WebSocket.Connection open(URI uri,
                                  WebSocket websocket,
                                  long maxConnectTime,
                                  TimeUnit units)
                                    throws IOException,
                                           InterruptedException,
                                           TimeoutException

      Opens a websocket connection to the URI and blocks until the connection is accepted or there is an error.

      Parameters:
        `uri` - The URI to connect to.
        `websocket` - The `WebSocket` instance to handle incoming events.
        `maxConnectTime` - The interval to wait for a successful connection
        `units` - the units of the maxConnectTime
      Returns:
        A `WebSocket.Connection`
      Throws:
        `IOException` - if the connection fails
        `InterruptedException` - if the thread is interrupted
        `TimeoutException` - if the timeout elapses before the connection is completed
      See Also:
        `open(URI, WebSocket)`

    - #### open

          public Future<WebSocket.Connection> open(URI uri,
                                          WebSocket websocket)
                                            throws IOException

      Asynchronously opens a websocket connection and returns a `Future` to obtain the connection.

      The caller must call `Future.get(long, TimeUnit)` if they wish to impose a connect timeout on the open.

      Parameters:
        `uri` - The URI to connect to.
        `websocket` - The `WebSocket` instance to handle incoming events.
      Returns:
        A `Future` to the `WebSocket.Connection`
      Throws:
        `IOException` - if the connection fails
      See Also:
        `open(URI, WebSocket, long, TimeUnit)`

    - #### toSocketAddress

          public static InetSocketAddress toSocketAddress(URI uri)

Copyright © 1995-2012 Mort Bay Consulting. All Rights Reserved.