VSTO Replica Portal

Printer-friendly version

The purpose of this page is to assist in the installation, configuration, and administration of the VSTO Replica Portal at RPI.

Installing the VSTO Replica Portal

Prerequisite Software

  • J2SE 5.0
  • Tomcat 5.5
  • Pellet 1.4

Software Installed on escience.rpi.edu

Software Package Version Installed in Maintainer Dependencies
java JRE 1.6.0_10 /usr/jdk1.6.0_10/jre VCC
tomcat 6.x /opt/tomcat/apache-tomcat-6.0.18 TW
pellet 1.4 /opt/pellet/pellet-1.4 TW

The information on this chart comes from the escience.rpi.edu software stack page.

If any of this information needs to be updated, please be sure to update it in both locations.

Building a VSTO Replica Portal Deployment file

Developing against the VSTO Replica Portal Framework

Loading the ontology into Protege

This requires the use of at least Protege 3.2, preferably Protege 3.4. Using Protege 4.x will work for reading the ontology, but not making modifications as the VSTO code base can not read .owl files generated from Protege 4.x.

  1. Start Protege 3.4
  2. You will get a Welcome dialog for Protege. Click on 'New Project' button.
  3. In the new dialog box check the box to 'Create from Existing Source', select 'OWL/RDF Files' and click 'Next'
  4. Enter the URI for the ontology, which is http://escience.rpi.edu/ontology/vsto/2/0/vsto_all.owl and click 'Next'
  5. Select 'OWL Full' and click 'Next'
  6. Select 'Logic View' and click 'Finish'

The ontology will now load in Protege. If you are only wanting to read the ontologies then this is all that you have to do. In order to edit the ontologies you have to download them to a local folder. If you want to edit, then continue here with these instructions. If you just want to look at the ontology, then skip down to the 'Save the Protege project' item below.

  1. On the left you will see the list of ontologies. The vsto_all.owl files imports the owl files for vsto, cedar, csac, and mlso. Under the Ontologies frame on the left, expand the ontologies for cedar, mlso, and csac and you will see the vsto ontology file.
  2. Select the vsto_all.owl file and click the 'Download ontologies to folder' button directly above the list of ontologies. It looks like a floppy disk.
    1. Select the directory where you want to save the vsto_all.owl file. Then click 'Download' button.
    2. It will say that it has downloaded the ontology to the directory. Click 'OK'
    3. When it asks if you want to add a project repository to redirect imports, click 'Yes'
    4. You will get a dialog that says that you should reload your project for the imports redirection to take effect. Click 'OK'. But don't do it just yet. We need to download the other .owl files.
  3. Click on the next .owl file, which should be the cedar.owl ontology' in the Ontologies list and click the 'Download' button again. Do the same thing that you did above to download the vsto_all owl file
  4. Click on the vsto.owl file under cedar.owl and download it
  5. Click on the csac.owl file and download it
  6. Click on the mlso.owl file and download it.
  7. Save the Protege project to the same place where you wrote the owl files. name the project the same as the main ontology file, which is vsto_all. The owl file should be vsto_all.owl. Click 'OK'
  8. Restart Protege by exiting out and restarting, selecting the protege project that you just saved and click 'Open Recent' in the Welcome dialog.

Installing a Development Portal in Eclipse

Install Prerequisite Software

Before installing and configuring Eclipse, you should check that all prerequisites are installed and working.

  • J2SE 5.0 Development Kit (JDK)
    • The VSTO Portal and PortalBase framework are built on J2SE 5.0.
    • Java SE 6 is intended to be fully backwards compatible with J2SE 5.0, so the VSTO Portal should successfully build and run using Java 6.
    • If you do not have a JDK of J2SE 5.0 or Java 6.0 installed, you can download one from here
  • Apache Tomcat 5.5, 6.0, or both
    • The VSTO Portal and PortalBase framework were built to run on Tomcat 5.5, but has been successfully tested on Tomcat 6.0.
    • If you do not have Tomcat installed, you can get it here
    • You can install both versions 5.5 and 6.0 on the same machine, this is advisable for a development environment.
  • Pellet 1.4 or 1.5
    • Pellet can be downloaded from here
    • Pellet 2.0+ has not been tested with the VSTO portal, and is assumed to be incompatible.
  • MySQL 5.1
    • MySQL can be downloaded from here - get the Community Edition
    • Create a database called metrics
    • Create the user metricsUser with password metricsPswd from host localhost that can insert and select to the database metrics
    • In the database metrics use this Session_table.sql.gz file to import the session_table

