org.ifeth.sehr.core.lib

Class SEHRDataSource

java.lang.Object

org.ifeth.sehr.core.lib.SEHRDataSource

public class SEHRDataSource
extends java.lang.Object

Simple class for accessing the firebird databases from SEHR projects as well as to read/save local files on the SEHR host like profiles, data stores - encrypted or not.

To access a SEHR database there are three basic, but different ways
1) using the ORM layer Hibernate (native w/o JPA)
2) accessing the database by using driver connections and 'java.sql' methods
3) using JNDI and/or pooled connections

In any case the database must be assigned. This object can be used either in SEHR server environments where the connection parameters are available by the SEHRConfiguration configuration object or in a client environment by setting the parameters during object initialization or by using the parameterless constructor with some setter methods.

To use JNDI/pooled connections do

• init object using the propriate constructor or setters
• call initFBDS()
• use connect()to establish a connection

To initialize ORM do

• init instance using #SEHRDataSource(org.ifeth.sehr.core.lib.SEHRConfiguration) or
• SEHRDataSource() and then init(org.ifeth.sehr.core.lib.SEHRConfiguration)
• then assign a Hibernate ORM session as required...

To use JPA with or w/o Hibernate you probably do not need this class. The JPA does not need a 'hibernate.xml.conf' and all classes are defined by the 'persistence.xml' as well as the connection. The entities of SEHR are based on EJB 3.0 and JPA annotations so that these are usable also in JPA.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DBPORT
static java.lang.String	LC_CTYPE
static java.lang.String	XMLCONF

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	SEHRDataSource() Initiates a parameterless object instance for database connection.

Method Summary

