Home

Basics

This library uses socketio_client.Socket in order to expose its api to users. Its contructor is package private, so you can't instantiate it directly from your code. Instead, the library exposes a builder class named socketio_client.IO. Here is an example of a socketio_client.Socket that connects to a server at endpoint http://localhost:3000/.

Socket socket = IO.of("http://localhost:3000/")
                  /* any options */
                  .socket();
socket.open();

Options

Since this library exposes socketio_client.IO as a builder for sockets, it also takes on the responsibility of configuring them. Available options, their explanations and default values are explained below.

• String[] transports, this option indicates which transports (polling or websocket) the client wants to use. Available choices are PollingTransport.NAME and WebSocketTransport.NAME, which respectively causes polling and websocket transports to be used.

Note: By default, transports array includes both of these values, which causes the transport to start with polling connection, and then upgrade to websocket connection, if possible.

If you want to use only one of them exclusively, you can use pollingOnly() or webSocketOnly() options to specify. For example:

// By default, it will start with a polling transport,
// and then will try to upgrade to websocket transport, if possible.
Socket socket = IO.of("http://localhost:3000/")
                  .socket();

// This socket will use polling transport only.
Socket socket = IO.of("http://localhost:3000/")
                  .pollingOnly()
                  .socket();

// This socket will use websocket transport only.
Socket socket = IO.of("http://localhost:3000/")
                  .webSocketOnly()
                  .socket();

• IO#query(String key, String value), this method allows users to register query parameters that will be included in requests. For example:

IO.of(url)
  .query("key1", "value1")
  .query("key2", "value2")
  .socket()

• IO#header(String key, String value), this method allows users to register headers that will be included in requests.

IO.of(url)
  .query("header1", "value1")
  .query("header2", "value2")
  .socket()

Note: By nature, polling transport will do recurring get requests, which will include all the headers and query parameters with each request. Websocket transport however, will only include these informations in the initial connection request, since once the underlying connection is upgraded to use the websocket protocol, it is no longer http that's in use, but rather websocket protocol.

• IO#path(String path), by default, socket.io framework attaches itself to the path /socket.io/, which is exactly the path this library makes its requests to. But you can configure your socket.io server to intercepts connections at a different path rather than the default one. In that case, you have to configure your socketio_client.Socket instance as well, so that they can send their requests to valid paths. Example:

IO.of("http://localhost:3000/")  
  .path("/custom_path_name")  
  .socket()

Note, notice that you don't include the custom path name in the url that you pass as a parameter to of(String url) function. That's for a reason. Socket.io framework has a concept called namespaces which allows a socket.io server to group connections. If you pass http://localhost:3000/custom_path_name/ as a parameter to of(String url) function, the /custom_path_name part will be interpreted as the namespace rather than the actual connection path. That's why you need to call the path(String path) to designate the path you want to connect to.

• IO#noReconnect(), prevents the client from making a reconnect attempt when the underlying connection is abruptly closed. By default, the socket.io client will attempt to reconnect on connection loss.

IO.of("http://localhost:3000/")  
  .noReconnect()  
  .socket()

• IO#noMultiplex(), by default, two or more socket.io client objects can share the same connection, but only if they all connect to the same path and only if they are all registered under different namespaces. If you don't want your client objects to share the same connection, even if they are able to, use noMultiplex() option.

IO.of("http://localhost:3000/")  
  .noMultiplex()  
  .socket()

• IO#callFactory(okhttp3.Call.Factory callFactory), this option allows you to provide your own okhttp3.Call.Factory, which is used by the polling transport when making GET and POST requests for reading and writing, respectively.

Note: This also allows you to register SSL/TLS capable okhttp3.Call.Factory so that you can talk over https. For an example, see Secure Connections.

• IO#webSocketFactory(okhttp3.WebSocket.Factory webSocketFactory), this option allows you to provide your own okhttp3.WebSocket.Factory, which is used by the websocket transport to initiate a websocket connection.

Note: This also allows you to register SSL/TLS capable okhttp3.WebSocket.Factory so that you can talk over wss. For an example, see Secure Connections.