Install Eclipse and Required plug-ins

  • Download and install the latest JEE version of Eclipse for your specific OS.
    • You can also install the standard Eclipse release and install the Web Tools Platform core plug-ins
  • Install the following Eclipse plug-ins/extensions
    • Subversion integration with Eclipse
      • There are two well-supported projects that provide Subversion integration with Eclipse; Subversive and Subclipse
    • Spring Eclipse plug-in
      • Spring is a very popular Java application framework that provides an alternative to the EJB model as well data access, transaction management, MVC, and remote access frameworks.
      • Instructions for installing Spring integration with Eclipse can be found here
    • PMD Eclipse plug-in
      • PMD is a static-code analysis tool for Java. It scans Java source code for possible bugs, dead code, suboptimal code, overcomplicated expressions, and duplicate code.
      • Instructions for installing PMD integration with Eclipse can be found here

Configure Eclipse

  • Disable JSP Validation
    • Window->Preferences->Validation->?Suspend all Validators
  • Define Java 1.5 environment in Eclipse
    • Window->Preferences->Java->Installed JREs
    • If you are using J2SE 5.0, check that JVM 1.5 is set to default
    • If you are using JE 6.0, check that JVM 1.6 is set to default
  • Define Tomcat runtime environment(s)
    • Window->Preferences->Server->Runtime Environments
    • If Tomcat 5.5 is defined and selected, deselect it
    • Add a server for every Apache Tomcat instance you wish to develop against
      • When creating the server definition, ensure that the tomcat installation directory you choose is of the same version as the server type chosen
  • Configure Ant to allow for Tomcat deployment
    • If you are using Maven instead of Ant to build the portal, ignore this step
    • Window->Preferences->Ant->Runtime->Global Entries->Add External Jar
    • Select catalina-ant.jar from your default Tomcat install
      • For Tomcat 5.5, the jar can be found at {TOMCAT_INSTALL}/server/lib
      • For Tomcat 6.0, the jar can be found at {TOMCAT_INSTALL}/lib
  • Configure Ant to find javac
    • If you are using Maven or a non-Windows development system, ignore this step
    • Window->Preferences->Ant->Runtime->Global Entries->Add External Jar
    • Select tools.jar from {JDK_INSTALL}/lib directory

Checkout VSTO code base from RPI Subversion

  • Configure Subversion Integration
    • Preferences->Team->SVN
    • Check the install directions for your chosen Subversion integration for detailed configuration help
  • Checkout the VSTO and PortalBase projects
    • Open the SVN Repository Exploring Perspective
    • Left-click in the Repository Explorer->New->Repository Location
      • Repository URL = "https://scm.escience.rpi.edu/svn/private/VSTOPortal"
    • Browse to the appropriate VSTO and PortalBase branch or trunk, left-click->Checkout

Configure VSTO Project

  • Define Apache Tomcat Server(s)
    • From the Server Pane in the JavaEE Perspective
    • Right-click->New->Server
    • Select Server Runtime (Apache Tomcat 5.5 or 6.0)
    • Select Next, add the VSTO project to the server's configured project list
  • Configure Tomcat Server(s) VM arguments on 'start'
    • For all Tomcat servers defined
      • Double-click on the server in the Server Pane
      • Click the 'Open Launch Configuration' link from the server configuration overview page
      • Add -Dowl_uri="http://escience.rpi.edu/ontology/vsto/2/0/" to the VM Arguments textbox under the Arguments tab
  • Set VSTO Project Targeted Runtimes
    • Right-click on the VSTO project in the Java EE Project Explorer
    • Properties->Targeted Runtimes
    • Check any Tomcat Servers you have defined
    • If a server is selected that you did not define, deselect it.
  • Configure SSL Keystore for the Server
    • Expand 'Servers' on the left and expand the tomcat associated with this Project
    • Edit the server.xml file
    • Uncomment the section SSL HTTP/1.1 Connector and modify as necessary. We did not have to make any modifications for ours.
    • You will also need to generate a key to use. Run the following from the command line
      • Windows: %JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA
      • Unix: $JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA
        • If keytool asks you to create a keystore pasword, the default password that will work with no extra configuration is 'changeit'. If you choose a different password you will have to configure the HTTPS connector (server.xml) or the JVM (via VM arguments) to use your password. The keystore password and password for the tomcat certificate must match.
      • keytool creates a .keystore file in the users home directory.
      • You will need to restart Eclipse for it to find the .keystore file
  • Answers to the questions asked
    • What is your first and last name?

  [Unknown]:  escience.rpi.edu

    • What is the name of your organizational unit?

  [Unknown]:  Tetherless World Constellation

    • What is the name of your organization?

  [Unknown]:  Rensselaer Polytechnic Institute

    • What is the name of your City or Locality?

  [Unknown]:  Troy

    • What is the name of your State or Province?

  [Unknown]:  NY

    • What is the two-letter country code for this unit?

  [Unknown]:  US

    • Is CN=escience.rpi.edu, OU=Tetherless World Constellation, O=Rensselaer Polytechnic Institute, L=Troy, ST=NY, C=US correct?

  [no]:  yes

  • Configure SSL jssecacert for Java
    • In order to contact https on cedarweb for authenticating logins you need to create a jssecacert file. Here is what you need to do:
      • Go to http://blogs.sun.com/andreas/entry/no_more_unable_to_find. You can get the .java file for InstallCert here by clicking on attached program.
      • Compile this file with javac
      • Run the file using the domain of the secure site you are wanting to contact. In our case, do the following:

 java InstallCert cedarweb.hao.ucar.edu

      • You should be shown a list of certificates to accept. For each one list, run InstallCert and accept each one in turn (1 then 2 then 3, or however many there are)
      • In your local directory will be created a jssecacerts file. Copy this file to $JAVA_HOME/lib/security or $JAVA_HOME/jre/lib/security if you have a jre directory.

    

  • Edit build.xml
    • Note, this is not required if you are using Maven
    • If the property 'portalbase' does not exist, add it with the following syntax
    • If the property does exist, edit it so that the value of the location attribute correctly points to the desired PortalBase project from your VSTO project.

  • Configure Eclipse to run with Extended Memory
    • Add '-Xmx512m' to your Eclipse configuration file at {ECLIPSE_INSTALL}/configuration/config.ini
  • Set VSTO to Build Automatically
    • Check that Project->Build Automatically is ON
  • Configure VSTO to use servlet-api.jar library from PortalBase'
    • Right-click on the VSTO Project->Build Path->Configure Build Path...
    • In the Libraries tab, select 'Add Jars...', and select servlet-api.jar from PortalBase/buildlibs