Modifier and Type	Method and Description
void	close() Close the current firebird connection handle...
void	close(int idx) Close a given connection handle.
static void	close(SEHRDataSource fbds) Close connection of the given data source handle.
void	closeAll() Deprecated. use destroy()
static void	closeConnection(java.sql.Connection connection) Helper method to close a given SQL connection in other modules, nothing else.
void	closeFBDataSource() Deprecated. use close()
static void	closeFBDataSource(SEHRDataSource fbds) Deprecated. use close()
void	closeJPAEntityManager() Close the JPA (RESOURCE_LOCAL) instance for managing the entities.
static void	closeResultSet(java.sql.ResultSet rs)
static void	closeStatement(java.sql.Statement st)
void	configure(java.util.Properties p) Configure a native (FBDS) access to a firebird database.
java.sql.Connection	connect() Make a (re-)connection using the current object assuming all required parameters are already invoked.
java.sql.Connection	connectFBDataSource(SEHRDataSource fbds, java.lang.String host, java.lang.String port, java.lang.String database, java.lang.String dbuser, java.lang.String dbpw) Deprecated. Use getConnection()
int	countPooledConnections() Get the number of currently pooled and used connections by pooled datasource.
void	destroy() Close all registered pooled connections, close the current connection and close ORM if any.
java.sql.Connection	getConnection() Return a connection handle.
java.sql.Connection	getConnection(int idx) Get an already established connection from map by index.
int	getConnectionIndex() Retrieve current used or last registered connection id (its hashcode).
java.lang.String	getDBFile()
java.lang.String	getDBHost() For general usage: get host of db access
java.lang.String	getDBPass()
int	getDBPort()
java.lang.String	getDBUser()
org.firebirdsql.ds.FBConnectionPoolDataSource	getFBDS()
protected java.sql.DatabaseMetaData	getFBMetaData() Get metadata about the current database source.
protected java.sql.DatabaseMetaData	getFBMetaData(SEHRDataSource fbds) Get metadata object about the given database source.
java.util.List<java.lang.Object>	getGenerator() Show the generator id's of the initialized native DB access.
java.util.List<java.lang.Object>	getGenerator(java.lang.String genid) Show the value of the given generator of the initialized native DB access.
static SEHRDataSource	getInstance()
javax.persistence.EntityManager	getJPAEntityManager() Get (or create) instance for managing the entities.
javax.persistence.EntityManagerFactory	getJPAHibernateFactory()
java.lang.String	getRandomID() Get a random digest ID.
SEHRConfiguration	getSEHRCfg()
int	initConnection() Init a new connection from pool and store it locally in a map.
org.firebirdsql.ds.FBConnectionPoolDataSource	initFBDS() Init a pooled data source to be used also by ORM/Hibernate/JPA.
void	initialize(java.util.Properties p) Initiates an object instance on a SEHR host using given properties.
void	initialize(SEHRConfiguration cfg) Initiates an object instance on a SEHR host using the SEHR configuration object.
void	initialize(java.lang.String host, int port, java.lang.String database, java.lang.String dblogin, java.lang.String dbpw, java.lang.String ORMFile) Deprecated. Use either #SEHRDataSource(SEHRConfiguration) or #SEHRDataSource(Properties)
void	initialize(java.lang.String host, java.lang.String port, java.lang.String database, java.lang.String dblogin, java.lang.String dbpw) Deprecated. Use either #SEHRDataSource(SEHRConfiguration) or #SEHRDataSource(Properties)
void	initialize(java.lang.String host, java.lang.String sport, java.lang.String database, java.lang.String dblogin, java.lang.String dbpw, java.lang.String ORMFile) Deprecated. Use either #SEHRDataSource(SEHRConfiguration) or #SEHRDataSource(Properties)
javax.persistence.EntityManagerFactory	initJPAResourceLocal()
boolean	isConnection() Check status of current connection.
boolean	isFBPooledDS() Get status if a pooled datasource is present.
boolean	isJPAResourceLocal(javax.persistence.EntityManager em)
static org.jdom.Document	loadXMLFile(java.io.File file, DeEncrypter denc) Read a XML file object and prepare a document object (DOM)
static org.jdom.Document	loadXMLFile(java.lang.String file) Read a XML file and prepare a document object (DOM)
javax.sql.PooledConnection	pooledConnection() Create a pooled connection for current firebird database source object.
static java.lang.Object	readBLOBField(SEHRConfiguration sehrcfg, java.lang.String table, java.lang.String field, java.lang.String pkfield, int recid) Deprecated. We trust only our datasource instance ...
static java.lang.Object	readBLOBField(SEHRDataSource ds, java.lang.String table, java.lang.String field, java.lang.String pkfield, int recid) Retrieve a BLOB field...
static byte[]	readBytesFromFile(java.io.File file) Method to get contents of a file as bytes.
static java.lang.Object	readDataObjectFile(java.io.File file, DeEncrypter cipher) Reads/Loads an object from file.
void	setCfg(SEHRConfiguration cfg) Set cfg object to use for datasource initialization.
void	setDataBase(java.lang.String dbHost, int dbPort, java.lang.String dbFile, java.lang.String dbUser, java.lang.String dbUserPass) For client usage: set database including host, port, path_to_db_file and login.
void	setDBFile(java.lang.String sFBDataBase)
void	setDBHost(java.lang.String host) For client usage: set port of firebird engine
void	setDBLogin(java.lang.String sFBLogin) Deprecated. use setDBUser(user)
void	setDBPass(java.lang.String pw)
void	setDBPort(int port) For client usage: set port of firebird engine
void	setDBPw(java.lang.String pw) For client usage: set database login password
void	setDBUser(java.lang.String user) For client usage: set database login name
void	setFBDS(org.firebirdsql.ds.FBConnectionPoolDataSource fbpds)
void	setJPAHibernateFactory(javax.persistence.EntityManagerFactory emf)
java.lang.String	showProcedures()
static java.lang.String	showProcedures(SEHRDataSource fbds) Show the procedures of the initialized native DB access.
java.lang.String	showTables() Show the tables of the assigned DB.
java.lang.String	showTables(boolean showfields) Show the tables of the initialized native DB access.
static java.lang.String	showTables(SEHRDataSource fbds) Show the tables of the initialized native DB access.
static java.lang.String	showTables(SEHRDataSource fbds, boolean showfields) Show the tables of the initialized native DB access.
java.lang.String	toString()
static boolean	writeBLOBRecord(SEHRConfiguration sehrcfg, java.lang.String table, java.lang.String field, java.lang.String pkfield, long recid, java.lang.Object o) Deprecated. Code cleaning... use datasource directly...
static boolean	writeBLOBRecord(SEHRDataSource ds, java.lang.String table, java.lang.String field, java.lang.String pkfield, long recid, java.lang.Object o) Writes a BLOB field to the database table.
static boolean	writeDataObjectFile(java.io.File file, java.lang.Object object, DeEncrypter cipher) Writes an object to file
static boolean	writeStreamToFile(java.io.InputStream is, java.lang.String filelocation)
static boolean	writeXMLFile(java.io.OutputStream out, org.jdom.Document doc) Writes a DOM (XML parsed) document to given output stream (System.out, File or URL)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DBPORT

