15.4. Making UDP connection requests

This section describes the technique of making UDP connection requests. As with TCP, 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 by calling isOnline on the RemoteService object representing the service. This is not required if your application sends a request at receiving the service online event for the target service.

Let’s see the method for making connection requests:

public void udpConnect(
    RemoteService remoteService,
    int virtualPort,
    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 API version of the service 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;
  • responseHandler is an implementation of the UDPResponseHandler 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 UDPResponseHandler interface:

public interface UDPResponseHandler {
    void onSuccess(
        ResponseContext context,
        DatagramSocket datagramSocket, 
        InetSocketAddress remoteSocketAddress,
        ConnectionMode mode);
    void onError(
        ResponseContext context,
        SoftnetException exception);
}

The method onSuccess is called if the request is successfully processed and the connection is established. It has the following parameters:

  • context is of type ResponseContext, which is the first parameter of any response handler of the platform. The type is described below;
  • datagramSocket is an instance of java.net.DatagramSocket that represents a socket for sending and receiving datagram packets;
  • remoteSocketAddress is an IP address and port of the remote UDP endpoint;
  • 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;	
    // the constructor is omitted
}
  • clientEndpoint specifies the client endpoint that sent the connection request;
  • remoteService represents a remote service to which the request has been made;
  • attachment is state data provided to the udpConnect call.

The onError method of UDPResponseHandler 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 udpConnect method to make a UDP 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 udpConnect call. Before calling it, the code checks whether the service is online. The second argument is the virtual port, specified as 25. The remote service is expected to be listening on this port as it was demonstrated in the previous section. The example implements the UDPRequestHandler interface and uses it as a third 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.udpConnect(remoteService, 10, new MyUDPResponseHandler());
        }
    }
    // the rest of the code
}

// custom implementation of the UDPResponseHandler interface
class MyUDPResponseHandler implements UDPResponseHandler
{
    public void onSuccess(
        ResponseContext context, 
        DatagramSocket datagramSocket, 
        InetSocketAddress remoteSocketAddress,
        ConnectionMode mode) 
    {
        System.out.println(String.format(
            "The UDP 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 UDP connection attempt with the service
            hosted on '%s' has failed with an error '%s'.",
            context.remoteService.getHostname(),
            exception.getMessage()));	
    }
}

TABLE OF CONTENTS