Protege Client Server Tutorial Setup

Protege Server Setup

This page describes the setup of the Protege server including: starting, testing, shutting down and troubleshooting the server. This page is part of the Protege client-server tutorial.

Starting the Server

There are two ways of starting the Protege server: one using the run server scripts available in the Protege installation directory - the easier and recommended way, and one using two steps by typing commands in a console - that is the more advanced way.

Please start by trying out the first solution (the recommended one), and only if that fails, try the second one.

Note. There is a known Java bug in Java 1.6.0_29 and Java 1.7 that affects the starting of the Protege server. If you use this version, please read this information first.

Starting the Protege server using the run_protege_server script (Recommended)

Try this method first.

In the Protege installation directory there is a script called run_protege_server.bat on Windows and run_protege_server.sh on Linux and MacOS. This script will start a background process called "rmiregistry", which is part of the standard Java Runtime Environment. The script will then start the Protege server by invoking a Java program (if you want to see the details about the command, look in the advanced method for starting the server).

If you have installed Protege with a Java VM included, then all you have to do to start the server, is to start a console window (on Windows, Start menu -> Run -> cmd), and run the run_protege_server script.

Note If you don't know whether you have installed Protege with a Java VM included or not, then look into the Protege installation folder. If you see a jre subfolder, then you have installed Protege with a Java VM included. If you do not see the jre folder, then you have not installed Protege with a Java VM included.

If you have Protege installed with an included Java VM, then you're done with this step. You only need run in a console the run_protege_server script.

If you have not installed Protege with an included Java VM, then you need to adjust the path to the Java VM in the run_protege_server script. To do that, you need to edit the run_protege_script in a text editor.

Windows

In run_protege_server.bat, edit the line:

set JDKBIN=jre\bin

to match your path to the JRE bin folder. For example, a common place would be in the Program files folder. If you don't know whether you have Java installed, or where, ask your system administrator. Or, even easier, just download the Protege installer with a Java VM included, and you don't have to go through this configuration. A typical example of where Java is installed on Windows is this:

set JDKBIN="C:\Program Files\Java\jre1.5.0_08\bin"

You should also check the path for the CODEBASE_URL and adjust it to match the installation of Protege on your computer. Please note that this argument is in URL format, and uses forward slashes. All space characters should be replaced with %%20. Please edit the line below to match the path to the protege.jar from your Protege installation:

set CODEBASE_URL=file:/c:/program%%20files/protege_3.4.7/protege.jar

Linux and MacOS

The run_protege_server.sh script uses the JAVA_HOME environment variable to figure out where to find Java. If JAVA_HOME in your setup already points to the Java VM installation directory, then you don't need to do anything. If it doesn't, then please edit the run_protege_server.sh in a text editor, and add at the beginning of the file (e.g. after the commented line containing "Where is Java?") a line setting the JAVA_HOME to the path to Java on your system. An example from a Ubuntu installation is:

JAVA_HOME=/usr/lib/jvm/java-1.5.0-sun-1.5.0.16/bin

OK, so now you are ready to launch the Protege server. In a console, change the directory to the Protege installation directory, and type run_protege_server.bat on Windows, and run_protege_server.sh on Linux and MacOS. You should see something like this:

Congratulations! You have started the server. If you have trouble starting the server, please see the troubleshooting section from below. The next steps are to configure on the server the projects (see below the configuration section). If you are running the server behind a firewall, there are some additional configuration that you must do to ensure that the clients can connect to the server even behind the firewall (See Firewall section from below).

Starting the Protege server in two steps using console commands (Advanced)

Try this method only if the recommended way of starting the server has failed. See above. Skip this section if you have already succeeded in starting the server

There are two processes that need to be started. In the root directory of your Protege installation, we have provided both an example Windows batch file ("run_protege_server.bat"), and an example Unix shell script ("run_protege_server.sh") to launch these processes. It is important to be aware of what the batch files are doing, so we suggest starting the processes manually at least once.

The first process to kick off is a background process called "rmiregistry", which is part of the standard Java Runtime Environment. If you downloaded the version of Protege that includes a Java Virtual Machine, you will find the rmiregistry executable in your jre/bin directory. If you installed Protege without a VM, you will need to locate and run the rmiregistry executable from the directory where you installed your VM (no parameters are necessary).