public static int DBPORT

XMLCONF

public static java.lang.String XMLCONF

LC_CTYPE

public static java.lang.String LC_CTYPE

Constructor Detail

SEHRDataSource

protected SEHRDataSource()

Initiates a parameterless object instance for database connection.

To access the IntraSEC db use either #SEHRDataSource(Properties) or initialize a connection step by step (e.g. on clients) by using the following setter methods followed by initFBDS():
SEHRDataSource
or
setDBFile(String), setDBHost(String), setDBPort(int), setDBLogin(String), setDBPw(String).

For Hibernate with EJB3 use the 'JTA' configuration of Glassfish.

See Also:

Firebird on Sourceforge

Method Detail

getInstance

public static SEHRDataSource getInstance()

initialize

public void initialize(java.util.Properties p)

Initiates an object instance on a SEHR host using given properties. (recommended constructor for first initialization).

Notice: If 'jndi.*' keys are defined the firebird datasource will be stored as a pooled connection as well as Hibernate will use this datasource for the session (Hibernate will be initialized if any 'ORM.*' key is present).

Parameters:

p - This Properties object holds all required data to connect

See Also:

Firebird on Sourceforge, SEHRDataSource Specification

initialize

public void initialize(SEHRConfiguration cfg)

Initiates an object instance on a SEHR host using the SEHR configuration object.

Important security note:
Due to security reasons the username and password to access any SEHR database (IntraSEC and IntraDOC etc.) are not stored by the configuration object. So you must know them and set the username and password using the corresponding setters. To use this component on the server site use JNDI and retrieve the object FBConnectionPoolDataSource to get a ready for use access.

Parameters:

cfg - The SEHRConfiguration object tracks all required data to connect

initialize

public void initialize(java.lang.String host,
                       int port,
                       java.lang.String database,
                       java.lang.String dblogin,
                       java.lang.String dbpw,
                       java.lang.String ORMFile)

Deprecated. Use either #SEHRDataSource(SEHRConfiguration) or #SEHRDataSource(Properties)

Initiates an object instance with individual connection parameters.

This constructor is defined for clients, where a local file access to a SEHR configuration SEHRConfiguration or ORM configuration is not available. There are two ways for the client to handle the parameters for a connection:

• by written papers and a local configuration using parameters (this method)
• by the recommended SOAP, SEHR socket or JNDI request to get a ready for use pooled firebird data source object and using the method setFBDS(org.firebirdsql.ds.FBConnectionPoolDataSource)

For a db connection use connect().

Parameters:

host -

port -

database -

dblogin -

dbpw -

ORMFile - Configuration file for Hibernate (path + filename)

initialize

public void initialize(java.lang.String host,
                       java.lang.String sport,
                       java.lang.String database,
                       java.lang.String dblogin,
                       java.lang.String dbpw,
                       java.lang.String ORMFile)

Deprecated. Use either #SEHRDataSource(SEHRConfiguration) or #SEHRDataSource(Properties)

Initiates an object instance with individual connection parameters

Parameters:

host -

sport -

database -

dblogin -

dbpw -

ORMFile - Configuration file for Hibernate (path + filename)

See Also:

SEHRDataSource#SEHRDataSource(Properties)

initialize

public void initialize(java.lang.String host,
                       java.lang.String port,
                       java.lang.String database,
                       java.lang.String dblogin,
                       java.lang.String dbpw)

Deprecated. Use either #SEHRDataSource(SEHRConfiguration) or #SEHRDataSource(Properties)

Initiates an object instance with individual connection parameters

