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

The CacheManager is used to determine whether or not the accounts are cached or not. The cache manager is described in the section which can be found here. One of the functions of the CacheManager is to open the account cache file and to restore it to the XModel. In order to do this a local route is setup in the routes.xml file as shown in listing 1.

The new route needs to be referenced from a service which is declared in the services.xml file as shown in listing 2.

  
    
  ...

The FileSave ServiceProxy class is part of Carousel and the carousel.jar file needs to be included in the classpath in order to run it. The StateManager is a custom ServiceProxy class and shows how custom classes can be built up into a reusable library. Whenever the cache manager saves or opens the cache file it does so by using the local DatasetSaveRoute route. The saveCacheFile method of the CacheManager class shown in listing 3 is used to save the cache information via a local route.

public void saveCacheFile()
{
  ServiceHelper svcHelp = getFileServiceHelper( FileSave.ARG_VALUE_SAVE, 
        StateManager.ARG_VALUE_MODELOUTPUT );
  svcHelp.setPassParam( FileSave.ARG_NAME_OVERWRITE, 
  FileSave.ARG_VALUE_OVERWRITE_YES );
  svcHelp.callService();
}

private static ServiceHelper getFileServiceHelper( String fileMode, String modelMode )
{
  ServiceHelper svcHelp = new ServiceHelper( "DatasetSaveService" );
  svcHelp.setPassParam( FileSave.ARG_NAME_DIR, XModelHelper.getTempVar( "userdir" ) );
  svcHelp.setPassParam( FileSave.ARG_NAME_FILENAME, cacheFileName );
  svcHelp.setPassParam( FileSave.ARG_NAME_MODE, fileMode );

  svcHelp.setPassParam( StateManager.ARG_NAME_MODELPATH, "retrievedaccounts" );
  svcHelp.setPassParam( StateManager.ARG_NAME_OUTPUTPARAM, 
  FileSave.ARG_NAME_CONTENTS );
  svcHelp.setPassParam( StateManager.ARG_NAME_OPERATION, modelMode );
  return svcHelp;
}

The function begins by calling the getFileServiceHelper function in order to get a reference to the ServiceHelper class which is a simple utility class to retrieve ServiceProxy classes from the XModel.

Once retrieved, the parameters of the ServiceContext can be set for the call to the service. The ARG_NAME_DIR of the FileSave ServiceProxy class is set in order to specify the directory of the file and the ARG_NAME_FILENAME parameter is set to specify the name of the saved file.

The ARG_NAME_MODE parameter is set to the value of the fileMode variable which in the case of saving the file is ARG_VALUE_SAVE.

Next the StateManager class parameters need to be set. The ARG_NAME_MODELPATH specifies the path into the model which will be persisted which in this case is retrievedaccounts. The ARG_NAME_OUTPUTPARAM is used by the StateManager to output the resulting model data. The name of the parameter in this case is ARG_NAME_CONTENTS. Finally the ARG_NAME_OPERATION parameter is set to the modelMode variable.

Now back in the code in listing 4, the ARG_NAME_OVERWRITE of the FileSave class is set to ARG_VALUE_OVERWRITE_YES ensuring that the file will be overwritten when found and will not return an error.

The callService method of the ServiceHelper class as shown in listing 5 is called.

  public Object callService()
  {
    return callService( true );
  }
  
  public Object callService( boolean autoPrompt )
  {
    args.setPassParam( SessionManager.ARG_NAME_CHECKPARAM, 
        LogonService.ARG_NAME_USERID );
    Object ret = node.get( context );
    if ( autoPrompt ) {
      removeUnwantedErrors( context );
      if ( context.hasErrors() )
        showErrorDialog( context );
    }
    return ret;
  }

The callService sets the ARG_NAME_CHECKPARAM is set even though it will simply be disregared for local routes. Next the get method of the XServiceModelNode is called in order to make the service call. The hasErrors function of the ServiceContext class checks to see if any errors have occurred during the call and displays the errors in an error dialog if there are any.

Once saved, the cachedaccounts.xml file will be saved to the directory being used by the Sugar Rich Client. Now in order to reopen the file and restore it to the model the code shown in listing 5 is used.

  public static void openCacheFile()
  {
    ServiceHelper svcHelp = getFileServiceHelper( FileSave.ARG_VALUE_OPEN, 
        StateManager.ARG_VALUE_MODELRESTORE );
    svcHelp.callService();
  }  

This method, once again, calls the getFileServiceHelper function in order to setup the ServiceHelper class but this time the FileSave.ARG_VALUE_OPEN and StateManager.ARG_VALUE_MODELRESTORE parameters are used to open the file and restore the state.