OHF Bridge Install Steps
The page explains the installation process of the Ohf bridge. We promise we'll make it simpler :-)
- 1 Pieces to obtain
- 2 Tomcat Setup
- 3 Eclipse OHF Build Process
- 4 Plugin Installation
- 5 Creation of an Axis jar that will work with the Bridge
Pieces to obtain
- Eclipse 3.2
- Java 5
- Tomcat 5.5.17
- Eclipse Equinox OSGi-on-Server deployable WAR (bridge.war)
- Install Tomcat from source or binary into a directory of your choice
- Launch Tomcat from a command prompt by executing the catalina script or loading the bootstrap.jar directly.
- Go to http://localhost/manager and login with the manager username/password
- Deploy Equinox/OSGi-On-Server Servlet using Tomcat's deployment mechanism
- Kill Tomcat by using Control-C from the command prompt or exit from osgi> prompt
- Open the config.ini' located at at <TOMCAT_HOME>/webapps/bridge/WEB-INF/platform/configuration/config.ini and add , org.eclipse.ohf.bridge@:start at the end of the osgi.bundles property. The file should look like this:
#Eclipse Runtime Configuration File osgi.bundles=org.eclipse.equinox.common@2:start, org.eclipse.update.configurator@start, org.eclipse.equinox.servlet.bridge.http@start, org.eclipse.equinox.http.registry@start, org.eclipse.ohf.bridge@:start osgi.bundles.defaultStartLevel=4
- Copy the following JARs from your Eclipse install's plugins directory to your Tomcat installation's <TOMCAT_HOME>/webapps/bridge/WEB-INF/platform/plugins directory:
org.eclipse.core.runtime_*.jar org.eclipes.core.jobs_*.jar org.eclipse.equinox.preferences_*.jar org.eclipse.core.contenttype_*.jar org.eclipse.emf.ecore_*.jar org.eclipse.emf.common_*.jar org.eclipse.emf.ecore.xmi_*.jar And copy directory: org.junit_3.8.1/
- If your Eclipse plugins directory does not contain the Eclipse plugins, download the last stable version of the EMF SDK from the Eclipse EMF download page.
- Relaunch Tomcat from a command prompt by executing the catalina script
- Create a bridge properties file. A sample file is located at org.eclipse.ohf.bridge\conf\bridge.properties.
- Set a system property for your OS named CATALINA_OPTS with value -Dbridge.properties equals the path to your bridge properties file. A sample DOS script to do that can be found at /org.eclipse.ohf.bridge/etc/setconf.bat. Following is a Windows example:
set CATALINA_OPTS=-Dbridge.properties=<your path to the properties>\bridge.properties
- Generate the bridge configuration files . Use the samples located in the CVS at \org.eclipse.ohf.bridge\conf.
Eclipse OHF Build Process
- Obtain all packages from the /technology/org.eclipse.ohf/plugins folder in Eclipse CVS
- Link org.eclipse.ohf.ihe.xds.soap with the external jar activation.jar (obtained from Sun's download site)
- Make the following modifications to the various Projects:
- Change build.properties to fix Java build
- Link with activation.jar from an External Library
- Change paths to HL7 profiles on lines 86 and 87
- Change paths to HL7 profiles on lines 75 and 76
- Modify the Axis Distribution and make the following changes:
- Add activation.jar to the Project and Project Build Path
- Add activation.jar to the build.properties file
- Modifications to MANIFEST.MF
- Add activation.jar to Bundle-ClassPath
- Add javax.activation to Export-Package
- Add org.apache.commons to Require-Bundle
- Add javax.servlet, javax.servlet.http to Import-Package
IMPORTANT NOTE ON EXPORT ORDER
Before exporting all plug-ins, it MUST be verified that org.eclipse.ohf.ihe.xds.soap is linked with activation.jar and exporting properly. IF NOT ALL CLASS FILES FROM THIS PROJECT EXPORT PROPERLY, IT WILL CAUSE org.eclipse.ohf.ihe.xds.consumer TO BREAK AND NOT EXPORT PROPERLY. IT IS ABSOLUTELY ESSENTIAL THAT YOU VERIFY THAT org.eclipse.ohf.ihe.xds.soap IS PROPERLY LINKING AND EXPORTING. IF YOU RECEIVE AN InvocationTargetException when running the bridge for the first time, THIS IS YOUR PROBLEM AND IT MUST FIRST BE RESOLVED.
- Export all OHF Projects from Eclipse using the Deployable Plug-Ins and Fragments options.
- After export, please see next section on how to properly create an org.apache.axis jar that will work with the bridge.
- Load Plugins into Tomcat using the OSGi command prompt or copy plugins to the Tomcat webapps/bridge/WEB-INF/platforms/plugins folder
- Copy server-config.wsdd file from org.eclipse.ohf.bridge/resources folder in your project workspace to the Tomcat webapps/bridge/WEB-INF folder.
- Restart Tomcat
- To test the install, go to http://localhost:8080/bridge/AxisServlet. If you receive a list of web services, then the install was successful.
Creation of an Axis jar that will work with the Bridge
The following steps are to compose a suitable bundle of Apache Axis for use with Eclipse OHF and the Ohf bridge components. Please note that some steps are performed outside of the Eclipse IDE to avoid several very complicated intermediary steps. This process requires direct manipulation of a Java Archive (JAR). You may use any tool of your choice to do this.
In our example, we will use the jar program included with the Java SDK.
If you have any questions, please contact the Eclipse OHF mailing list or newsgroup. We will try to automate the process.
The following steps are to be performed within the Eclipse IDE
- Obtain the org.apache.axis project from the Eclipse OHF CVS Repository. See: dev.eclipse.org:/cvsroot/technology/org.eclipse.ohf/plugins/org.apache.axis
- Export the org.apache.axis project by right clicking on the project name in Eclipse, select "Export" and then pick "Plug-in Development" -> "Deployable Plug-ins and Fragments"
- Export to a directory of choosing. For example, C:\ohf
The following steps are to be performed outside of the Eclipse IDE
You may use an application of your choosing to manipulate JAR files. We will use the jar program included with the Sun Java SDK for simplicity sake.
- Open a command prompt and navigate to the directory in which you exported the org.apache.axis bundle (cd C:\ohf\plugins)
- Unpack the org.apache.axis bundle using the following command:
jar -xvf org.apache.axis_1.0.0.jar
Note: The jar program may not be in the shell execution path. When runnin in Windoes DOS you may get a responce like:
'jar' is not recognized as an internal or external command, operable program or batch file.
If that happens, locate the Java home directory and use the full path to teh jar program. In windoes it will look something like:
"C:\Program Files\Java\jdk1.5.0_03\bin\jar.exe" -xvf org.apache.axis_1.0.0.jar
- Create a new file called plugin.xml in the directory you just unpacked the Axis JAR. Add the following contents to plugin.xml:
<?xml version="1.0" encoding="UTF-8"?> <?eclipse version="3.2"?> <plugin> <extension point="org.eclipse.equinox.http.registry.servlets"> <servlet alias="/AxisServlet" class="org.apache.axis.transport.http.AxisServlet"/> </extension> <extension point="org.eclipse.equinox.http.registry.servlets"> <servlet alias="/services" class="org.apache.axis.transport.http.AxisServlet"/> </extension> </plugin>
- The Axis implementation we use does not provide an implementation of the javax.acitvation.DataHandler nor the javax.mail.internet.MimeMultipart packages needed for compilation and SOAP with attachment support. Java Mail 1.3.3 (mailapi.jar) and Java Activation Framework 1.0.2 (activation.jar) must be downloaded separately. Take note of exact versions of these jars. These jars can be found at JAF v1.0.2 and JAVA MAIL v1.3.3.
- After downloading the respective packages, unzip each and move their principal JAR file (activation.jar from JAF, mail.jar from Java Mail) to the directory in which you unpacked the Axis jar.
Make the following changes to the file META-INF/MANIFEST.MF
- Bundle-SymbolicName: Make the package a singleton instance (required for extending against the Equinox framework). Do that by adding singleton=true to the Bundle-SymbolicName property.
Bundle-SymbolicName: org.apache.axis; singleton=true
- Bundle-ClassPath: Add activation.jar and mail.jar to the existing list of JAR files in the classpath.
- Export-Package: Force the export of packages provided by activation.jar and mail.jar. Add the following packages to the list:
javax.activation, javax.mail, javax.mail.internet
- Import-Package: For Axis's internal engine to work, it needs to have the Java Servlet API exposed to it. This is provided natively by your application server's web container. Add the following line to the end of your manifest:
Import-Package: javax.servlet, javax.servlet.http
- Require-Bundle: Because Apache Axis runs through its own servlet, it needs to be able to see the packages it's invoking (e.g. bridge). Add the following bundles to the Require-Bundle list:
- Be sure to leave a blank line as the last line in your MANIFEST.MF file
- Delete the original org.apache.axis_1.3.jar file
- Recreate the org.apache.axis JAR while in the C:\ohf\plugins directory using the following command:
jar -cvfmM org.apache.axis.osgi.server_1.3.jar META-INF/MANIFEST.MF .
- Copy the org.apache.axis.osgi.server_1.3.jar file to the directory where the rest of your OHF plugins exist (i.e. to the Tomcat webapps/bridge/WEB-INF/platforms/plugins folder). Ensure that it is the only Axis jar in this directory.
You are now ready to start using Apache Axis in the Equinox server-side bridge and the Eclipse Open Healthcare Framework.