To connect/open use connect()

Parameters:

host -

port -

database -

dblogin -

dbpw -

configure

public void configure(java.util.Properties p)

Configure a native (FBDS) access to a firebird database.

Parameters:

p -

initFBDS

public org.firebirdsql.ds.FBConnectionPoolDataSource initFBDS()

Init a pooled data source to be used also by ORM/Hibernate/JPA.

By JDBC convention apps should use this kind of data source only. The ds object canbe stored by JNDI for a common reusage through the app.

Returns:

See Also:

Firebird on Sourceforge

initJPAResourceLocal

public javax.persistence.EntityManagerFactory initJPAResourceLocal()

connectFBDataSource

public java.sql.Connection connectFBDataSource(SEHRDataSource fbds,
                                               java.lang.String host,
                                               java.lang.String port,
                                               java.lang.String database,
                                               java.lang.String dbuser,
                                               java.lang.String dbpw)
                                        throws java.sql.SQLException

Deprecated. Use getConnection()

Make a connection for a given firebird database ...

Parameters:

fbds -

host -

port -

database -

dbuser -

dbpw -

Returns:

Throws:

java.sql.SQLException

connect

public java.sql.Connection connect()

Make a (re-)connection using the current object assuming all required parameters are already invoked. The map of connections will be cleared!

Returns:

(Connection) Object to handle connections or 'null'

See Also:

Firebird on Sourceforge

closeFBDataSource

public void closeFBDataSource()
                       throws java.sql.SQLException

Deprecated. use close()

Close the firebird datasource handle of the current object.

Throws:

java.sql.SQLException

closeFBDataSource

public static void closeFBDataSource(SEHRDataSource fbds)
                              throws java.sql.SQLException

Deprecated. use close()

Parameters:

fbds -

Throws:

java.sql.SQLException

close

public void close()

Close the current firebird connection handle...

close

public void close(int idx)
           throws java.sql.SQLException

Close a given connection handle.

Parameters:

idx - - the hash code of a connection

Throws:

java.sql.SQLException

close

public static void close(SEHRDataSource fbds)
                  throws java.sql.SQLException

Close connection of the given data source handle.

Parameters:

fbds - FBDataSource object @deprecated use close()

Throws:

java.sql.SQLException

closeResultSet

public static void closeResultSet(java.sql.ResultSet rs)

closeStatement

public static void closeStatement(java.sql.Statement st)

closeConnection

public static void closeConnection(java.sql.Connection connection)

Helper method to close a given SQL connection in other modules, nothing else.

Parameters:

connection -

pooledConnection

public javax.sql.PooledConnection pooledConnection()
                                            throws java.sql.SQLException

Create a pooled connection for current firebird database source object.

Note: Use closeConnection(int conidx)! Pooled connections do have large benefits in c/s connections but there are also some traps. One of these traps is the number and the maximum of pooled concurrent connections. To get an overview of the number of used connections use countPooledConnections().
To close all connections at once use closeAll()
To get a specific and already established connection use getConnection(int idx)

Returns:

Throws:

java.sql.SQLException

See Also:

Firebird on Sourceforge

initConnection

public int initConnection()

Init a new connection from pool and store it locally in a map.

Returns:

connection id (hash)

getConnection

public java.sql.Connection getConnection(int idx)

Get an already established connection from map by index.

To keep the integrity of prepared statements the pool is indexed. So you may init a connection, assign statements to it and use exactly the indexed connection to get your statementents back.

Parameters:

idx -

Returns:

getConnectionIndex

public int getConnectionIndex()

Retrieve current used or last registered connection id (its hashcode). To reuse a DB connection handle use the method getConnection(int) with the hashcode as parameter. Another use case is to close a DB connection using close(int) to return the handle back into the pool.

Returns:

Current connection id (hash).

closeAll

public void closeAll()

Deprecated. use destroy()

Close all registered simple connections including the current connection

destroy

public void destroy()