To follow are the steps for running the rmiregistry executable:

• Launch a console window.
• Change the working directory to the Protege installation directory.
• If you are using Windows, type "start /min jre\bin\rmiregistry".
• If you are using Unix, type "jre/bin/rmiregistry &".

Note: If you installed Protege without a VM and your Java installation is located in a path with spaces (such as "C:\Program Files\Java\jre1.5.0_08\bin\rmiregistry.exe") the start command for the RMI Registry in the "run_protege_server.bat" will fail. To fix this, change the command to:

start "rmiregistry" /min "C:\Program Files\Java\jre1.5.0_08\bin\rmiregistry.exe"

The rmiregistry process will either start with no messages, or will crash saying that the port is already in use. The latter result probably means that you are already running rmiregistry. Either of these results is fine. You only need one version of rmiregistry running on your machine since all applications can use it.

The second process to kick off is the Protege server process, using the following command (please note that this is a single command):

Windows:

jre\bin\java -Xmx200M -cp protege.jar;looks-2.1.3.jar;unicode_panel.jar -Djava.rmi.server.codebase=file:/c:/program%20files/protege_3.3.1/protege.jar edu.stanford.smi.protege.server.Server examples\server\metaproject.pprj

Unix:

jre/bin/java -Xmx200M -cp protege.jar:looks-2.1.3.jar:unicode_panel.jar -Djava.rmi.server.codebase=file:/home/rwf/protege_3.1/protege.jar edu.stanford.smi.protege.server.Server examples/server/metaproject.pprj

The meaning of the parameters will be explained in the Configuring the Server section. The intent of this section is simply to get you going as quickly as possible. The set of parameters listed above assumes that you have installed Protege in the default location with the default directory name. On Unix, you will have to change the path of the codebase parameter to point to the proper location of the Protege JAR file (note that this path must be "absolute" from the root - no shortcuts!).

The Protege server should start up with the normal console window output (the build number, the version of the JVM used, a list of installed plug-ins, etc.). In addition, you should see the following output:

Available Projects:
	Newspaper
	Wines
Protege server ready to accept connections...

To follow is a screenshot of what this looks like on a Windows machine:

Congratulations! You now have the server running.

Please note the following:

• On Unix, the metaproject unfortunately refers to other Protege projects using relative paths containing Windows "\" characters rather than Unix "/" characters. Please edit the metaproject (with Protege) to correct these characters before starting the server, otherwise it will complain about projects that can't be found.

• If you start the server twice there are no error messages. The second instance takes over accepting new client connections, while the first continues working with existing client connections, if any.

Troubleshooting Protege server starting problems

1. "The system can not find the path specified" - If you have messages saying that the system cannot find the path specified, or other similar messages, it means that the Java VM was not found on the path as specified in the run_protege_server script, or as you have specified in the command in the console (depending on what method you used to start the Protege server). If you have installed Protege with an included Java VM (the easiest way), then you should not get this message. If you have not installed Protege with an included Java VM, then check in run_protege_server.bat or .sh that you have specified the right path to the local Java installation. See the recommended way for starting the Protege server for examples.

2. Port already in use When starting the run_protege_server script, or the rmiregistry (for the advance method), you may get a message in the console or in a dialog saying that the port is already in use. It will look something like:

java.rmi.server.ExportException: Port already in use: 1099; nested exception is:
 java.net.BindException: Address already in use

This means that the rmiregistry is already running on the port (default 1099) and it has not been started again. This is usually fine, and you can ignore this exception. This exception comes usually up if you have already run a Protege server and you have killed it, e.g. Ctrl+C in the console. What you can do (optional), is to kill the existing rmiregistry process. In Windows, you can do this in the Task Manager - end all rmiregistry tasks. In Linux, MacOS - you type in a console the command pkill rmiregistry

Which type of back-end to use (database vs. file-based) in client-server mode

Warning: We recommend the use of database projects if you run Protege in client-server mode. If you store your project in a Protege database, any changes made by Protege clients are immediately committed. However, if for some reason you want to use a file-based project (like those in the example above), you need to tell the server to periodically save the project to disk. If you don't specify a save interval, any changes you make will be lost if the server crashes.