Run the VSTO Portal from Eclipse

  • Start the Pellet server
    • Check that the script pellet-dig.sh in your pellet install directory is executable, if not make it so
    • Call the script pellet-dig.sh from the pellet install directory to run the pellet server (default port 8081)
    • Alternatively
      • Add {PELLET_INSTALL}/lib/pellet.jar to your $CLASSPATH
      • Add {PELLET_INSTALL} to your $PATH
      • Edit pellet-dig.sh, remove '-cp lib/pellet.jar' from the java call
      • Now you should be able to start the Pellet server from any location
  • Launch VSTO from Eclipse
    • Right click on VSTO Project->Run As->Run on Server
    • Select the appropriate Server
    • Check that the VSTO project is in the configured projects list
    • Click Finish

Deploying VSTO under tomcat

Metrics

 describe session_table;
 +--------------------+--------------+------+-----+---------------------+----------------+
 | Field              | Type         | Null | Key | Default             | Extra          |
 +--------------------+--------------+------+-----+---------------------+----------------+
 | id                 | int(11)      |      | PRI | NULL                | auto_increment |
 | session_identifier | varchar(128) |      |     |                     |                |
 | portal_url         | varchar(128) |      | MUL |                     |                |
 | username           | varchar(64)  |      |     |                     |                |
 | time               | datetime     |      |     | 0000-00-00 00:00:00 |                |
 | remote_address     | text         | YES  |     | NULL                |                |
 | user_agent         | text         | YES  | MUL | NULL                |                |
 +--------------------+--------------+------+-----+---------------------+----------------+

 -- MySQL dump 9.07
 --
 -- Host: localhost    Database: metrics
 ---------------------------------------------------------
 -- Server version       4.0.9-gamma-max-log
 
 --
 -- Table structure for table 'session_table'
 --
 
 CREATE TABLE session_table (
   id int(11) NOT NULL auto_increment,
   session_identifier varchar(128) NOT NULL default '',
   portal_url varchar(128) NOT NULL default '',
   username varchar(64) NOT NULL default '',
   time datetime NOT NULL default '0000-00-00 00:00:00',
   remote_address text,
   user_agent text,
   PRIMARY KEY  (id),
   KEY portal_url_index (portal_url),
   KEY newindex (user_agent(1))
 ) TYPE=MyISAM;
 

Metrics is recorded in the SessionMetrics class under PortalBase ncar.scd.metrics. There is also a metrics.properties file in the same place. We can create this on the local machine and change this file to reflect the connection information. Unfortunately this file is part of the .jar file for VSTO project so we would have to rebuild for the machine we are running on. This needs to change, having the file located someplace else and read in as a configuration file.

Troubleshooting

Problem: Out of memory when building the VSTO war file from the command line.


ant war
    [...]
        [javac] The system is out of resources.
        [javac] Consult the following stack trace for details.
        [javac] java.lang.OutOfMemoryError: Java heap space
        [javac]     at com.sun.tools.javac.code.Scope$ImportScope.makeEntry(Scope.java:324)
    [...]
    BUILD FAILED
    /Users/josh/projects/school/vsto/VSTO/build.xml:86: Compile failed; see the compiler error output for details.

Solution: Add -Xmx512m to the $ANT_OPTS environment variable

