Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

OHF Bridge

Revision as of 11:19, 30 August 2006 by Eishay.gmail.com (Talk | contribs) (The following steps are to be performed outside of the Eclipse IDE)

OHF Bridge Alpha Release

The OHF Bridge is an OHF subproject which supplies SOAP access to the OHF plugins. The plugins that are directly invoked on the first release of the bridge are the OHF IHE Client plugins. These plugins calls other OHF plugins to get facilities for HL7 stack, security and auditing.

The OHF Bridge is based on the OSGi on Server project in order to load the OHF plugins into teh server environment.


An early preview of OHF Bridge's API has been released. This allows a PHP EMR application to search patients and retrieve documents from a healthcare repository.
Please view the API first to learn more about OHF Bridge:
OHF Bridge Documentation

Next, take a look at the sample PHP application that demonstrates the implementation of OHF Bridge:
Sample Application
(Alternatively, a command line version of the same application is here: Test.php)

A zip package that includes everything mentioned above can be downloaded here:
OHF Bridge Package

Please post any questions or concerns on the OHF newsgroup at:
news://news.eclipse.org/eclipse.technology.ohf

OHF in Action

A demonstration of OHF's capabilities are now being shown at the following link:

http://ibmod235.dal-ebis.ihost.com:8080/ohf/demo/index.php

The demonstration shows the full pipeline from a PDQ query, which returns matches based on the demographic information provided about a patient, to the retrieval of a document through XDS for a specific patient. To best demonstrate the functions that exist at the current time, please follow the instructions below.

  1. Choose "Wisconsin" as the state of residence for the patient for whom you are searching
  2. Click the "Search" button, and you should see a list of patients at the bottom of the page
  3. You'll notice that one of the patients is named Joyce Murphy. Click on the "Search for Documents" link under her information
  4. A list of documents that are linked to Joyce Murphy are displayed. Currently only Patient Generated Medical History can be retrieved and displayed. Click on any of the files that are labeled as Patient Generated Medical History.
  5. Congratulations! You have queried for a patient using PDQ and retrieved a patient document through XDS

While the demo is still in its early stages, it does show that the capability to connect healthcare players from corporations to local hospitals is a reality and not just a dream. Currently there is both limited data and limited functionality. While these shortcomings are being ironed out, the principal of connectivity in healthcare is still being demonstrated.

The WSDL files off of which the web services are generated can be found at the following links:

OHF Bridge in the CVS

For general instractions for the OHF CVS take a look at this page.

Eclipse/OSGi

The OHF Bridge Eclipse/OSGi projects are stored in the Eclipse Technology CVS repository. The projects are:

OHF Bridge Adapters (org.eclipse.ohf.bridge)

The OHF Bridge Adapters takes incoming requests from the web service, marshalls the request object to message query object and calls the Eclipse OHF plugin which will handle the repository access.

OHF Bridge Web Services (org.eclipse.ohf.bridge.ws)

The OHF Bridge Web Services reside in a SOAP Engine such as Apache Axis. They acquire SOAP envelopes from EMR applications and call a series of internal methods provided by the Adapters.

OHF Bridge PHP Client (org.eclipse.ohf.bridge.client)

The OHF Bridge PHP Client contains all the PHP source code of a sample application that implements the OHF Bridge API.

OHF Architecture

Overall Architecture Design

Bridge-architecture.png

API Implementation Inside EMR Applications

OHF Bridge provides a simple API consisting of methods that allow an EMR application to search patients with demographic information, and then create, retrieve and save patient documents. The API is initially developed for the LAMP environment, and will be extended to other platforms such as Java and .NET. Once an EMR application accesses a method to request a call to the interoperability stack, the call is packaged into a SOAP envelope and then sent to the OHF Web Service.

OHF Bridge Web Services

The OHF Web Services resides inside the AXIS SOAP Engine, which has been ported to an OSGi bundle inside Tomcat. Once the Web Services acquires the SOAP envelope from the EMR application, it calls a series of internal methods provided by the Adapters. These internal methods are designed to cast the received call object to OHF objects recognizable by the PDQ, PIX, and XDS plug-ins. Once the casting is done, the OHF objects are passed onto the plug-ins.

Eclipse OHF Plug-ins