Close all registered pooled connections, close the current connection and close ORM if any. Important note: Since we are using Jaybird 2.2. handle this with care on JPA managed modules (EJB's).

countPooledConnections

public int countPooledConnections()

Get the number of currently pooled and used connections by pooled datasource.

Note: Only available on pooled connections ...

Returns:

(int) n-connections or '-1'

isFBPooledDS

public boolean isFBPooledDS()

Get status if a pooled datasource is present.

Returns:

status true if a pooled connection is in use

isConnection

public boolean isConnection()

Check status of current connection.

Returns:

getConnection

public java.sql.Connection getConnection()

Return a connection handle.

If there is no connection this method tries to establish a native JDBC connection by using the settings.

Returns:

Connection

getRandomID

public java.lang.String getRandomID()

Get a random digest ID.

Returns:

MsgDig - The digest

setCfg

public void setCfg(SEHRConfiguration cfg)

Set cfg object to use for datasource initialization.

Parameters:

cfg -

setDBPort

public void setDBPort(int port)

For client usage: set port of firebird engine

Parameters:

port - The port of the database (if <1024 port it is set to 3050)

getDBHost

public java.lang.String getDBHost()

For general usage: get host of db access

Returns:

ip_as_String

setDBHost

public void setDBHost(java.lang.String host)

For client usage: set port of firebird engine

Parameters:

host - Use IP or DNS to connect

setDataBase

public void setDataBase(java.lang.String dbHost,
                        int dbPort,
                        java.lang.String dbFile,
                        java.lang.String dbUser,
                        java.lang.String dbUserPass)

For client usage: set database including host, port, path_to_db_file and login.

Parameters:

dbHost -

dbPort -

dbFile -

dbUser -

dbUserPass -

setDBUser

public void setDBUser(java.lang.String user)

For client usage: set database login name

setDBPw

public void setDBPw(java.lang.String pw)

For client usage: set database login password

setFBDS

public void setFBDS(org.firebirdsql.ds.FBConnectionPoolDataSource fbpds)

getFBDS

public org.firebirdsql.ds.FBConnectionPoolDataSource getFBDS()

getDBPort

public int getDBPort()

Returns:

the sFBPort

getDBFile

public java.lang.String getDBFile()

Returns:

the sFBDataBase

setDBFile

public void setDBFile(java.lang.String sFBDataBase)

Parameters:

sFBDataBase - the sFBDataBase to set

getDBUser

public java.lang.String getDBUser()

Returns:

the sFBLogin

setDBLogin

public void setDBLogin(java.lang.String sFBLogin)

Deprecated. use setDBUser(user)

Parameters:

sFBLogin - the sFBLogin to set

getDBPass

public java.lang.String getDBPass()

Returns:

the sFBPw

setDBPass

public void setDBPass(java.lang.String pw)

Parameters:

pw - the password to the DB to set

setJPAHibernateFactory

public void setJPAHibernateFactory(javax.persistence.EntityManagerFactory emf)

getJPAHibernateFactory

public javax.persistence.EntityManagerFactory getJPAHibernateFactory()

getJPAEntityManager

public javax.persistence.EntityManager getJPAEntityManager()

Get (or create) instance for managing the entities.

Returns:

em - The EntitiyManager instance.

closeJPAEntityManager

public void closeJPAEntityManager()

Close the JPA (RESOURCE_LOCAL) instance for managing the entities.

Note:Do not close JTA container managed instances!

isJPAResourceLocal

public boolean isJPAResourceLocal(javax.persistence.EntityManager em)

readBytesFromFile

public static byte[] readBytesFromFile(java.io.File file)
                                throws java.io.IOException

Method to get contents of a file as bytes.

This method is used to prepare an object to store as a BLOB

Parameters:

file -

Returns:

Throws:

java.io.IOException

readDataObjectFile

public static java.lang.Object readDataObjectFile(java.io.File file,
                                                  DeEncrypter cipher)

Reads/Loads an object from file.

Parameters:

file -

cipher -

Returns:

Object

writeStreamToFile

public static boolean writeStreamToFile(java.io.InputStream is,
                                        java.lang.String filelocation)

writeDataObjectFile

public static boolean writeDataObjectFile(java.io.File file,
                                          java.lang.Object object,
                                          DeEncrypter cipher)

Writes an object to file

Parameters:

file -

object -

cipher -

Returns:

boolean

loadXMLFile

public static org.jdom.Document loadXMLFile(java.lang.String file)

Read a XML file and prepare a document object (DOM)

Parameters:

file -

Returns:

Document

loadXMLFile

public static org.jdom.Document loadXMLFile(java.io.File file,
                                            DeEncrypter denc)

Read a XML file object and prepare a document object (DOM)

Parameters:

file -

denc - 'null' if the file is not crypted

Returns:

Document

writeXMLFile

public static boolean writeXMLFile(java.io.OutputStream out,
                                   org.jdom.Document doc)

Writes a DOM (XML parsed) document to given output stream (System.out, File or URL)

Parameters:

out -

doc -

Returns:

boolean

readBLOBField

public static java.lang.Object readBLOBField(SEHRConfiguration sehrcfg,
                                             java.lang.String table,
                                             java.lang.String field,
                                             java.lang.String pkfield,
                                             int recid)

Deprecated. We trust only our datasource instance ...

readBLOBField

public static java.lang.Object readBLOBField(SEHRDataSource ds,
                                             java.lang.String table,
                                             java.lang.String field,
                                             java.lang.String pkfield,
                                             int recid)

Retrieve a BLOB field...

Parameters:

ds -

table -

field -

pkfield -

recid -

Returns:

Object

getSEHRCfg

public SEHRConfiguration getSEHRCfg()

writeBLOBRecord

public static boolean writeBLOBRecord(SEHRConfiguration sehrcfg,
                                      java.lang.String table,
                                      java.lang.String field,
                                      java.lang.String pkfield,
                                      long recid,
                                      java.lang.Object o)

Deprecated. Code cleaning... use datasource directly...

writeBLOBRecord

public static boolean writeBLOBRecord(SEHRDataSource ds,
                                      java.lang.String table,
                                      java.lang.String field,
                                      java.lang.String pkfield,
                                      long recid,
                                      java.lang.Object o)

Writes a BLOB field to the database table.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

getFBMetaData

protected java.sql.DatabaseMetaData getFBMetaData()

Get metadata about the current database source. A native access to the DB required - JPA is not supported!

Returns:

databaseMetaData - 'null' if not successfull

getFBMetaData

protected java.sql.DatabaseMetaData getFBMetaData(SEHRDataSource fbds)

Get metadata object about the given database source.

Parameters:

fbds - Firebird datasource object with a native access configured!

Returns:

fbmd 'null' if no successfull Firebird metadata obejct

showTables

public java.lang.String showTables()

Show the tables of the assigned DB. The native access to the DB required - JPA is not supported!

Returns:

dump - A plain dump of tables; 'null' if not successfull

showTables

public java.lang.String showTables(boolean showfields)

Show the tables of the initialized native DB access. The native access to the DB required - JPA is not supported!

Returns:

dump - A plain dump of tables; 'null' if not successfull

showTables

public static java.lang.String showTables(SEHRDataSource fbds)

Show the tables of the initialized native DB access. The native access to the DB required - JPA is not supported!

Returns:

dump - A plain dump of tables; 'null' if not successfull

showTables

public static java.lang.String showTables(SEHRDataSource fbds,
                                          boolean showfields)

Show the tables of the initialized native DB access. The native access to the DB required - JPA is not supported!

Parameters:

fbds -

showfields -

Returns:

dump - A plain dump of tables; 'null' if not successfull

showProcedures

public java.lang.String showProcedures()

showProcedures

public static java.lang.String showProcedures(SEHRDataSource fbds)

Show the procedures of the initialized native DB access. The native access to the DB required - JPA is not supported!

Parameters:

fbds -

Returns:

dump - A plain dump of stored procs; 'null' if not successfull

getGenerator

public java.util.List<java.lang.Object> getGenerator()

Show the generator id's of the initialized native DB access. The native access to the DB required - JPA is not supported!

Returns:

dump - A plain dump of the current id's; 'null' if not successfull

getGenerator

public java.util.List<java.lang.Object> getGenerator(java.lang.String genid)

Show the value of the given generator of the initialized native DB access. The native access to the DB required - JPA is not supported!

Parameters:

genid -

Returns:

value - The value of the given generator name