The ModelDesigner Server

The main role of the ModelDesigner Server (MDS) consists in executing a model against a database of biological sequences. Usually, the model is created with the ModelDesigner client application from which that execution is started. As a side role of this fundamental function, MDS handles connection(s) to Prolog server(s) that actually do the job of searching for models in sequences.

In addition to this fundamental role MDS handles an execution queue, a list of system sequence databases and a list of user-uploaded databases.

The execution queue stores all the execution requests (i.e., queries) sent by MDS clients.

The list of system sequence databases is made of the sequence DBs installed by the MDS administrator. Usually, those DBs are the major ones used in bioinformatics, such as Uniprot (protein sequences) and GenBank (DNA sequences), for example. This role of the MDS allows a user to easily access large sequence databases.

The list of user-uploaded sequence databases is made of the sequence DBs uploaded by a MDS client onto the server. This role of the MDS allows a user to search for models on its own sequences.

2.2. General architecture

MDS is a Java-based application server relying upon the JSP (1.2) - Servlets (2.3) technology. As explained below, the server is made of a set of Servlets responsible for executing services required by ModelDesigner clients. The fundamental service consists in executing a model against a sequence database, as follows. From the ModelBuilder (i.e. the ModelDesigner client module exploited by users to visually create a model), a user requests a model execution. First, the client automatically requests to the MDS the list of available databases. That list is then presented to the user from which he/she chooses a DB of interest. Upon validation of the DB selection, the client sends to the server all the necessary information for the query execution: a logol script (i.e., the SVG-based representation of the model), an XML formatted representation of the visual model, and the name of the sequence database. Upon reception of this information, the MDS validates it, then stores that data on disk. A unique Request Identifier (RID) is then sent back to the client application. That RID is also introduced, on the server side, within the queries queue. That queue is frequently and automatically scanned by the server to pick one RID and to start an execution as soon as a Prolog server is available. One to several such servers are available for MDS to be used in parallel.

As for now, the MDS runs within a Tomcat Java application server.

Figure 2-1. The ModelDesigner server architecture.

2.3. The server at work

Here is a more precise description of the server roles (also called services). In addition, to better present the server architecture, the name of the servlets responsible for answering a service is presented too.

2.3.1. Available sequence database(s)

The servlet MDAvailableDatabases is responsible for sending to the client the list of available sequence databases. As stated previously, available databases are of two types: system (also called public) and user. A public database is installed by a system administrator on the server side. Usually they are huge databases, such as SwissProt, UniProt, Genbank, etc. A user database is one that has been installed by the client (see servlet MDDatabaseUploader below).

2.3.2. Installing a user database on the server side

The serlvet MDDatabaseUploader can receive from the client a set of sequences (FASTA formatted) to be installed on the server side. These sequences are saved in a file that can then be used by the client to perform a search with this particular database. It is very important to note that the usage of a client database is restricted to the client that requires the installation on that database on the server side.

The servlet MDCheckDBExistenz is used by the server to figure out if a particular user database already exists on the server side.

2.3.3. Query execution

The servlet MDStartSearching is responsible for executing a query (i.e. a sequence model) against a particular database. That servlet performs its job using classes MDQueryEngine and MDQueryExecStatus. It is worth noting that the MDStartSearching can also be used to stop the execution of a query previously started.

2.3.4. Query execution status

The servlet MDQueryStatus is responsible for sending to the client the current status of a query. It works in relation with class MDQueryExecStatus.

Actually, when the MDStartSearching starts a query, it creates an instance of class MDQueryExecStatus and pass it to an instance of class MDQueryEngine. During its work, MDQueryEngine maintains up to date the content of the object MDQueryExecStatus. Knowing that this object is also shared with the ExecutionContext of the ModelDesigner server, MDQueryStatus can access the content of the MDQueryExecStatus object, then sends back to the client that information.

2.3.5. Uploading the results of a particular query

The servlet MDFetchResult is responsible for sending to the client the results of a query. When this servlet is invoked, it first checks if the query is terminated. If true, the servlet sends back to the client a Zipped file containing all the data related to the query execution and its results.

2.3.6. Synchronous vs. asynchronous server answers

