Configuring Protege Install Folders (Non-NCI Users)

Overview

This page serves as an instructional guide as well as a brief history and and overview about Protege to all non-NCI users. Users are able to download a zipped copy of this public release Protege extenstion package, which contain the necessary installation folders. Within each folder, certain file(s) will need to be configured in order to properly run the application. Once configured in the user should be able to run Protege within their own server environment.

EVS Protege Extensions Introduction and History

Currently, version 1.3.0.188 is the third public release of the EVS Protege Extensions. There have been multiple revisions released, tested and used internally over the past year. The current version is considered stable and reliable and suitable for external release.

These extensions were created in response to a need for an open-source editing tool that could be customized to the needs of the EVS content editors. In addition, EVS wanted the ability to exchange and share editable content with external collaborators. The Protégé editing tool, developed by Stanford, was used as the basis and extended to meet these needs.

The extensions are built on the Protégé 3.4 Beta 508 codebase and utilize pellet 1.5. Some improvements to the Protégé software were required to meet the needs of EVS, but these have already been merged into the Protégé trunk. Both Protégé and Pellet are included within the download. The Explanation Server was developed in collaboration with Clark & Parsia LLC.

The Protégé and the extensions are built and expect to run on Java 1.5.

EVS Protege Extensions packages

As metioned above, the EVS Protégé Extensions are broken into three separate packages. The Explanation server provides
classification and explanation functionality. The Protégé server provides access to a central editing project for multiple users. The Protégé client is the end-user application for accessing the Protégé server and editing content.

Explanation Server

The Explanation Server is used to do classification of the ontology and provide explanations on demand to the Protégé Client GUI. It runs directly against the database, independently of the Protégé Server. The Protégé Server queries the Explanation Server for information when needed and controls requests for classification, so multiple clients cannot try and classify at the same time. The Explanation Server is designed to run in the bash shell on a Linux or Unix computer. Please ensure that the JRE is installed on the machine to run the explanation server.

Protege Server

The Protégé server provides multi-user access to a single ontology stored in a database. It coordinates and controls user activities and resource allocation. It stores a history of user actions for use in tracking changes and resolving conflicts. The server also provides a centralized means of enforcing business rules and configurations upon client applications. EVS has extended the Protégé server to allow tracking of workflow and assigning of editing tasks. The Protege server is
designed to run in the bash shell on a Linux or Unix computer. Please ensure that the JRE is installed on the machine to run the explanation server.

Protege Client

The Protégé client is a java-swing based GUI used for editing an ontology. EVS uses the client to connect to the Protégé server application, allowing multiple editors to share the same ontology. The Protégé client can also be used in standalone mode to edit a single ontology but some of the client-server specific extensions are then disabled. The client is used in standalone mode by managers to perform Prompt comparisons and terminology exports. The Protege client is designed to run in the bash shell on a Linux or Unix computer or on a Windows computer. The JRE has been set for the Protege client to run on a Windows machine, however, this JRE folder is not needed for the client residing on the server, the Linux server should have a JRE setup.

Installation instructions

The instructions below will allow the user to build an environment to match the one used by EVS. Some of
the configurations are optional and will be labeled as such. The zip package contains folders for the client,
Protege server and explanation server. All of these should be copied to the Linux/Unix machine where you will
be serving Protege. A copy of the client should also reside on a local Windows machine for use in accessing
the server data.

Metaproject

Any multi-user Protégé server-client configuration requires a metaproject. The server application references this metaproject to determine what ontologies to make available for editing and what users have rights to do various tasks. EVS has made available an example metaproject that includes all the privileges and groups required for the NCI edit tab. A base metaproject is located in the Protege.Server-1.3.0.188/examples/server folder.

Protégé Client Folder

Before the vocabulary can be accessed by the server it must be loaded into a project using the Protege Client
GUI. The OWL source is loaded first as a Protege file project and then converted to a database project.
Steps to load a new Protege project and convert in to a database project are below. The Protege application will create
the necessary tables in the database. You, or course, need to have a database ready and able to be written to
before you start the load.

