registerApplication (int timeout)

Creates the registration for this application and starts the connection. An ApplicationTimeoutException is thrown if the method does not succeed within the number of seconds specified by the timeout.

If a callback handler is registered and network connectivity is available, the sequence of callbacks as a result of calling registerApplication is:

onRegistrationStatusChanged(RegistrationStatus.REGISTERING, 0, "")
onConnectionStatusChanged(ConnectionStatus.CONNECTING, 0, "")
onConnectionStatusChanged(ConnectionStatus.CONNECTED, 0, "")
onRegistrationStatusChanged(RegistrationStatus.REGISTERED, 0, "")

When the connectionStatus of CONNECTED has been reached and the application's applicationSettings have been received from the server, the application is now in a suitable state for database subscriptions and/or synchronization. If a callback handler is registered and network connectivity is unavailable, the sequence of callbacks as a result of calling registerApplication is:

onRegistrationStatusChanged(RegistrationStatus.REGISTERING, 0, "")
onRegistrationStatusChanged(RegistrationStatus.REGISTRATION_ERROR, code, message)

In such a case, the registration process has permanently failed and will not continue in the background. If a callback handler is registered and network connectivity is available for the start of registration but becomes unavailable before the connection is established, the sequence of callbacks as a result of calling registerApplication is:

onRegistrationStatusChanged(RegistrationStatus.REGISTERING, 0, "")
onConnectionStatusChanged(ConnectionStatus.CONNECTING, 0, "")
onConnectionStatusChanged(ConnectionStatus.CONNECTION_ERROR, code, message)

In such a case, the registration process has temporarily failed and will continue in the background when network connectivity is restored.

As a best practice, if a timeout exception occurs in registerApplication or startConnection, the application should wait for the appropriate callback, and optionally add a user message to the application, "please wait" for example, instead of closing the application. This prevents a build up of start up requests by needlessly restarting the application which can adversely affect performance.

Wait for the application callback, such as onConnectionStatusChanged() if ApplicationTimeoutException is encountered when calling registerApplication (int timeout), instead of closing the application. This allows the application code to catch ApplicationTimeoutException and does not throw an exception.

try 
{ Application.GetInstance().RegsiterApplication(100); } 
catch(ApplicationTimeoutException ex) 
{ 
while (Application.GetInstance().ConnectionStatus == ConnectionStatus.CONNECTING) 
{ Thread.Sleep(100); } 
}

Syntax

public void registerApplication(int timeout)

Parameters

timeout – Number of seconds to wait until the registration is created. If the the timeout is greater than zero and the registration is not created within the timeout period, an ApplicationTimeoutException is thrown (the operation might still be completing in a background thread). If the timeout value is less than or equal to 0, then this method returns immediately without waiting for the registration to finish (a non-blocking call). If the timeout value is less than or equal to 0, then this method returns immediately without waiting for the registration to finish (a non-blocking call).

Examples

Register an Application – Registers the application with a one minute waiting period.
```
app.registerApplication(60);
```

Usage

You must set up the ConnectionProperties and ApplicationIdentifier before you can invoke registerApplication.

The maximum length of the Application ID is 64 characters. The total length of the Application Connection ID cannot exceeds 128 characters. The Application Connection ID format is deviceId__applicationId. The applicationId separator is two underscores.

Application app = Application.getInstance();
// set Application ID - need to match as the server side Application ID
app.setApplicationIdentifier("SMP101");
app.setApplicationCallback(new MyApplicationCallbackHandler());
ConnectionProperties props = app.getConnectionProperties();
props.setServerName("server.mycompany.com");
props.setPortNumber(5001);
LoginCredentials loginCred = new LoginCredentials("supAdmin", "supPwd");
props.setLoginCredentials(loginCred);

SMP101DB.setApplication(app);

if (app.getRegistrationStatus() != RegistrationStatus.REGISTERED)
{
  app.registerApplication();
}