15.2. Making TCP connection requests

This section describes the technique of making TCP connection requests. The client sends a request to the virtual port on which the remote service is listening. Before making a request, it is desirable to check whether the remote service is online – for this, the RemoteService has a method isOnline. This is not required if your application sends a request at receiving the service online event for the target service (see the section “Interface ClientEventListener”).

Let’s see the method for making connection requests:

public void tcpConnect(
    RemoteService remoteService,
    int virtualPort,
    TCPOptions tcpOptions,
    TCPResponseHandler responseHandler, 
    RequestParams requestParams)
  • remoteService is the first parameter of any request method of the client endpoint. Before making a request, your app can check the online status and the version of the service’s primary API against it. Note that a single-service endpoint has overloaded request methods without this parameter;
  • virtualPort is a virtual port on which the remote service is listening;
  • tcpOptions specifies the receive and send buffer sizes that will be assigned to the TCP connection at the client side;
  • responseHandler is an implementation of the TCPResponseHandler interface that client app provides to the method. It is discussed below;
  • requestParams is an optional parameter whose structure is shown next.

RequestParams is a unified structure that clients use to specify additional parameters for any request method of the platform. It has three fields:

public class RequestParams {
	public final Object attachment;
	public final int waitSeconds; 
	public final SequenceEncoder sessionTag;
}
  • attachment contains any attached data you want to pass to the respone handler;
  • waitSeconds is the wait timeout after which the request method completes with an exception of type TimeoutExpiredSoftnetException. Its default value is zero, which sets the default timeout value to 30 seconds;
  • sessionTag is used to provide information about the session in the context of which the request will be made. The data size is limited to 128 bytes.

Next to consider is the TCPResponseHandler interface:

public interface TCPResponseHandler {
	void onSuccess(ResponseContext context, SocketChannel socketChannel, ConnectionMode mode);
	void onError(ResponseContext context, SoftnetException exception);
}

The onSuccess method is invoked if the request is successfully processed and the connection is established. Let’s see its parameters:

  • context is of type ResponseContext, which is the first parameter of any response handler of the platform. The type is described below;
  • socketChannel is a Java NIO SocketChannel object that represents the established TCP connection;
  • mode provides the mode of the connection – P2P or Proxy.

The ResponseContext class has the following fields:

public class ResponseContext {
    public final ClientEndpoint clientEndpoint;
    public final RemoteService remoteService;
    public final Object attachment;	
}
  • clientEndpoint is the client endpoint that made the connection request;
  • remoteService represents a remote service to which the request has been made;
  • attachment is the state data passed through the tcpConnect call.

The onError method of TCPResponseHandler is invoked if the connection request fails. The second parameter of type SoftnetException specifies an error. Possible exceptions are listed below:

  • ServiceOfflineSoftnetException – the remote service is offline;
  • ConnectionAttemptFailedSoftnetException – the connection attempt failed. The details are provided in the exception message;
  • AccessDeniedSoftnetException – the client does not have enough permissions to establish this connection;
  • PortUnreachableSoftnetException – the remote service is not listening on the virtual port specified in the connection request;
  • ServiceBusySoftnetException – the server’s backlog of pending connections is full;
  • TimeoutExpiredSoftnetException – the connection request timeout expired.

Below is an example of using the described method to make a TCP connection request. The client endpoint is assumed to be single-service. The RemoteService object is retrieved by calling findService(0) and used as the first argument to the tcpConnect call. Before calling it, the code checks whether the service is online. The second argument is the virtual port, specified as 10. The remote service is expected to be listening on this port as it was demonstrated in the previous section. The example implements the TCPRequestHandler interface and uses it as a fourth argument to the method call:

public static void main(String[] args) {
    // the client endpoint creation code is omitted
    if(softnetClient.isSingleService()) {
        RemoteService remoteService = softnetClient.findService(0);
        if(remoteService.isOnline()) {
            softnetClient.tcpConnect(remoteService, 10, null, new MyTCPResponseHandler());
        }
    }
    // the rest of the code
}

// custom implementation of the TCPResponseHandler interface
class MyTCPResponseHandler implements TCPResponseHandler {
    public void onSuccess(ResponseContext context, SocketChannel socketChannel, ConnectionMode mode) {
        System.out.println(String.format(
            "The TCP connection has been established with
            the service hosted on '%s'. 
            The connection mode is '%s'.", context.remoteService.getHostname(),
            mode));
        // the rest of the code
    }
    public void onError(ResponseContext context, SoftnetException exception) {
        System.out.println(String.format(
            "The TCP connection attempt with the service
            hosted on '%s' has failed with an error '%s'.",
            context.remoteService.getHostname(),
            exception.getMessage()));	
    }
}

TABLE OF CONTENTS