These steps can be performed on a Windows machine but all the files generated or modified would then need to be copied
up to the Linux server. The directions below assume the user is running the client on the actual Linux server.

Files to configure in the Protege client folder:

run_protege.sh (Linux) / run_protege.bat (Windows)

JAVA_HOME = must be set to the proper path.
For the client folder residing on the Linux server, set MAX_MEMORY value to a suitable size (NCI Prod - 7GB, QA - 7GB, Dev 2.5GB).
For a copy of a client on your local machine, set the MAX_MEMORY to 700MB.
Ensure PERMGEN_MEMORY, an MAX_PERMGEN_MEMORY options are present and both set to 512M.

PromptNCIPlugins.properties

Examine the PromptNCIPlugins.properties file to verify correct database information. This is only necessary if Prompt is going to be used to export history records to the concept_history table:

nci.prompt.ipAddress=<hostname>:<port>
nci.prompt.dataBaseName=<db name>
nci.prompt.dbEVSHistoryTable=<tablename>
nci.prompt.userName=<username>
nci.prompt.password=<password>

Explanation Server Folder

The Explanation Server can connect with either the Protege database or to a raw OWL file. Files to configure:

start_explanation_server.sh

Allocate a decent max_heap_size. (default is set to 12gigs, however, less memory can be used for test machines (i.e. 8GB for QA)).
Enusre that the explanation server is pointing to the correct Protege.Server folder: (protege_install=/path/to/new/Protege server folder). This allows the Explanation server to use jars found in the Protege.Server folder.
Make sure the path to the java server is correct (replace <PATH TO JRE BIN> with the actual jre/bin/java.exe location.
The command to connect the explanation server to a database project: './start_explanation_server.sh --port <PORT> --protege-standalone /path/to/databaseProject.pprj'. The command to connect to a raw OWL file: *'./sh start_explanation_server.sh --urls file:///home/user/path/to/file.owl'*
The Explanation Server is ready when you see "Jena, Classification, and Extracting' as well as a final
'Server started, listening on port ....' message. The Explanation Server should be allowed to start completely before starting the Protege Server.

Protege Server Folder

run_rmiregistry.sh

JAVA_HOME must be set in the script.
The very last line has a port number that will need to match the Protege Server: $JAVA_PATH/rmiregistry <PORT> &

run_protege_server_nci.sh

JAVA_HOME must be set.
Set MAX_MEMORY to a suitable size to run adequately (i.e. NCI Production - 7.5 GB, QA - 7GB, Dev - 3GB).
Ensure MAX_PERMGEN_MEMORY, and PERMGEN_MEMORY options are included, both set at 512M.
Ensure RMI_REG_PORT number matches port number in 'run_rmiregistry.sh' script.
Set RMI_SERV_PORT to any desired open port.
HOSTNAME_PARAM=-Djava.rmi.server.hostname=<hostname> should be edited with the actual server hostname where the rmi registry server will be running. The "localhost" address will not work properly, it needs to be the actual server name.
Set METAPROJECT with the location of Metaproject file.
Ensure that the RMI_REG_PORT=-Dprotege.rmi.registry.port=<PORT> matches the RMI port number in the 'run_rmiregistry' script.

codegen.properties

The codegen.seed number should be set at a figure higher than the highest concept number in your vocabulary. The codegen prefix and codegen.suffix values are optional. The optional codegen delimeter will set the character to be inserted between prefix and code or code and suffix. Example: prefix=B, delimiter=-, suffix=cs, seed=100. The first code generated will be B-100-cs. A 'codegen.dat' file will then be generated within the Protege server folder and will be updated to "100" and will iterate the concept code number from that point.

PromptNCIPlugin.properties

Verify correct database information for saving to the evs_history table. This information should match the PromptNCIplugin info residing in the Protege client folder: