One of the primary design goals of OpenEMed is to be as database independent
as possible. OpenEMed supports relational as well as object oriented database
management systems by means of database managers.
Two of these database managers use object-relational mapping tools that are
themselves implemented on top of the standard JDBC interface. So any database
with a supporting JDBC driver should work. Any ODBC-compliant data source
can also be accessed using JDBC-ODBC bridge.
OpenEMed has been tested with these object oriented databases:
OpenEMed supports different types of pluggable database managers. Two of these managers (JDXDatabaseMgr and OJBDatabaseMgr) provide a object-relational mapping and can therefore be used with a wide variety of relational databases. OpenEMed is tested with MySQL and hsqldb, ut other databases should work too. For more information please contact the vendor.
COAS uses a abstract database interface that makes it independent from a
specific DBMS (Database Management System).This allows to use COAS with a
wide variety of different databases. This is achieved by means of an abstract
database manager (gov.lanl.Database.DatabaseMgr)
gov.lanl.Database.PoetDatabaseMgr:gov.lanl.Database.sODatabaseMgr:gov.lanl.Database.JNDIDatabaseMgr:gov.lanl.Database.JDXDatabaseMgr:gov.lanl.Database.OJBDatabaseMgr:
There are two different solutions to run OpenEMed with Oracle. The first uses the JDXDatabaseMgr, the second OJBDatabaseMgr? Details on using it with OJBDatabaseMgr are described in the answer to Question 6.
Both database managers are quite similar. They map Java objects into relation database tables a mapping file. JDX is a commercial product while ObjectRelationalBridge is open source. Configuration is quite straight forward for both of them. We don't have any performance comparisons, but ObjectBridge appears to scale quite well, is free. It is still under development and may not be as stable as JDX. We focus our discussion here on OJBDatabaseMgr.
First choose a relation database that you will use to store your data. Most of the examples in the distribution directory (OpenEMed/dist) are pre-configured to use ObjectRelationalBridge with instantDB (included in this distribution).
# the type of the database (JDX, JNDI, POET, LDAP, JDO, sO) #DataBaseType JDO DataBaseType OJB #DataBaseType JDO #DataBaseType sO #DataBaseType POET #DataBaseType JDX
Uncomment the line for the database manager that you want to use. E.g. for
ObjectRelationalBridge use 'DatabaseType OJB'. Make sure that you only have
one DataBaseType option (comment out the rest).
Using the right database factory:
The database manager creates persistent capable objects for the CORBA objects
transfered between client and server. These persistent objects are to some
degree database specific and are therefore created in a dynamic way by a factory
class. A properities file (e.g. persist.properties) tells the factory what
objects to create. The file is specified int the COAS configuration file with
the DBFactory attribute. To use a different properties file edit the line
DBFactory persist.properties to the desired file.
persist.properties:
This is the previous mentioned properties file, that maps CORBA classes to
persistent capable classes. It contains two attributes:
#POET #org.omg.DsObservationAccess.ObservationDataStruct gov.lanl.COAS.odmg.ObservationData_ #gov.lanl.COAS.StringMap_ gov.lanl.COAS.odmg.StringMapImpl_ #JDX / sO #org.omg.DsObservationAccess.ObservationDataStruct gov.lanl.COAS.ObservationData_ #gov.lanl.COAS.StringMap_ gov.lanl.COAS.StringMapImpl_ #ObJectBridge org.omg.DsObservationAccess.ObservationDataStruct gov.lanl.COAS.ojb.OjbObservationData_ gov.lanl.COAS.StringMap_ gov.lanl.COAS.StringMapImpl_The attributes commented out can be used for the JDX, sO or POET database manager. Make sure that you comment out or delete the attibute for the other database managers. PIDS has a different mechanism to get to the persistent object factory and doesn't use the persist.properties mechanism.
Buildfile: build.xml
targets:
[echo]
[echo] The following targets are available:
[echo] targets Lists the build targets
[echo] create_oracle Creates the Oracle database for OpenEMed
[echo] create_coas_mysql Creates the MySql database for COAS service
[echo] create_coas Creates the hsqldb database for COAS service
[echo] create_pids Creates the hsqldb database for PIDS service
[echo] create_pids_mysql Creates the Mysql database for PIDS service
[echo] run_nameservice Starts the nameservice
[echo] run_coas_oracle Starts the COAS server with Oracle DB and OJB
(blocking)
[echo]
BUILD SUCCESSFUL
All you need to do to create the MySQL database is to edit the file mysql.properties
the directory OpenEMed\dist\servers to correspond to the appropriate database and user:
mysql.classpath=${lib.dir}/mm.mysql-2.0.14-bin.jar
pids_mysql.url=jdbc:mysql://localhost:3306/pids
coas_mysql.url=jdbc:mysql://localhost:3306/coas
PIDS.userid=openemed
PIDS.password=openemed
COAS.userid=openemed
COAS.password=openemed
Similarly, you should create the appropriate databases and user (with appropriate permissions) in MySQL before creating the tables
These two parameters contain the userID/password combination the COAS server will use to log into the database. You can define your own userId and password but you need to match these names in the mapping file OpenEMed/dist/servers/coas/ojb/config/0.9/mysql_repository.xml.
COAS and PIDS will be created in its own database schema, depending on the userid specified in the property file. The Ant targets performs an SQL command creating the database tables and indices specified in the database schema file at OpenEMed/dist/servers/coas/obj/config/mysql_coas.sql respectively. OpenEMed/dist/servers/pids/obj/config/mysql_pids.sql. These files should not be changed.
The distribution ships with Orbacus 4.0, a NamingService from Object Oriented
Concepts (http://www.ooc.com). To start the server open a new console and
execute the script file OpenEMed/dist/servers/namingservice.bat. This will
run an nameservice on your local machine as localhost on port 5001. You can
change this settings accordingly.
To start the service by hand enter
java -Xbootclasspath/p:%ORBPATH% -Dorg.omg.CORBA.ORBClass=com.ooc.CORBA.ORB
-Dorg.omg.CORBA.ORBSingletonClass=com.ooc.CORBA.ORBSingleton %ORBPATH%;%JVMPATH%
com.ooc.CosNaming.Server -OAport 5000
-OAhost 127.0.0.1 -d OrbacusNameService.db -i
with
JVMPATH environment variable set to the Java runtime libraries
ORBPATH environment variable set to the Orbacus libraries, e.g. ORBPATH=/OpenEMed/lib/OB.jar;/OpenEMed/lib/OBUtil.jar;/OpenEMed/lib/OBNaming.jar;/OpenEMed/lib/OBTrading.jar
Explanation of the Java VM Parameters:
-Xbootclasspath/p prepends directories and zip/jar files in front
of bootstrap class path. May or may not be necessary depending on the JVM
and Orbacus version. -Dorg.omg.CORBA.ORBClass=com.ooc.CORBA.ORB -Dorg.omg.CORBA.ORBSingletonClass=com.ooc.CORBA.ORBSingleton
tells the Java Virtual Machine the concrete classes to instantiate
for the CORBA interface. When using a different ORB you will have to change
this settings.
Explanation of com.ooc.CosNaming.Server parameters:
-OAport sets the listening port (here 5000) -OAhost set the listening machine
(here localhost) -d OrbacusNameService.db -i tells the nameservice to use
an existing reference database Alternatively the Ant target 'run_nameservice'
can be used to start the service. The nameservice will block the console during
its runtime. On Windows machines the service can be ended with CTRL-C. In
order to have access to the CORBA objects from another machine, localhost
should be changed to the machine name.
Make sure a namingservice is running. To start the COAS service open a new
console and execute the script file OpenEMed/dist/serves/coas.bat To start
the service by hand enter
java -mx128m -ms128m -Dorg.omg.CORBA.ORBClass=com.ooc.CORBA.ORB -Dorg.omg.CORBA.ORBSingletonClass=com.ooc.CORBA.ORBSingleton
-classpath %OPENEMEDPATH%;%JDXPATH%;%POETPATH%;%IAIKPATH%;%JVMPATH%;%ORBPATH%
-Dtelemed.authen=njc.org gov.lanl.COAS.ObservationComponentImpl -file Coas.cfg
-ORBconfig orb.properties
with JVMPATH environment variable to the Java runtime libraries, ORBPATH environment
variable to the Orbacus libraries, JDXPATH environment variable to the JDX
library files, needed for JDXDatabaseMgr (not included in this distribution),
POETPATH environment variable to POET library files, needed for POETDatabaseMgr
(not included in this distribution), IAIKPATH environment varibale to ISAI
library files, needed to run services with security turned on OPENEMEDPATH
environment variable to the OpenEMed libraries, e.g. /OpenEMEd/dist/lib/corbamed.jar;/OpenEMed/dist/lib/OpenEMed.jar;/OpenEMed/dist/lib/servers-persistent.jar;/OpenEMed/dist/lib/tools.jar;
Explanation of the Java VM parameters:
-mx set the initial Java heap size (here 128 MB) -ms set the
maximal Java heap size (here 128 MB)
-Dorg.omg.CORBA.ORBClass=com.ooc.CORBA.ORB -Dorg.omg.CORBA.ORBSingletonClass=com.ooc.CORBA.ORBSingleton
tells the Java Virtual Machine the concrete classes to instiate for
the CORBA interface. When using a different ORB you will have to change this
settings.
All the files in this directory are third-party archive distributed with OpenEMed, please see copyright info on some files.
All the files in this directory are created by OpenEMed from source code
clients.jar class file archive of the client software
(built from OpenEMed/src/clients)corbamed.jar class file archive of the CORBAmed specifications
(also available with documenation at at the Healthcare Domain Taskforce
webpage of the OMG, http://healthcare.omg.org)OpenEMed.jar class file archive of OpenEMed's CORBA
specificationservers-persistent.jar class file archive of OpenEMed's
persistent servers (built from OpenEMed/src/servers/persistent)servers-transient.jar class file archive of OpenEMed's
transient servers (built from OpenEMed/src/servers/transienttools.jar class file archive of OpenEMed's tool library
(build from OpenEMed/src/tools)
COAS uses a properties file to control most of the runtime parameters to
avoid having to hardcode many of the options. The properties file is specified
on the command line to run coas with the -file option (which must be the first
optional parameter). Any parameter can be overridden on the command line with
the expression "-
The easiest way to answer this question is to read the more detailed documentation
on persistence in the Person Identification
Service. It provides a sample usage of calling the DatabaseMgr demonstrating
its independence of the type of Database involved.
#
# COAS Configuration File
#
#
# Reference name to register at namingService
#
# This is the name COAS registers itself to the naming service.
# Use this name to look up this service at a naming service.
serverName COASServer
#
# Database type
#
# This specifies the database manager to be used.
# Allowed values are JDX, JNDI, POET, LDAP, JDO, sO
DataBaseType OJB
#
# Database URL
#
# This specifies a connection string or file that is passed to the database manager. The
# database manager tries to open a connection using this string or file
# Example settings:
# for POET:
#DataBase poet://LOCAL/DsOAS.db
# for JDX:
#DataBase jdbc:odbc:DsOAS;JDX_ORMFile=DsOAS-Access.jdx;JDX_DBTYPE=MSACCESS
# for OJB/Instantdb
#DataBase ojb//config//repository.xml
# for OJB/Oracle:
DataBase ojb//config//repositoryOracle.xml
#
# PersistentFactory File
#
# This attribute specifies a properties file that contains the
# CORBA-to-persistent class mapping.
DBFactory persist.properties
#
# Database Population File
#
# This attribute specifies the XML data file to populate the database.
CreateDB SmallMedServer.xml
#
# Multimedia embedding
#
# This attribute embeds a URI as a blob in a multimedia object (yes/no)
# This attribute specifies if URI in a multimedia object (which are specified
# in the database population file) should be embedded as a BLOB in the
# database or not. If 'no', the URI is stored as a string in the database,
# if 'yes' the URI is read by an URLReader and stored as an BLOB.
#
# NOTE: createDB must be specified
embedMultimedia no
# Generate XML file from input file
# This attribute can be used to create a new xml file from the input xml file
# (specified with the 'CreateDB' attribute)
# This can be useful to embed URIs as BLOBS in an xml file. The BLOBS will be
# BINHEX64 encoded.
#
# NOTE: CreateDB must be specified
# createXML generatedXML.xml
# debug mode
# This attribute turns debugging on or off. Attribute will become obsolete once as
# we update COAS to use the Log4J logging kit.
debug off
#
# Policies section
#
# The following policy define the default behavior of COAS.
# Policies can be examined at runtime. The default behavior can also be altered
# by passing policies to the corresponding access method.
#
# ObsIdInsteadOfDataPolicy
#
# This policy specifies if observation identification numbers (ObsId) instead of the data
# itself will be returned for specific qualified codes by the server. If set to 'true'
# an ObsId will be returned for all qualified codes specified in the observation value
# replacement section (see below). This option is useful to save minimize memory and bandwidth
# requirements for large observation values. If an observation value got replace by an ObsId,
# its value can be retrieved in a second call using the
# org.omg.DsObservationAccess.QueryAccess.get_observation(org.omg.DsObservationAccess.ObservationId observation_id)
# call.
ObsIdInsteadOfDataPolicy=false
#
#ObsIdReturnPolicy
#
# This policy specifies if each ObservationData object has an observation identifier
# (ObsId) attached or not. The ObsId is needed for modifications to the object.
# If no modification to the data are necessary, this attribute should be set to
# 'false' to minimize memory and bandwidth requirements.
#
ObsIdReturnPolicy = false
#
#SupportedCodesReturnAllPolicy
#
# This policy specifies if a call to org.omg.DsObservationAccess.QueryAccess.get_supported_codes(...)
# returns all (SupportedCodesReturnAllPolicy = true) qualified codes or just the top-level
# codes (SupportedCodesReturnAllPolicy = false).
SupportedCodesReturnAllPolicy = false
#
# Observation value replacement section
#
# The qualified codes defined here can be used to replace observation values by
# observation ids.
# The ObsIdInsteadOfDataPolicy must be set to true in this configuration file
# or must be specified explicitly in the call.
# Add each replacement qualified code by the 'replaceByObsId' attribute plus a
# continuous integer number starting with '1'.
# Example:
# replaceByObsId1 DNS:OpenEMed.org/TraitCode/ImageStudy/ImageSeries/Image
# replaceByObsId2 DNS:OpenEMed.org/TraitCode/Multimedia
#
replaceByObsId1 DNS:telemed.lanl.gov/TraitCode/ImageStudy/ImageSeries/Image
#
# Secondary observation data section
#
# The qualified codes defined here are stored in a different, non-search able
# database table. This has the advantage to keep the main storage table for
# observation data objects smaller and increase query performance on this table.
#
# Add each code to be insert into the non-search able table
# by the 'putIntoSecondary' attribute plus a continuous integer number
# starting with '1'.
# Example:
#putIntoSecondary1 DNS:OpenEMed.org/TraitCode/ImageStudy/ImageSeries
#putIntoSecondary2 DNS:OpenEMed.org/TraitCode/Multimedia
putIntoSecondary1 DNS:telemed.lanl.gov/TraitCode/ImageStudy/ImageSeries
#
# Attribute parser [need to check on this one!!!]
#
# This attribute specifies the parser to parse the attribute personId, startTime,
# stopTime and signingFlag. Possible values are 'String' or 'HL7'. 'String' treats
# these attributes as they are without conversion. HL7 takes the qualified code and
# parses the values in accordance with the HL7 specification to some internal format.
parser HL7
#
# Attribute to QualifiedCode mapping
#
# PersonId, startTime and stopTime are some of the main search parameters in
# COAS (who and when). When population the database from an XML file, these
# attributes specify the qualified codes to use for this search parameters.
# signingFlag is a special attribute to mark an observation as read only.
personId DNS:omg.org/DSObservationAccess/HL72.3/PID/PatientIDInternalID
startTime DNS:omg.org/DSObservationAccess/HL72.3/OBR/ObservationDate_Time
stopTime DNS:omg.org/DSObservationAccess/HL72.3/OBR/ObservationEndDate_Time
signingFlag DNS:telemed.lanl.gov/QualifierCode/IsSigned
#SSL Service parameters
# See KeyManager documentation for more complete documentation on these variables.
# SSL specifies whether to do use SSL authentication with digital certificates
# KEYSTOREPATH indicates what keystore to use
# KEALIAS is the alias of the key in the keystore to use
# KEYPASS is the password for the specified alias
# TRUSTDECIDERCLASS name of Java class to call to verify the credentials of the user
# SSLSERVICETYPE JFSSL or ADIRON (ADIRON is the CSIv2 implementation)
# SSLCIPHERS specifies which encryption algorithm to use
# VERBOSE determines how much information to display in setting up the SSL security.
SSL=off
KEYSTOREPATH=../keystores/CA_1.keystore
KEYALIAS=ca1
KEYPASS=ca1pass
TRUSTDECIDERCLASS=default
SSLSERVICETYPE=JFSSL
SSLCIPHERS=RSA
VERBOSE=true