About Paxtools.jar

INOH

2007/09/12

TOC

Overview

This documentation explains about org.biopax.paxtools.proxy and org.biopax.paxtools.persistence among Paxtools.

Operating Environment

OS
Windows 2000/XP, Mac OS X, Linux, BSD and Unix assumable.
Windows Xp and RedHat Linux 9 are used for the development.
Java
1.5.0 or later
DBMS
PostgreSQL 8.x or MySQL 5.x
DBMS may be sufficient if a host is different from the environment where Paxtools.jar is used.

Outline of main packages

org.biopax.paxtools.model
It is a model of the element of bioPAX. It's defined as the Java interface.
When using the library of Paxtools.jar, it is desired to access through this model.
org.biopax.paxtools.impl
It's defined as the implementation of the model, the Java implementation.
It is an actual functional portion in the library of Paxtools.jar. The content of each element is stored in the instance. It is desired to us this through the model.
org.biopax.paxtools.proxy
Although this is also the implementation of the model, the Java implementation, it is a substitute (proxy) for the persistence of Java using JPA (Hibernate), and org.biopax.paxtools.impl is called for the function.
Notations are used for the persistence and searching.
org.biopax.paxtools.persistence
It has the persistence of the OWL file using a proxy, and has a function of searching the variety of information using the persistence data.

Other required libraries

The following libraries are required to use Paxtools.jar.

RDF related
aspectjrt.jar
collections-generic-4.01.jar
commons-logging.jar
concurrent.jar
icu4j_3_4.jar
iri.jar
jakarta-oro.jar
jena.jar
junit-4.1.jar
log4j-1.2.12.jar
xercesImpl.jar
xml-apis.jar
Persistence related
antlr-2.7.6.jar
asm.jar
cglib-2.1.3.jar
commons-collections-2.1.1.jar
dom4j-1.6.1.jar
ehcache-1.2.3.jar
ejb3-persistence.jar
hibernate-annotations.jar
hibernate-commons-annotations.jar
hibernate-entitymanager.jar
hibernate-search.jar
hibernate3.jar
hibernate3.jar.new
javassist.jar
jboss-archive-browsing.jar
jdbc2_0-stdext.jar
jta.jar
lucene-core-2.1.0.jar
DBMS driver
mysql-connector-java-5.0.7-bin.jar (In case MySQL is used for the persistence.)
postgresql-8.2-504.jdbc3.jar (In case PostgreSQL is used for the persistence.)

The following are used for Persistence related library above mentioned by the development.

Hibernate 3.2.3
Hibernate Annotations 3.3.0 GA
Hibernate EntityManager 3.3.1 GA
Hibernate Search 3.0.0 Beta1

Setting up DBMS

The setup of DBMS and Lusene is required for the persistence-related function among Paxtools.jar.

The operation of DBMS is checked by PostgreSQL (8.2) and MySQL (5.0.)

Decide the host used for DB access, DB space name, and a user name.

The default value is described in META-INF/persistence.xml in Paxtools.jar.

The property name of a host and DB space name is "hibernate.connection.url", and a value is "jdbc:postgresql://localhost/PAXTOOLS" or "jdbc:mysql://localhost/PAXTOOLS."

The property name of a user name is "hibernate.connection.username"and the value is "paxtools."

These values can be set up in org.biopax.paxtools.persistence.level2.HiRDBConnect.

Setting up PostgreSQL

The locale of DB cluster and DB space needs to be coincided for PostgreSQL.

Please specify ja_JP.utf8 as follows when creating the DB cluster.

initdb -D /opt/pgsql/data --locale=ja_JP.utf8

Moreover, please specify UNICODE when creating the DB space.

createdb PAXTOOLS -E UNICODE

If this locale information is not in agreement, the phenomenon of an error with the upper function is confirmed.

Please note that PostgreSQL will be set to ja_JP.eucJP by the default even if the file system of the distribution of Linux is UTF-8 base.

createuser is for creating the PostgreSQL user.

createuser paxtools

When a machine using Paxtools.jar and the host of PostgreSQL are different, it will be connected by the network. but it is necessary to permit the access by pg_hba.conf in the directory of DB cluster.

Setting up MySQL

The following shows how to create the MySQL user.

Create two users, for the local host and for other than the local host.

mysql --user=root mysql
grant all privileges on *.* to paxtools@localhost;
grant all privileges on *.* to paxtools@'%';