To follow are some instructions for specifying a save interval for file-based projects:

1) If you use the run_protege_server script to start your server, you can uncomment the line in the script that contains the option for project autosave. Some OS specific comments are provided directly below.

Windows

You don't need to do anything, because autosave is enabled by default using a 2 minute time interval:

set SAVE_INTERVAL=-saveIntervalSec=120

If you don't want this option, you can comment it out by typing rem in front of this line.

Linux

Remove the comment symbol # from the line:

SAVE_INTERVAL=-saveIntervalSec=120

2) If you start your server using the "advanced" method described earlier in this setup guide, you need to add an extra argument to the server's start command:

...server.Server -saveIntervalSec=N ...

... where N is the number of seconds between saves. A reasonable number for N is perhaps 120 (every two minutes). If your project is large you may want to choose a larger number since the system will be unavailable while the save is taking place. Note that saves are only performed when a project changes.

Testing: Connect a Client to the Server

On the same machine, start Protege by double-clicking on the executable. From the "Welcome to Protege" dialog, click the "Open Existing Project..." button, which brings up the "Open Project" dialog. If you have configured Protege not to show the welcome dialog, you can bring up the Open Project dialog by choosing the File | Open Project... menu item. In the Open Project dialog, click on the Server button in the lower-left corner. To follow is a screenshot of the dialog after clicking on the Server button:

Leave the default information in the dialog (User Name = "Guest", etc.) and press OK. You will then see the "Select Project" dialog, which shows you the available projects (Newspaper and Wines) to choose from:

Select the "Newspaper" example and press OK.

In a moment the Newspaper project will load and be available in the client. Changes that you make in the client are actually being propagated to the server (although this is difficult to see with just one client running!).

Connect a Second Client to the Server

You can run a second client either on the same machine or on a different machine. If you choose to connect from the same machine, just follow the instructions given above. If you choose to connect from a different machine, you need to enter the DNS name for the server machine in the Project | Open Project dialog in the "Host Machine Name" text box (in place of the default value of "localhost"). The DNS name will be something like "yourservermachine.yourdomain.com".

Note that you must use the TCP/IP name (DNS name) for the machine and not the "Windows Networking" name for the machine, even if both of your client and server machines are running Windows. If you don't know your server machine's DNS name you may need to get someone at your site to help you figure it out. If your server machine does not have a DNS name then you cannot connect to it from another machine using Protege.

When you make changes in either of the clients, the changes will immediately be reflected in the other. Try it!

Shutting down the Protege server

Shutting down the server using the Server Admin user interface

You may shut down the server in a very easy way using the Server Admin user interface. In the login panel, select the "Administer server" check box and click on OK. In the Server Admin Tab, go to the "Server Control" tab, and click on the button Shut down the Protege server". You need the appropriate permissions to shut down the server.

A detailed guide with screenshots is available on the Server Admin wiki page.

Shutting down the server using commands in the console

Another clean way of shutting down the server is to run the shutdown_protege_server script from the Protege installation directory.

If you had to configure the Java VM path when starting the Protege server, then you will probably need to do the same in the shutdown_protege_server.bat or .sh file. If you have installed Protege with Java VM included, then you don't need to do anything.

After making sure that the Java VM path is correct in shutdown_protege_server script, you should open a console, change to the Protege installation directory, and type:

shutdown_protege_server.bat

(In Linux, MacOS - shutdown_protege_server.sh)

If you have started Protege server on a different port (because of a firewall), then instead of the command from above, you need to run:

shutdown_protege_server.bat localhost:5200

Replace the "5200" with the port number on which you are running the rmiregistry and the Protege server.

Note: There is an "unclean" way of shutting down the server: You may type "Ctrl+C" in the console window where you run the server. If you use this method, and have ontologies that are stored in file mode rather than database mode, then you will loose all the changes made to the ontology from the last save until the kill operation.

Note: All Protege clients should be closed before you shut down the server. If a client is running and the server is shutdown, then the clients will start throwing exceptions that it cannot find the server.

Read more about the Protege multi-user support in the Protege client-server tutorial.