All but MDStartSearching servlets work synchronously. Actually, MDStartSearching uses a system similar to the one exploited on the NCBI's BLAST server: when the server receives a query, it assigns a unique identifier to that query. The identifier is immediately returned to the client, while the query will be executed as soon as some computer ressources are available. The client can then use the unique identifier to query the server, asking for the availability of the results. Within the ModelDesigner server, that unique identifier is called RID. In addition to uniquely identified a query, the RID is used:

to securely identify a client. Since the RID is computed using the client IDs (user name and computer IP address), a client A cannot ask for the results of client B.
to store on the server side all the files related to a particular query. Indeed, the RID is used to create a temporary directory on the server side.

It is worth noting that a similar system of RIDs is used by the ModelDesigner server to handle user databases.

Chapter 3. Using the ModelDesigner server

3.1. General presentation

If not already done, you have to carefully read the manual Installing a ModelDesigner developper workstation to read about the architecture, the deployment procedure and the usage of the ModelDesigner developper bundle.

3.2. Modifying, compiling and testing the server

3.2.1. Preparing the system

As fow now, there are no test classes associated to the MDS source code. Use the following procedure to test any modifications made on this code. It is worth noting that this procedure requires two ModelDesigner modules: appserver (of course: this is the MDS) and gui (the client application able to connect and to use the MDS). Please, refer to the manual Installing a ModelDesigner developper workstation to install these two modules. The rest of this document supposes you have read that manual!

Switch to the appserver home directory, then check if you can find there the following files (they are known as the management files of a ModelDesigner module): build.xml, common.xml, tomcat.properties and version.properties. If this is not the case, do the following:

