12.2.1. Connectivity status event handler

The approach for handling client connectivity status events closely mirrors that of services, as outlined in the preceding chapter, but there are some slight differences. So, we provide a similar description.

Here is the handler signature:

void onConnectivityChanged(ServiceEndpointEvent e)

To get an updated connectivity status do the following. In the handler’s body call the getEndpoint method on the ‘e’ parameter. It returns the endpoint of type ClientEndpoint which invoked the handler. Then call the endpoint’s getConnectivity method. It has the following signature:

public EndpointConnectivity getConnectivity()

The method returns an object of type EndpointConnectivity with the following members:

public class EndpointConnectivity {
    public final ConnectivityStatus status;
    public final SoftnetError error;
    public final String message;
}
  • status of enumeration type ConnectivityStatus. It is the current connectivity status of the client endpoint. Possible values and their meanings are described below;
  • error of enumeration type SoftnetError. The possible connectivity errors are given below. If there is no error, its value is NoError;
  • message contains the error message if error differs from NoError.

The described steps may look like the following:

public void onConnectivityChanged(ClientEndpointEvent e) {
    ClientEndpoint clientEndpoint = e.getEndpoint();
    EndpointConnectivity connectivity = clientEndpoint.getConnectivity();

    System.out.println(String.format(
        "Connectivity Status: %s, Error: %s, Message: %s",
        connectivity.status,
        connectivity.error,
        connectivity.message));
}

The next is the ConnectivityStatus enumeration:

public enum ConnectivityStatus
{
    Disconnected,
    AttemptToConnect,
    Connected,
    Down,
    Closed
}

When the client endpoint is just instantiated, the connectivity status is Disconnected. The endpoint is inactive. Calling the disconnect method also sets the status to Disconnected. Calling the close method on the endpoint sets the status to Closed, making the endpoint unusable. The remaining possible status values reflect the current stage of the control channel establishment procedure. Calling the connect method brings the endpoint to the active state. Once in this state, the endpoint starts a procedure of establishing the control channel. Also, this procedure starts when the existing channel has been detected as broken and has to be re-established. Let’s consider how this procedure works.

Stage 1. The procedure starts from setting the connectivity parameters to the following values and raising a connectivity event:
     status: ConnectivityStatus.AttemptToConnect;
     error: SoftnetError.NoError;
     message: null.
Then the endpoint makes a request to the Softnet Balancer to locate a Softnet Tracker running the target site. Depending on the result, there are three possible scenarios:

  1. The Balancer returns an IP-address of the tracker. What happens next is described below in stage 2;
  2. The Balancer does not find the client account for a client URI provided to the method ClientEndpoint.create. The endpoint completes operating with a fatal error. The connectivity parameters take the following values:
         status: ConnectivityStatus.Down;
         error: SoftnetError.ClientNotRegistered;
         message: <error description>.
    To notify the application of this status, the endpoint raises a connectivity event again;
  3. The endpoint fails to make the request due to a network error. The connectivity parameters take the following values:
         status: ConnectivityStatus.AttemptToConnect;
         error: SoftnetError.NetworkError;
         message: <error description>.

The endpoint raises a connectivity event so that the application could get a new status. After a certain period of time, the endpoint repeats the procedure. As for waiting time between two consecutive attempts, it starts from one second and doubles at each unlucky attempt until it reaches one minute. Then each subsequent attempt is made with a one-minute wait. This process continues until the Softnet Balancer returns some result described in the first two cases.

Stage 2. Here, we consider what happens when the Softnet Balancer returns an IP-address of the Tracker. This is the first case described in stage 1. The endpoint makes attempt to establish a connection with the Softnet Tracker and if it is a stateful client, performs authentication. Here, we have three possible scenarios:

  1. The endpoint establishes a connection with the Tracker and if it is a stateful client, successfully authenticates. The connectivity parameters take the following values:
         status: ConnectivityStatus.Connected;
         error: SoftnetError.NoError;
         message: null.
    The endpoint raises a connectivity event. As the connectivity status is Connected, the endpoint starts establishing the client status. This process is described in the next section;
  2. This step is true for stateful clients. The endpoint establishes a connection with the Tracker but fails to perform authentication. The endpoint completes operating with a fatal error. The connectivity parameters take the following values:
         status: ConnectivityStatus.Down;
         error: SoftnetError.PasswordNotMatched;
         message: <error description>.
    Then the endpoint raises a final connectivity event;
  3. The endpoint fails to establish a connection with the Tracker due to a network error. The connectivity parameters take the following values:
         status: ConnectivityStatus.AttemptToConnect;
         error: SoftnetError.NetworkError;
         message: <error description>.

Then the endpoint raises a connectivity event. After a certain period of time, the endpoint repeats the procedure as it was described earlier for the case 3 of the procedure’s stage 1.

The procedure works until the connectivity status is Connected or a fatal error occurs. After the channel has been successfully created, the endpoint starts establishing the client status. The client can interact with services only if it gets the Online status. However, the idea behind Softnet is such that regardless of the client status, the endpoint must still be connected to the Tracker. Thanks to this feature, the client restarts automatically with a new status when the administrator changes its status through the management panel.

The endpoint can be temporarily deactivated, i.e., disconnected from the site, by calling the disconnect method:

public void disconnect()

Later, the endpoint can be activated again by calling the connect method. When the application terminates, it must call the endpoint’s close method, which releases all resources associated with it:

public void close()

TABLE OF CONTENTS