The following shows how to create the DB space of MySQL.

mysql
create database PAXTOOLS;

Setting up Lucene

The directory path for the Licene index is required.

mkdir /opt/paxtools/lucene_index

Since there is no initial value, it is necessary to set up the value in org.biopax.paxtools.persistence.level2.HiRDBConnect.

Functions for checking of operation

org.biopax.paxtools.persistence.level2.HiRDBTrial has the main function for checking the operation of the persistence and searching.

How to use

java -classpath The path of the above-mentioned library and Paxtools.ja. 
org.biopax.paxtools.persistence.level2.HiRDBTrial [Option] command parameter...

Option

OptionDescription

-i Setting file path

-ini Setting file path

The path of the ini file which sets up the option.

If omitted, HiRDBTrialCmd.ini of the current directory will be used.

-f File path

-file File path

-filePath File path

The file path of the command which needs a file path.

The file path is used by the command of buildddl, upload, and download.

-puName Persistence unit name

Character strings which choose persistence-unit under META-INF/persistence.xml.

Specify PaxtoolsForPostgreSQL or PaxtoolsForMySQL.

If omitted PaxtoolsForPostgreSQL will be used.

-jdbc URL

The URL which describes the host name and the space name of DB.

If omitted "jdbc:postgresql://localhost/PAXTOOLS" will be used.

-user DB user name

It is a user name to access DB.

If omitted "paxtools" will be used.

-password DB user password

It is a user password to access DB.

If omitted, an empty string will be used.

-indexBase directory path

It is a directory path for Lucene index.

If omitted, an empty string will be used.

Example of HiRDBTrialCmd.ini

puName=PaxtoolsForPostgreSQL
jdbc=jdbc\:postgresql\://miracle/PAXTOOLS
user=paxtools
indexBase=D:\\Paxtools\\lucene_index

Command

Command for persistence

buildddl
Create the DDL file.
Specify the output file path by -f option.
upload
Persist the OWL file.
Specify the input file path by -f option.
Resister the file name as a key.
download
Output the persistent OWL file.
Specify the output file path by -f option.
Call the file name as a key.
keyword
Search by the keyword.
Output rdf:ID of the element hit.
list
Output a list of the persistent keys (file names.)

Search Command

The search command makes the API name a command and adds a parameter to it.

Elements among parameters (pathway etc.) can be specified by the rdf:ID with name space.

Boolean can be specified as true or false.

getPathwayList
Acquire all pathway.
getPathwayListByNAME
Acquire pathway that matches the query.
getPathwayListByORGANISM
Acquire pathway from the organism.
getSuperPathwayList
Acquire the parent of pathway
getAllSuperPathwayList
Acquire all the ancestor of pathway.
getAllSubPathwayList
Acquire all the descendant of pathway.
getTopLevelPathway
Acquire the most outside of the pathway including pathways.
getNEXT_STEPListOfPathway
Acquire the event which occurs next to pathway by pathwayStep.
getAllNEXT_STEPListOfPathway
Acquire all the event which occurs next to pathway by pathwayStep.
getPreviousStepListOfPathway
Acquire the event which occurs before pathway by pathwayStep.
getAllPreviousStepListOfPathway
Acquire all the event which occurs before pathway by pathwayStep.
getEC_NUMBERListInPathway
Acquire the entire enzyme included in pathway.
getPhysicalEntityListInPathway
Acquire all physicalEntity included in pathway.
getInteractionListInPathway
Acquire all included in pathway.
getAllEvidenceListInPathway
Acquire a list of EVIDENCE in pathway.
getPathwayListByTERMOfEVIDENCE_CODE
Acquire pathway from TERM of EVIDENCE-CODE.
getInteractionList
Acquire all interaction.
getControlList
Acquire all control.
getCatalysisList
Acquire all interaction.
getModulationList
Acquire all modulation.
getConversionList
Acquire all conversion.
getBiochemicalReactionList
Acquire all biochemicalReaction.
getTransportWithBiochemicalReactionList
Acquire all transportWithBiochemicalReaction.
getComplexAssemblyList
Acquire all complexAssembly.
getTransportList
Acquire all transport.
getInteractionListByNAME
Acquire interaction whose query matches Name or SHORT-NAME.
getInteractionListByINTERACTION_TYPE
Acquire interaction whose query matches INTERACTION-TYPE.
getBiochemicalReactionListByEC_NUMBER
Acquire biochemicalReaction from the enzyme.
getControlListByCONTROLLED
Acquire control from CONTROLLED.
getCONTROLLERListByCONTROLLED
Acquire CONTROLLER from CONTROLLED.
getPhysicalEntityList
Acquire all physicalEntity.
getComplexList
Acquire all complex.
getDnaList
Acquire all dna.
getProteinList
Acquire all protein.
getRnaList
Acquire all rna.
getSmallMoleculeList
Acquire all smallMolecule.
getPhysicalEntityListByNAME
Acquire physicalEntity whose query matches Name.
getPhysicalEntityListByORGANISM
Acquire physicalEntity from the organism (Except for smallMolecule.)
getSequenceEntityListBySEQUENCE
Acquire protein, dna and rna from the array.
isNEXT_STEPof
The reverse pointer of NEXT-STEP.
isPATHWAY_COMPONENTSof
The reverse pointer of PATHWAY-COMPONENTS.
isSTEP_INTERACTIONSof
The reverse pointer of STEP-INTERACTIONS.
isXREFof
The reverse pointer of XREF.
isPARTICIPANTSof
The reverse pointer of PARTICIPANTS
isCOMPONENTSof
The reverse pointer of COMPONENTS
isPHYSICAL_ENTITYof
The reverse pointer of PHYSICAL-ENTITY
getEntityListByDATA_SOURCE
Acquire entity from DATA-SOURCE.
getEntityListByDBAndIDOfXREF
Acquire entity form DB and ID of XREF.
getEntityListByNAME
Acquire entity whose query matches NAME.
getDataSourceList
Acquire a list of NAME of dataSource.
getEntityListByAVAIRABILITY
Acquire entity whose query matches AVAIRABILITY.
getEntityListByCOMMENT
Acquire entity whose query matches COMMENT.

