How Routes and Services are used to persist and restore the model remotely

Just as with the local routes and services which are described here, remote routes are configured through the routes and services files. The main difference is that the remote route passes control over to a webserver which in turn has it's own set of route and service files which are synchronised with the client. We can take a look at the Welcome page which contains components to get user logon information as shown in figure 1.

In this page we just want to logon to the server and establish a session with the server. We start by creating the LogonRoute in the routes.xml file which is shown in listing 1.

The ClientLogonService extends the Carousel AuthenticationService in order to take care of the client side user authentication. The selfmanaged attribute is set to true meaning that the user will be prompted to logon if they have not already done so. The checksessionalive attribute tells the AuthenticationService to check that the session with the server is still alive. The modelid attribute specifies the path into the XModel where the user id will be stored.

The SessionManager class establishes the server session and makes sure that a valid session is in place for each call. As with the AuthenticationService class the selfmanaged attribute of the SessionManager class tells it to take care of session management automatically. The modelid attribute specifies the path into the XModel where the session id is stored.

The XHttpClientServiceProxy ServiceProxy class is the point in the route where service calls are passed over to the webserver. The url attribute specifies the address at which the tomcat XServiceServlet is located.

This route now needs to be referenced from the services.xml file as shown in listing 2

Now the server side routes and services for the LogonRoute route can be configured. We'll start by looking at the serverroutes.xml file which defines the LogonRoute as shown in listing 3.

The LogonService class which extends the AuthenticationService overloads the checkCredentials function of the AuthenticationService class in order to check the logon credentials against the database. We won't go into the details of the checkCredentials just yet but suffice to say that a boolean value is returned depending on the outcome of the check.

The ServerSessionManager is the server side version of the SessionManager and creates a new session if there isn't already one otherwise it checks that the current session is valid.

As with the client routes, the server routes need to be referenced from a services file. In this case the reference in declared in the serverservices.xml file as shown in listing 4.

  
  ...

Now in order to call this route the logon code from the Welcome class can be examined. Listing 5 shows the code which calls the service.

  ServiceHelper serviceHlp = new ServiceHelper( "LogonService" );
        
  serviceHlp.setPassParam( SessionManager.ARG_NAME_CHECKPARAM, 
        LogonService.ARG_NAME_USERID );
  serviceHlp.setPassParam( LogonService.ARG_NAME_USERID, userIdEdit.getText() );
  serviceHlp.setPassParam( LogonService.ARG_NAME_PASSWORD, passwordEdit.getText() );
  serviceHlp.setPassParam( ClientLogonService.ARG_NAME_AUTOPROMPT, "false" );
  serviceHlp.callService( false );
  boolean success = serviceHlp.getArgs().getReturnParam( 
        LogonService.ARG_NAME_USERID ) != null;

The first line returns a reference to a ServiceHelper class. This class is explained in more detail in the secion on local routes. Next the SessionManager.ARG_NAME_CHECKPARAM parameter is set to LogonService.ARG_NAME_USERID. This ensures that the session can check that the user id logged on with is what is stored in the server side session.

Now the LogonService.ARG_NAME_USERID and LogonService.ARG_NAME_PASSWORD parameters are set to the values entered in the edit components as shown in figure 1 above.

The ClientLogonService.ARG_NAME_AUTOPROMPT parameter is a custom parameter which is used in the ClientLogonService class to suppress automatic prompts if the logon fails. This is the only instance in the application where we will want to suppress automatic logons in this way.

Finally the service is called and returns to execute the next line. Here we check that the returned LogonService.ARG_NAME_USERID parameter is not null. If it is null it means that the authentication has failed and an error is shown otherwise the function returns true.

That deals with setting up the authentication and session managment for the application. This will need to be done whenever a call to the server is made so each route which passes off to the server needs to include the ClientLogonService and SessionManager ServiceProxy classes.

Now we can take a look at another route which will retrieve the selected account from the server. The route which handles this is the QueryRoute route which is declared in the routes.xml file as shown in listing 6.

Once again the route includes the ClientLogonService, the SessionManager and the XHttpClientServiceProxy ServiceProxy classes. The QueryService and TransformService classes will be explained a bit more when we take a look at the service call.

And again the route needs to be referenced from the services.xml file as shown in listing 7.

The server side declarations in the serverroutes.xml and serverservices.xml files are shown in listing 8 and 9 respectively.

If the user has chosen to work offline from the welcome page, then no session will be established with the server. So if an attempt is made to contact the server subsequently the user needs to be prompted to logon. This functionality is handled automatically by the AuthenticationService when it's attribute is set to selfmanaged. the user will be presented with the logon dialog shown below in figure 2.

Now we can take a look at the AccountRetrieve class which takes care of fetching account and contact information from the server.

  public void retrieveAccount( String id )
  {
    ServiceHelper svcHelp = new ServiceHelper( "QueryService" );

    svcHelp.setPassParam( QueryService.ARG_NAME_QUERY, "AccountRetrieve" );
    svcHelp.setPassParam( TransformService.ARG_NAME_TRANSFORMNAME, "AccountDetails" );
    svcHelp.setPassParam( TransformService.ARG_NAME_TRANSFORMPARAM, 
        QueryService.ARG_NAME_RESULTSET );
    svcHelp.setPassParam( QueryService.ARG_NAME_NUMPARAMS, "1" );
    svcHelp.setPassParam( QueryService.ARG_NAME_PARAMVALUE + "0", id );
    svcHelp.callService();
  }  

The QueryService.ARG_NAME_QUERY parameter specifies the name of the query which will be executed in the database.xml file. The TransformService.ARG_NAME_TRANSFORMNAME parameter specifies the name of the file which will transform the database data into the model structure which can be used by the XUI XModel. In this case the transformation name is AccountDetails which mean that the AccountDetails.xsl file will be used to transform the data. The TransformService.ARG_NAME_TRANSFORMPARAM parameter specifies the name of the return parameter which will contain the result of the data transformation.

The QueryService.ARG_NAME_NUMPARAMS parameter specifies the number of arguments which will be passed to the PreparedStatement in the database.xml file. Each individual PreparedStatment argument is specified by the QueryService.ARG_NAME_PARAMVALUE parameter by appending the zero-based index of the parameter to it. The parameter itself in this case is id which is the id of the account which has been selected.