The OHF Plug-ins includes three distinct mechanisms (PDQ, PIX, and XDS), each consists of two components: the component that retrieves files (the consumer component) and another component that creates files (the source component). The PDQ plug-in handles the search of patient with demographic information including patient ID, full name, address, gender, date of birth, and contact information and returns a list of possible matches. Next, the PIX plug-in handle the cross-reference and comparison of patient metadata. Lastly, the XDS plug-in finds a list of documents for the matching patient and retrieves the full content of a selected document.

Interoperability Stack

The Interoperability Stack is a physical datacenter that hosts patient medical documents. It conforms fully to the HL7 international healthcare standard. It has two separate components: the registry that hosts the metadata for patient and document search, and the repository that stores the contents of medical documents. In the event of patient search, the search is done in the registry; a list of matching patient is then returned. In the event of document retrieval, the registry accesses the repository, pulls the document and returns it. If the EMR application requests a creation, change or deletion of a document, the repository will first take the appropriate action and update the document, and then it will request a change in the metadata within the registry. A security component lies on top of both the repository and the registry and performs the permission handling.


Bridge Install Steps

Pieces to obtain

  • Eclipse 3.2
  • Java 5
  • Tomcat 5.5.17
  • Eclipse Equinox OSGi-on-Server deployable WAR (bridge.war)

Tomcat Setup

  1. Install Tomcat from source or binary into a directory of your choice
  2. Launch Tomcat from a command prompt by executing the catalina script or loading the bootstrap.jar directly.
  3. Go to http://localhost/manager and login with the manager username/password
  4. Deploy Equinox/OSGi-On-Server Servlet using Tomcat's deployment mechanism
  5. Kill Tomcat by using Control-C from the command prompt or exit from osgi> prompt
  6. Copy the following JARs from your Eclipse install's plugins directory to your Tomcat installation's 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/

Relaunch Tomcat from a command prompt by executing the catalina script

Eclipse OHF Build Process

  1. Obtain all packages from the /technology/org.eclipse.ohf/plugins folder in Eclipse CVS
  2. Link org.eclipse.ohf.ihe.xds.soap with the external jar activation.jar (obtained from Sun's download site)
  3. Make the following modifications to the various Projects:
    org.eclipse.ohf.ihe.xds.consumer
    Change build.properties to fix Java build
    org.eclipse.ohf.ihe.xds.soap
    Link with activation.jar from an External Library
    org.eclipse.ohf.bridge.pdq.PDQbridge.java
    Change paths to HL7 profiles on lines 86 and 87
    org.eclipse.ohf.bridge.pix.PIXConsumerBridge.java
    Change paths to HL7 profiles on lines 75 and 76
  4. 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 [Eishay] Check it out... poblems export the plugin this way
  5. In the org.eclipse.ohf.hl7v2.core.definitions.model.NamedDefn.java change the getName() method to:
     public String getName() {
           int lastSep = getPath().lastIndexOf(PATH_SEPARATOR);
           return getPath().substring(lastSep+1);
      }
       Yes! Its a hack due to a pending bug. When the bug will be fixed we'll remove this instruction 
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.

Plugin Installation

  1. Export all OHF Projects from Eclipse using the Deployable Plug-Ins and Fragments options.
  2. After export, please see next section on how to properly create an org.apache.axis jar that will work with the bridge.
  3. Load Plugins into Tomcat using the OSGi command prompt or copy plugins to the Tomcat webapps/bridge/WEB-INF/platforms/plugins folder
  4. Copy server-config.wsdd file from org.eclipse.ohf.bridge/resources folder in your project workspace to the Tomcat webapps/bridge/WEB-INF folder.
  5. Restart Tomcat
  6. 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

  1. 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
  1. 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"
  2. 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\j2re1.4.2_01\bin\jar -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.
activation.jar,
mail.jar,
  • 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:
org.eclipse.ohf.bridge,
org.eclipse.ohf.bridge.ws
  • 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_1.3.osgi.server.jar META-INF/MANIFEST.MF .

You are now ready to start using Apache Axis in the Equinox server-side bridge and the Eclipse Open Healthcare Framework. Copy the org.apache.axis_1.3.osgi.server.jar file to the directory where the rest of your OHF plugins exist.

Back to the top