How to use the HiRDB Class

Here we explain how to use the HiRDB class from the application which uses the persistence by Paxtools.jar.

HiRDB holds the connection and the session of the persistence.

HiRDBConnect and HiRDBSession are used when more detailed operation is required.

HiRDB is one of the example of how to use HiRDBConnect and HiRDBSession.

Constructor

HiRDB.HiRDB(String puName, String connectionURL, String user, String password, String indexBase)

Set the various parameters about the persistence and call the constructor.

Actual connection etc. is not made when calling the constructor.

When HiRDB.setup is called explicitly or when various commands, such as search, are called before setting up, the setup is performed automatically, and connection are made.

Setting up

boolean HiRDB.setup()

Connect and make the session.

There is no explicit release of the connection.

Call HiRDB.getSession().close() in order to release the session.

The element (for example, pathway) obtained by the search of persistence etc. and its property (for example, NAME) are effective only while the session is maintained.

An error may occur when accessing the element and the property after releasing the session.

Acquiring the element by rdf:ID

public BioPAXElement HiRDB.getElementByRDFID(String rdfID)

Specify rdf:ID and acquire the element (the element which inherits BioPAXElement, for example, pathway.)

The full path with the name space is required for rdf:ID.

Acquiring the keyword search instance

KeywordSearch createKeywordSearch()

Acquire the instance of keyword search.

The following search can be called using the acquired instance.

search(String keyword)
Search by keyword from all field of Lucene.
search(String fieldName, String keyword)
Search by keyword by specifying the field.

Field

OWL data is classified by various character strings into the following field when persisted, and these are passed to Lucene.

BioPAXElementProxy.SEARCH_INDEX_NAME = "paxtools";
BioPAXElementProxy.SEARCH_FIELD_KEYWORD = "keyword";
BioPAXElementProxy.SEARCH_FIELD_NAME = "name";
BioPAXElementProxy.SEARCH_FIELD_SYNONYMS = "synonyms";
BioPAXElementProxy.SEARCH_FIELD_TERM = "term";
BioPAXElementProxy.SEARCH_FIELD_EC_NUMBER = "ec_number";
BioPAXElementProxy.SEARCH_FIELD_SEQUENCE = "sequence";
BioPAXElementProxy.SEARCH_FIELD_XREF_DB = "xref_db";
BioPAXElementProxy.SEARCH_FIELD_XREF_ID = "xref_id";
BioPAXElementProxy.SEARCH_FIELD_AVAILABILITY = "availability";
BioPAXElementProxy.SEARCH_FIELD_COMMENT = "comment";

Acquiring the instance of the Pathway search

PathwaySearch createPathwaySearch()

Acquire the instance of the search by Pathway.

The following searches are called using the acquired instance.

getPathwayList
Acquire all pathway.
getPathwayListByNAME
Acquire pathway that matches the query.
getPathwayListByORGANISM
Acquire pathway from the organism.
getSuperPathwayList
Acquire the parent of pathway.
getAllSuperPathwayList
Acquire all the ancestor of pathway.
getAllSubPathwayList
Acquire all the descendant of pathway.
getTopLevelPathway
Acquire the most outside of the pathway including pathways.
getNEXT_STEPListOfPathway
Acquire the event which occurs next to pathway by pathwayStep.
getAllNEXT_STEPListOfPathway
Acquire all the event which occurs next to pathway by pathwayStep.
getPreviousStepListOfPathway
Acquire the event which occurs before pathway by pathwayStep.
getAllPreviousStepListOfPathway
Acquire all the event which occurs before pathway by pathwayStep.
getEC_NUMBERListInPathway
Acquire the entire enzyme included in pathway.
getPhysicalEntityListInPathway
Acquire all physicalEntity included in pathway.
getInteractionListInPathway
Acquire all physicalEntity included in pathway.
getAllEvidenceListInPathway
Acquire a list of EVIDENCE in pathway.
getPathwayListByTERMOfEVIDENCE_CODE
Acquire pathway from TERM of EVIDENCE-CODE.

Acquiring the Interaction search instance

InteractionSearch createInteractionSearch()

Acquire the instance of Interaction search.

The following search can be called using the acquired instance.

getInteractionList
Acquire all interaction.
getControlList
Acquire all control.
getCatalysisList
Acquire all interaction.
getModulationList
Acquire all modulation.
getConversionList
Acquire all conversion.
getBiochemicalReactionList
Acquire all biochemicalReaction.
getTransportWithBiochemicalReactionList
Acquire all transportWithBiochemicalReaction.
getComplexAssemblyList
Acquire all complexAssembly.
getTransportList
Acquire all transport.
getInteractionListByNAME
Acquire interaction whose query matches Name or SHORT-NAME.
getInteractionListByINTERACTION_TYPE
Acquire interaction whose query matches INTERACTION-TYPE.
getBiochemicalReactionListByEC_NUMBER
Acquire biochemicalReaction from the enzyme.
getControlListByCONTROLLED
Acquire control from CONTROLLED.
getCONTROLLERListByCONTROLLED
Acquire CONTROLLER from CONTROLLED.

Acquiring the PhysicalEntity search instance

PhysicalEntitySearch createPhysicalEntitySearch()

Acquire the instance of PhysicalEntity search.

The following search can be called using the acquired instance.

getPhysicalEntityList
Acquire all physicalEntity.
getComplexList
Acquire all complex.
getDnaList
Acquire all dna.
getProteinList
Acquire all protein.
getRnaList
Acquire all rna.
getSmallMoleculeList
Acquire all smallMolecule.
getPhysicalEntityListByNAME
Acquire physicalEntity whose query matches NAME.
getPhysicalEntityListByORGANISM
Acquire physicalEntity (except for smallMolecule) from the organism.
getSequenceEntityListBySEQUENCE
Acquire protein, dna and rna from the array.

Acquiring other search instance

MiscSearch createMiscSearch()

Acquire the instance of other search.

The following search can be called using the acquired instance.

isNEXT_STEPof
The reverse pointer of NEXT-STEP.
isPATHWAY_COMPONENTSof
The reverse pointer of PATHWAY-COMPONENTS.
isSTEP_INTERACTIONSof
The reverse pointer of STEP-INTERACTIONS.
isXREFof
The reverse pointer of XREF.
isPARTICIPANTSof
The reverse pointer of PARTICIPANTS
isCOMPONENTSof
The reverse pointer of COMPONENTS
isPHYSICAL_ENTITYof
The reverse pointer of PHYSICAL-ENTITY
getEntityListByDATA_SOURCE
Acquire entity from DATA-SOURCE.
getEntityListByDBAndIDOfXREF
Acquire entity form DB and ID of XREF.
getEntityListByNAME
Acquire entity whose query matches NAME.
getDataSourceList
Acquire a list of NAME of dataSource.
getEntityListByAVAIRABILITY
Acquire entity whose query matches AVAIRABILITY.
getEntityListByCOMMENT
Acquire entity whose query matches COMMENT.