Problem: MalformedURLException starting VSTO service


    java.net.MalformedURLException: no protocol: nullvsto_all.owl
        at java.net.URL.(URL.java:567)
        at java.net.URL.(URL.java:464)
        at java.net.URL.(URL.java:413)
        at edu.stanford.smi.protegex.owl.jena.parser.ProtegeOWLParser.run(ProtegeOWLParser.java:136)
        at edu.stanford.smi.protegex.owl.jena.JenaOWLModel.load(JenaOWLModel.java:230)
        at edu.stanford.smi.protegex.owl.ProtegeOWL.createJenaOWLModelFromURI(ProtegeOWL.java:62)
        at ncar.vsto.VSTOservice.init(Unknown Source)
        [...]

See: ./JavaSource/ncar/vsto/Constants.java

Solution:

1) Add -Dowl_uri=http://escience.rpi.edu/ontology/vsto/2/0/ to $CATALINA_OPTS environment variable

or

2) Add -Dowl_uri=http://escience.rpi.edu/ontology/vsto/2/0/ to catalina.sh

note, the value set in catalina.sh takes precedence over the CATALINA_OPTS environment variable

Problem: Reasoner not found during VSTO service start


    java.lang.Exception: Required Reasoner Engine is not available
        at ncar.vsto.VSTOservice.init(Unknown Source)
        [...]

Solution: Start the Pellet service

Problem: MySQL connection refused when starting VSTO service


SEVERE: Servlet.service() for servlet jsp threw exception
com.mysql.jdbc.CommunicationsException: Communications link failure due to underlying exception:

    • BEGIN NESTED EXCEPTION **

java.net.ConnectException
MESSAGE: Connection refused
...

Solution: The VSTO service is probably configured to use a metrics database and cannot successfully connect to it, presumably because you do not have one setup.

To remove metrics functionality, comment out the Metrics Filter and Filter Mapping defined in VSTO/WebContent/WEB-INF/web.xml

OR

Create the metrics database, using mysql using the instructions above.

Problem: Failed to convert property value of type LinkedMap to HashedMap

Solution: Apparently, either when building in eclipse or using ant, multiple jar files can be added to the lib directory for some of the commons jars. Perhaps it is adding the latest version of the jar file to the lib directory so that the latest is used. This creates a problem if the VSTO code is out of date with the latest jar file. In this particular cases, there were additional commons-collections.jar file in webapps/vstoapp/WEB-INF/lib. Remove all versions except commons-collections.jar, and restart tomcat.

Problem: When running vstoapp in tomcat (or eclipse) you get the error:


ERROR-Context initialization failed
org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'useCase1aController' defined in ServletContext resource
[/WEB-INF/vstoapp-service.xml]: Can't resolve reference to bean 'useCase1Data' while setting property 'applicationData'; nested exception
is org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'useCase1Data' defined in ServletContext resource
[/WEB-INF/vstoapp-service.xml]: Initialization of bean failed; nested exception is java.lang.IllegalArgumentException: null slot

Solution: This problem is encountered when the uri specified by -Dowl_uri does not match the URI in the generated java code. When the java code is generated, it hard-codes the URI in some of the classes generated. If the -Dowl_uri does not match these hard-coded strings, you will get this message.

The solution is to either correct the -Dowl_uri (configuration settings for the server in eclipse, or the CATALINA_OPTS in your environment) or to re-generate the java classes with the correct URI.

Problem: Doesn't seem to be finding the java source in VSTO project to build

Solution: Your build path might be pointing to the wrong java source directory. The first pass at the VSTO project had the source under JavaSource. This was moved to be more consistent with PortalBase and to be usable under Maven. If you have this problem, first check the build path to see if it says JavaSource. If it does, then change it.

  1. Right click on VSTO project and select 'Configure Build Path'
  2. Select the "Source" tab
  3. If the src folder is JavaSource then you need to change it. If it isn't JavaSource, it might still be wrong
  4. Click "Add Folder"
  5. select src/main/java
  6. then select JavaSource and remove it

Problem: Receive a java exception about "Initialization of bean failed: ...: URI is not absolute

 ERROR-Context initialization failed
 org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'vstoService'
 defined in ServletContext resource [/WEB-INF/vstoapp-service.xml]:  Initialization of bean failed; nested
 exception is java.lang.IllegalArgumentException: URI is not absolute
 java.lang.IllegalArgumentException: URI is not absolute

Solution: More than likely you are on a Mac, but could be any system. This usually means that the -Dowl_uri option added to CATALINA_OPTS is not being passed to tomcat properly. Adding this to catalina.sh in the bin directory appears to resolve the issue. So after all the comments add:

 CATALINA_OPTS="-Xmx512m -Dowl_uri=http://escience.rpi.edu/ontology/vsto/2/0/"

The first option is to bump up the heap space, the second option is passed to tomcat correctly.