hibiscus%  cp ./scripts/*.xml .
hibiscus%  cp ./scripts/*.properties .

This will copy the Ant files (build.xml and common.xml) and configuration files (tomcat.properties and version.properties) you need to manage the appserver from the command-line.

Please, check the tomcat.properties file to figure out if the directory reported there is valid for your installation; that directory is the place where you deployed the Tomcat server already configured to run MDS.

3.2.2. Starting/stopping the servers

When using a developper installation of ModelDesigner, you install and run the entire system (one client, one MDS and two Prolog servers) on a same computer: yours! So, before doing anything, you need to check if the three servers are already running. To figure out if Tomcat (and MDS) is running:

hibiscus%  ps -ef | grep tomcat

Examine the output of that command, you can quickly see if Tomcat is running. Then, check out if the Prolog servers are running:

hibiscus%  ps -ef | grep sicstus

Again, by examining the output of that command, you can quickly see if Sicstus Prolog is up and running.

We are about to start from freshly started servers. So if Tomcat is running, here is the procedure to stop it:

hibiscus%  ant stop

This command will run the stop target described in the Ant's build.xml. If you look at that file, you can see that it invokes the Tomcat command that stops the server.

In a similar way, if Sicstus is running, you have to use the Linux kill command (this is using the brute force, but unfortunately there is not other way to stop a Sicstus Prolog server):

hibiscus%  kill -9 <PID>

where <PID> is a Sicstus Prolog process ID: that ID is given by the ps command previously used to check out if Sicstus is running. So, execute such a kill command to stop every Sicstus Prolog server that is running on your computer.

Now, starting all servers is quite easy:

hibiscus%  ant prolog & 
hibiscus%  ant start &

The first command starts the Sicstus Prolog servers, while the second one starts the Tomcat/MDS server.

3.2.3. Deploying and testing MDS code modification

Suppose you have made some modifications on the source code of MDS. How to test the new code? First of all, compile the code to check if your changes do not report any errors:

hibiscus%  ant compile

Then stops the Tomcat/MDS server, and restarts it:

hibiscus%  ant stop
hibiscus%  ant start &

If you have a look at the Ant file, you will see that the start target actually does behing the scene a nice job for you: it recompiles the entire source code, deploys that new compiled code within the Tomcat webapps directory, then starts Tomcat which, in turns, will start MDS.

As stated above, we are going to test the MDS update with the ModelDesigner client. To do so, prepare a Jar distribution of the client part of MDS:

hibiscus%  ant distrib

This command will prepare in the distrib directory of the appserver module a Jar file (hereafter called MDS-Jar) containing the compiled code allowing the ModelDesigner client to connect the MDS. Then, you copy MDS-Jar to the jar directory of the gui module. Finally, switch to the home directory of that module, and run the client application:

hibiscus%  ant run

From the client, you can now test the MDS modifications you made.

3.2.4. Committing the changes to CVS

As soon as you have successfully updated the code of the MDS, do not forget to commit the new source code files. It is not necessary to commit the MDS-Jar located in the distrib directory of the appserver module. However, it is absolutely necessary to commit the one you installed in the jar directory of the gui module. Otherwise you are going to be in real trouble by having a client application that cannot connect the server part!

3.2.5. Beware of Ant scripts conflicts

In this chapter, you have been introduced to the scripts that allow you to compile and deploy the MDS source code. In the manual Installing a ModelDesigner developper workstation, you have been introduced to the scripts that allow you to start/stop the MDS from within the gui module. Do not mix those scripts altogether. The former scripts (those from the appserver) allow you to work on the source code of the MDS. The latter scripts (those from the gui) allow you to only start/stop a MDS while working on the source code of the gui module. This is the reason why it is important to check if the Tomcat/MDS/Prolog servers are running BEFORE working on any development copies of ModelDesigner: always shutdown all development servers, then restart them from fresh if you do not remember when and how they were started. This is a good practice to avoid being in trouble.

3.2.6. Updating/committing management files

Each ModelDesigner module (core, client and appserver) is shipped with a set of mangement files that are located in the scripts directory of their distribution. To use these scripts, you have to copy them to the home directory of the corresponding module; this is actually what we did previously (see Section 3.2.1 ). If you want to modify these files, you do that on the copy of these files located in the home directory of the module. Then you test you modifications. As soon as you are ready to commit the changes, you copy the updated files back to the scripts directory, then you do the commit. We now give an example of that procedure.

You have certainly noticed that MDS-Jar is stamped with a version number. That number is actually set up in the management file version.properties located in the home directory of the appserver module. That version number can be modified, however do not forget to commit the version.properties to CVS. To do this, follow that procedure from the home directory of the appserver module:

hibiscus%  cp version.properties scripts
hibiscus%  cd scripts
hibiscus%  cvs commit -m "blabla" version.properties

Such a procedure stands for all management files of the appserver module, namely: build.xml, common.xml, tomcat.properties and version.properties.

Chapter 4. The ModelDesigner server configuration files

4.1. MDS configuration files for Tomcat

The directory conf of the appserver module contains the configuration files of the MDS that have to be installed within Tomcat. The following table presents them with a description of their roles:

Table 4-1. MDS configuration files

File name	Description
web.xml	This is the standard required Tomcat file describing the MDS application. In this file you can find some properties used by the MDS to access its resources: path to store queries and databases.
MDServer_DB.conf	Contains the path to the system databases. To update the list of system databases available to the ModelDesigner clients, this is the file you have to update.
MDServer_PrologServers.conf	Contains the alias to the Sicstus Prolog servers. To update the number of Sicstus Prolog servers available to the MDS, this is the file you have to update. When updating that file, do not forget to update the management shell script `startDSicstus.sh` located in the `scripts` directory of the `appserver` module. You'll also have to update the same script located in the `prolog` directory of the `gui` module.
MDServerVersion.vm	This is a Velocity template document used by the servlet `MDServerVersion` from `appserver` package `model.com.server`.

Those files can be edited in the directory conf of the appserver module. For the modifications to take place you must shutdown then restart the Tomcat/MDS server as explained previously (see Section 3.2.2).

4.2. Sicstus Prolog server configuration

The configuration of the Sicstus Prolog servers are defined in two places.

The first one is a shell script, named startDSicstus.sh, that effectively starts the servers. That script can be located by looking at the target prolog in the Ant build file available for both appserver and gui modules. There you will find the exact location of the script that can be edited to configure the Prolog servers: location of the Sicstus Prolog program, number of servers to start (default is 2), host IP address (localhost by default) and ports (7600 and 7601).

The second file is MDServer_PrologServers.conf (presented in Section 4.1) located in the directory conf of the appserver module. If you modify the above mentioned startDSicstus.sh, you must report the modifications in the MDServer_PrologServers.conf file. Of course, if you modify MDServer_PrologServers.conf, do not forget to update startDSicstus.sh.