org.atmosphere.wasync

Interface Socket

All Known Implementing Classes:

AtmosphereSocket, DefaultSocket, SerializedSocket

public interface Socket

A Socket represents a connection to a remote server. A Socket abstract the transport used and will negotiate the best Request.TRANSPORT to communicate with the Server.

Depending on the transport used, one or two connections will be opened. For WebSocket, a single, bi-directional connection will be used. For other transport like streaming, server side events and long-polling, a connection will be opened to the server and will be suspended (stay opened) until an event happen on the server. A second connection will be opened every time the fire(Object) method is invoked and cached for further re-use.

As simple as

     Client client = AtmosphereClientFactory.getDefault().newClient();

     RequestBuilder request = client.newRequestBuilder()
             .method(Request.METHOD.GET)
             .uri(targetUrl + "/suspend")
             .encoder(new Encoder<String, Reader>() {        // Stream the request body
                 @Override
                 public Reader encode(String s) {
                     return new StringReader(s);
                 }
             })
             .decoder(new Decoder<String, Reader>() {
                  @Override
                 public Reader decode(String s) {
                     return new StringReader(s);
                 }
             })
             .transport(Request.TRANSPORT.WEBSOCKET)                        // Try WebSocket
             .transport(Request.TRANSPORT.LONG_POLLING);                    // Fallback to Long-Polling

     Socket socket = client.create();
     socket.on("message", new Function<String>() {
         @Override
         public void on(Reader r) {
             // Read the response
         }
     }).on(new Function<IOException>() {

         @Override
         public void on(Throwable t) {
             // Some IOException occurred
         }

     }).open(request.build()).fire("echo");
 

Author:

Jeanfrancois Arcand

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Socket.STATUS The current state of the underlying Socket.

Method Summary

Modifier and Type	Method and Description
void	close() Close this Socket, asynchronously.
Future	fire(Object data) Send data to the remote Server.
Socket	on(Event event, Function<?> function) Associate a Function with an Event.
Socket	on(Function<?> function) Associate a Function with the Socket.
Socket	on(String functionMessage, Function<?> function) Associate a Function with the Socket.
Socket	open(Request request) Connect to the remote Server using the Request's information.
Socket	open(Request request, long timeout, TimeUnit unit) Connect to the remote Server using the Request's information, will timeout if the connection failed to open within a certain time.
Socket.STATUS	status() Return the Socket.STATUS of this Socket.

Method Detail

fire

Future fire(Object data)
     throws IOException

Send data to the remote Server. The object will first be delivered to the set of Encoder, and then send to the server. The server's response will be delivered to the set of defined Function using the opened Transport, e.g for Request.TRANSPORT.WEBSOCKET, the same connection will be re-used and, for others transports, the suspended connection.

Parameters:

data - object to send

Returns:

a Future

Throws:

IOException

on

Socket on(Function<?> function)

Associate a Function with the Socket. When a response is received, the library will try to associated the decoded message (decoded by Decoder) to the defined type of the Function

Parameters:

function - a Function

Returns:

this

on

Socket on(String functionMessage,
          Function<?> function)

Associate a Function with the Socket. When a response is received, the library will try to associated the decoded message (decoded by Decoder) to the defined type of the Function. The default messages are defined by Event but handling of custom message can be done using a FunctionResolver

Parameters:

function - a Function

Returns:

this

on

Socket on(Event event,
          Function<?> function)

Associate a Function with an Event. When the event happen the library will try to associated the decoded event (decoded by Decoder) to the defined type of the Function. The default event are defined by Event but handling of custom event can be done using a FunctionResolver

Parameters:

function - a Function

Returns:

this

open

Socket open(Request request)
     throws IOException

Connect to the remote Server using the Request's information.

Parameters:

request - a Request

Returns:

this

Throws:

IOException - in case the connect fails or a network failure occurs.

open

Socket open(Request request,
            long timeout,
            TimeUnit unit)
     throws IOException

Connect to the remote Server using the Request's information, will timeout if the connection failed to open within a certain time.

Parameters:

request - a Request

timeout - the maximum time to wait

unit - the time unit of the timeout argument

Returns:

this

Throws:

IOException - in case the connect fails or a network failure occurs.

close

void close()

Close this Socket, asynchronously.

status

Socket.STATUS status()

Return the Socket.STATUS of this Socket.