Multi-user Troubleshooting

10 min

Mysql connections and exceptions

A known "feature" of the MySQL connection pool manager and the JDBC driver means that MySQL times out connections that have been idle for a long period of time but the JDBC driver cannot easily re-establish these.

If you are seeing exceptions such as the following in the Protege server logs (/logs):

com.mysql.jdbc.CommunicationsException: Communications link failure

It is likely that the Protege server has just tried to use a JDBC database connection that MySQL has culled. There is no complete solution to this at the present time, and the workaround is to set the connection timeout on the MySQL database server very high, e.g. 5+ days and have the Protege server restarted weekly to ensure that the connections are regularly reset.

Out of Memory

It is important to consider the memory requirements on the Essential Architecture Manager server as the number of instances in the model increases, to avoid Java Out Of Memory Exceptions.

If the server is reporting out of memory exceptions (see the logs in the /logs directory) then the MAX_MEMORY parameter in the server startup file (run_protege_server.bat or run_protege_server.sh) must be increased. It's worth starting this around -Xmx200M but when a large number (>1000) of instances are in the model, you may need to raise this, e.g. to -Xmx500M or above.

Most performance problems are related directly to the amount of memory that is required by the server. As the repository grows (e.g. > 1000 instances), more memory is required by the server, in particular, if the Essential Viewer component running in Tomcat is co-located with the Essential Modeller running in the Protege Server.

Memory Requirements

As the repository grows in terms of the number of instances, in particular when you get beyond 1000-2000 instances, you should provide around 2GB of memory on the physical server platform on which you are running the Essential Architecture Manager server.

CPU Load

It is common for the Essential Viewer component – running in Tomcat – to be deployed alongside the Essential Modeller component – running in the Protege Server. Both require large amounts of memory, but the XSLT approach used by many of the analysis reports of Essential Viewer is also CPU intensive. If you are experiencing performance and response issues with the server, allocating an additional CPU (e.g. Dual CPU server) will enable the physical host server to manage the load of both of the Essential Architecture Manager server components.

Change History

Using the Collaborative Protege tab plugin is a good thing for team and multi-user repositories. A very detailed change log is kept in an OWL project that is associated with your active project – called the Annotations project. Currently (Protege 3.3.1), this is only stored using a file-based project – in 3 related files:

  • annotations_.pprj

  • annotations_.rdfs

  • annotations_.rdf

There is no option to have this content – especially the *.rdf and *rdfs files stored in a relational database (possibly available in Protege 3.4). Having this detailed change history stored in files means that these files (the *.rdf file in particular) get very large quite quickly. When it goes over 3.5MB it will start to affect the performance of the Protege server.


We have created a script to run in the Protege Script tab on the Annotations project file to perform housekeeping on this file as follows:

  • Stop the Protege server (to stop the active Essential repository) – See

  • Archive the current version of the project

  • Delete all instances in the project

  • Save the project

  • Re-start the Protege server

It turns out that the Protege team are on the same page with this and have announced an enhancement on the Changes tab as a menu option to clear the change history (with an option to archive it first). We are, therefore, in the absence of a database back-end for the Annotations project, comfortable that this is the best-practice way of managing the change history.


To use this script follow these simple steps

  • Stop the Protege server – See

  • Open the current annotations_.pprj file in Protege as a native file-based project (not via a server)

  • If it's not already there, add the Protege Script tab (Project->Configure and select Protege Script Tab), if it is, go to the script tab

  • Run this script (below) using the command


The latest version of the script is provided here.

# (c)2008 EAS ltd.

# 19.02.2008    JWC v1.0

# 18.04.2008    JWC Updated to remove more instances and to force an archive, 1st


# Archive and purge changes [annotations] projects


# Run this against the annotations_<myProject>.pprj

# 1. Stop the server

# 2. Open the annotations file in stand-alone mode (just open the local PPRJ file)

# 3. Go to the Script tab and run this script

# 4. Remember to save the Annotations project on completion of this script

import java

# Do the archive

from edu.stanford.smi.protege.util import ArchiveManager

anArchiveMgr = ArchiveManager.getArchiveManager()

anArchiveMgr.archive(kb.getProject(), "Housekeeping archive of current change history")

print "Archive completed successfully"

# Remove the changes, etc from the current history

# Remove timestamps

rmInsts = kb.getCls("Timestamp").getDirectInstances()

print "Removing ", rmInsts.size(), " Timestamp instances"

for delInst in rmInsts: delInst.delete()

# Remove the changes

rmChanges = kb.getCls("Change").getInstances()

print "Removing ", rmChanges.size(), " Change instances (including all subclasses)"

for delInst in rmChanges: delInst.delete()

# Remove Ontology Components

rmOntComps = kb.getCls("Ontology_Component").getInstances()

print "Removing ", rmOntComps.size(), " Ontology Component instances (including all subclasses)"

for delInst in rmOntComps: delInst.delete()

# Remove Annotations

rmAnnotations = kb.getCls("Annotation").getInstances()

print "Removing ", rmAnnotations.size(), " Annotation instances (including all subclasses)"

for delInst in rmAnnotations: delInst.delete()

print "Finished."

Updated 31 October 2023

Contact Us