Purpose

The purpose of this guide is to help get users up and running with a demonstration version of the Academic History Web Service as quickly as possible. After deployment and demonstration, more advanced deployment decisions may be required. For more detailed background on what the Academic History Web Service is, how it works, and why it is useful, see the Academic History Web Service Deployment Guide. For more advanced configuration of the service see the Configuration Guide. To develop custom authenticators and providers for the service, see the Developer's Guide.

Pre-requisites

The only significant pre-requisite is to install a version of the Sun Java Development Kit (JDK) version 6. This service will also work with Java 5, but for the sake of keeping instructions simple and staying current, please use Java 6 if possible. If you have not yet downloaded and installed Java 6, you can get it from http://java.sun.com. Please note that you need the Java Development Kit (JDK) and not just the Java Runtime Environment (JRE). The JDK includes the JRE, so just get the JDK.

Step 1: Download the Academic History Web Service Example Package

Download the current, stable package (package 13) from https://package.openeai.org/package/work/openeai-academichistory-tomcat-1.0/archive/openeai-academichistory-tomcat-1.0.package-13.zip

Step 2: Uncompress the archive to your desired location on the target system

On Windows, use your preferred utility to unzip the contents of the archive to the file system. For example, if you use WinZip, you could place the file in the c:\ directory and right click on the archive and select WinZip->Extract to here". This would uncompress the contents to c:\openeai-academichistory-tomcat-1.0

On Linux or similar UNIX like operating systems, use your preferred utility to unzip the contents of the archive to the file system. For example, if you have the unzip command, you might place the file into the target directory and run "unzip -qq openeai-academichistory-tomcat-1.0.zip" which would uncompress the archive in the current directory, creating a new directory called openeai-academichistory-tomcat-1.0 containing the contents of the archive.

It should not be necessary to uncompress the archive to any specific location or use any specific unzip utility. The above are simply specific examples for illustration.

Step 3: Set environment variables

On Windows, go to "System->Advanced->Environment Variables" and set two system variables. The first is JAVA_HOME, which should point to the home directory of your Java 6 Java Development Kit (JDK), for example "C:\progra~1\Java\jdk1.6.0_13". Note that this value may be different for you depending on precisely which verison of Java 6 you have deployed. If you have not yet downloaded and installed Java 6, you can get it from http://java.sun.com. Note that "progra~1" is the short name for the "Program Files" folder. It is recommended that you use this short name to ensure compatability with command-line scripts included in the package. The second environment variable is AHWS_HOME which should be set to the value of the directory into which you uncompressed the distribution archive, for example "c:\openeai-academichistory-tomcat-1.0".

On Linux or UNIX, set these environment variables by adding lines to the .profile or .bash_profile of the user who will run these examples or write a script to setup the environment with these variables. For example, if your user is using the bash shell you might at these lines to the user's .bash_profile:

JAVA_HOME=/usr/java/jdk1.6.0_13
AHWS_HOME=/opt/ahws/openeai-academichistory-tomcat-1.0
export JAVA_HOME AHWS_HOME

Step 4: Create a self-signed certificate and register it in appropriate certificate stores

The Apache Tomcat application server included in the package comes preconfigured with both HTTP and HTTPS connectors. In order to start the application server and use the HTTPS prototol you must create a certificate, keystore, and cacert to use. On Windows execute from AHWS_HOME:

cd "%AHWS_HOME%"
%JAVA_HOME%\bin\keytool -keystore .keystore -genkey -alias localhost -keyalg RSA

And answer the questions to create a certificate. IMPORTANT NOTE: When prompted to enter the first and last name during certificate generation, enter "localhost" as the value. Then execute the following commands to export the certificate and import it into a cacerts file:

%JAVA_HOME%\bin\keytool -export -keystore .keystore -alias localhost -file localhost.pem
%JAVA_HOME%\bin\keytool -import -keystore cacerts -file localhost.pem

When asked, "Trust this certificate?" enter "yes".

Finally, this certificate must be present in the cacerts file of your Java runtime for the Academic History Web Service client to function properly. You may either copy the cacerts file to %JAVA_HOME%\jre\lib\security or you may import the cert into an existing cacerts file there if you already have certificates in that certificate store. For example, to copy the file run:

copy "%AHWS_HOME%\cacerts" %JAVA_HOME%\jre\lib\security

Or to import the certificate into this other certificate store file, enter:

%JAVA_HOME%\bin\keytool -import -keystore %JAVA_HOME%\jre\lib\security\cacerts -file localhost.pem

On Linux or UNIX run the following:

cd $AHWS_HOME
$JAVA_HOME/bin/keytool -keystore .keystore -genkey -alias localhost -keyalg RSA

And answer the questions to create a certificate. IMPORTANT NOTE: When prompted to enter the first and last name during certificate generation, enter "localhost" as the value. Then execute the following commands to export the certificate and import it into a cacerts file:

$JAVA_HOME/bin/keytool -exportcert -keystore .keystore -alias localhost -file localhost.pem
$JAVA_HOME/bin/keytool -import -keystore cacerts -file localhost.pem

When asked, "Trust this certificate?" enter "yes".

Finally, this certificate must be present in the cacerts file of your Java runtime for the Academic History Web Service client to function properly. You may either copy the cacerts file to $JAVA_HOME/jre/lib/security or you may import the cert into an existing cacerts file there if you already have certificates in that certificate store.

For example, to copy the file run the following as a user with write permissions to the $JAVA_HOME/jre/lib/security:

cp $AHWS_HOME/cacerts $JAVA_HOME/jre/lib/security

Or to import the certificate into this other certificate store file, enter as a user with write permission to this cacerts file:

$JAVA_HOME/bin/keytool -import -keystore $JAVA_HOME/jre/lib/security/cacerts -file localhost.pem

Step 5: Copy jndi.properties to the Java runtime library directory

The jndi.properties file contains some Java Naming and Directory Interface (JNDI) administered objects required by the service. Copy the file in the AHWS_HOME directory called jndi.properties to the JAVA_HOME/jre/lib directory. On Windows execute:

copy "%AHWS_HOME%\jndi.properties" %JAVA_HOME%\jre\lib

Or copy and paste accordingly using Windows file explorer. On Linux or UNIX run the following:

cp $AHWS_HOME/jndi.properties $JAVA_HOME/jre/lib

Step 6: Start Tomcat

From the AHWS_HOME directory execute the following to start Tomcat.

On Windows:

startTomcat.bat

On Linux or UNIX, the first time you go to start Tomcat you may need to set some permissions. There is a script to help take care of this. Execute the following:

chmod 755 perms.sh
./perms.sh

You should see a message indicated that permissions have been set. After that, all you ever need to do to start Tomcat from $AHWS_HOME is run:

./startTomcat.sh

Step 7: Verify that the Apache Axis2 web service framework is running

Open a browser and navigate to:

http://localhost:8080/axis2/services/listServices

You should see a listing of the available services, including the Version service and the Academic History Service. [Suggeston: someone add a screen shot]

Next navigate to the same location using SSL at:

https://localhost:8443/axis2/services/listServices

You should see the same result, a listing of the available services including the Version Service and the Academic History service. [Suggestion: someone add a screenshot]

The remaining examples will use the secure SSL URLs, because this service should typcially be accessed via SSL. However, the example package includes non-SSL configurations for demostration and debugging activities.

Step 8: Access the Academic History Web Service client web application

Open a browser and navigate to:

http://localhost:8080/ahws/AcademicHistoryWS/AcademicHistoryWS.html
or
https://localhost:8443/ahws/AcademicHistoryWS/AcademicHistoryWS.html

You should see the Academic History Web Service client web application load and provide a text box for entering a URL for the WSDL of the Academic History Web Service. [Suggestion: someone add a screen shot]

Enter the WSDL URL https://localhost:8443/axis2/services/AcademicHistoryService?wsdl into the box and press the "Go" button.

Step 9: Test the Academic History Web Service

Click on the "PingQueryRequest" tab of the client web application and pres the "Go" button. The client should send a PingRequest to the web service and display the result "The service is up" in the Web Service Response box. [Suggestion: add screen shot and additional instructions for testing all of the other actions]

Step 10: Stopping Tomcat and the Academic History Web Service

From the AHWS_HOME directory execute the following to stop Tomcat.