org.oreodata.jdbcimpl
Class JDBCBackedRecordSet

java.lang.Object
  |
  +--java.rmi.server.RemoteObject
        |
        +--java.rmi.server.RemoteServer
              |
              +--java.rmi.server.UnicastRemoteObject
                    |
                    +--org.oreodata.AbstractDataSource
                          |
                          +--org.oreodata.jdbcimpl.JDBCBackedRecordSet

All Implemented Interfaces:

DataListener, java.util.EventListener, OreoDataSource, java.rmi.Remote, java.io.Serializable

Direct Known Subclasses:

JDBCTransactionalDataSource

public class JDBCBackedRecordSet

extends AbstractDataSource

A class that is essentially a facade in front of an external relational database. This is just one of various possible ways to implement this. This implementation allows for an in-memory cache of adjustable size. This container is probably fairly efficient for an app whose profile is that there are a lot of reads and relatively few writes to the external RDBMS. That is probably more the rule than the exception.

Here are the various PROPERTY parameters you can set in your datasources.xml. Note that only the first 2 are required. It is advisable to set MAX_CACHE_SIZE also, since memory caching of records has the potential to improve performance drastically under many (if not most) circumstances. The caching algorithm is actually quite simple-minded. The container caches in-memory the records that clients request. When the cache reaches a certain size (defined in MAX_CACHE_SIZE) the cache is wiped out and allowed to build up again. Also, the cache can be configured to have a maximum shelf-life via the CACHE_REFRESH_FREQUENCY parameter.

Parameter	Description	Default
JDBC_DRIVER_CLASS	The fully qualified classname of the JDBC driver you want to use.	Required parameter
JDBC_URL	The JDBC URL for the external RDBMS. Note that the ampersand in the URL must be written & or this won't be well-formed XML!	Required parameter
USER	The user ID for connecting to the external RDBMS.	Only required if the userID is not specified in the JDBC_URL parameter
PASSWORD	The password that corresponds to the USER for logging into the external RDBMS.	Necessary if the USER key is specified and a password is required
DEFAULT_RECORD	Indicates a default record type for this container. In particular, if an instance of this class is homogeneous, i.e. contains only one record type, it could be nice to specify this, since it allows you to write simply: get(lookupKey) instead of get("order_entry", lookupKey) since the first parameter is implicitly understood.	Unset
CREATE_TABLES_IF_NECESSARY	A list of record types for which to create tables if they do not already exist in the underlying RDBMS.	Unset
CHECK_CONCURRENT_UPDATE	Check whether there has been a concurrent update and throw an exception if this is the case.	No, don't check.
DOUBLE_QUOTE_LITERAL	Nasty little detail. Sets whether to use a double quote '' to specify a single quote character in SQL queries. Otherwise, it uses the backslash as the escape character.	"N" (i.e. \' is used)
MAX_CACHE_SIZE	Sets the maximum size of the in-memory cache. It might be worth experimenting with different values.	"0" (i.e. no cache)
CACHE_REFRESH_FREQUENCY	Sets the shelf life of data in the memory cache This value is irrelevant if MAX_CACHE_SIZE is unset. If you want to be able to bulk update the underlying database, and have the results reflected in your app without a restart, then you might want to set this. Maybe an hour (i.e. 3600) would be reasonable. If you never update your data from outside the app, you should leave this unset. Note also, that wipeCache() can be called to invalidate the cache.	Unset (i.e. infinite shelf life)
CONNECTION_POOL_MINIMUM	Sets the number of JDBC Connections to initiate at the begining	4
CONNECTION_POOL_MAXIMUM	Sets the maximum number of JDBC Connections to have in existence at the same time.	20

Author:

Jonathan Revusky, Alberto Molpeceres

See Also:

Serialized Form

Field Summary

protected boolean	checkConcurrentUpdate
protected java.lang.String	defaultRecordType
protected boolean	doubleQuoteLiteral
protected java.lang.String	driverClassName
protected java.lang.String	jdbcURL
protected int	maxCacheSize
protected int	maxConnections
protected int	minConnections
protected java.lang.String	password
protected ConnectionPool	pool
protected java.lang.String	userID

Fields inherited from class org.oreodata.AbstractDataSource

defaultCharEncoding, lastLogRotation, transactionCount

Fields inherited from class java.rmi.server.RemoteObject

ref

Constructor Summary

JDBCBackedRecordSet()

Method Summary

void	close() A method that should be called to free any resources associated with the data source.
Record	delete(Record rec) Delete a record.
Record	delete(java.lang.String type, java.lang.Object key) Delete a record.
Record	get(java.lang.String type, java.lang.Object key)
protected JDBCConnection	getConnection()
void	init(java.util.Properties props) A method that initializes a DataSource with a set of initialization properties.
Record	insert(Record rec) Adds a new record to the managed pool.
java.util.List	keys(java.lang.String type)
java.util.List	select(RecordFilter filter, RecordComparator comparator) Fetches a list of records matching filter.
protected java.lang.Object	uniqueKey(Record rec)
Record	update(Record oldRec, Record newRec) Replaces an existing version of a record with a new updated version.
void	wipeCache() If this data source is backed by some external mechanism, like an RDBMS, wipes the in-memory cache, if one is being maintained.

Methods inherited from class org.oreodata.AbstractDataSource

addDataListener, fireDataEvent, fireEvents, freeze, freeze, get, getName, handleEvent, keys, lookup, markStale, normalizeKey, reload, reload, removeDataListener, select, setFireEvents, setUseXML, useXML, writeElement, writeSnapshot

Methods inherited from class java.rmi.server.UnicastRemoteObject

clone, exportObject, exportObject, exportObject, unexportObject

Methods inherited from class java.rmi.server.RemoteServer

getClientHost, getLog, setLog

Methods inherited from class java.rmi.server.RemoteObject

equals, getRef, hashCode, toString, toStub

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

maxCacheSize

protected int maxCacheSize

minConnections

protected int minConnections

maxConnections

protected int maxConnections

pool

protected ConnectionPool pool

userID

protected java.lang.String userID

password

protected java.lang.String password

checkConcurrentUpdate

protected boolean checkConcurrentUpdate

driverClassName

protected java.lang.String driverClassName

jdbcURL

protected java.lang.String jdbcURL

defaultRecordType

protected java.lang.String defaultRecordType

doubleQuoteLiteral

protected boolean doubleQuoteLiteral

Constructor Detail

JDBCBackedRecordSet

public JDBCBackedRecordSet()
                    throws java.io.IOException

Method Detail

init

public void init(java.util.Properties props)
          throws java.io.IOException

Description copied from interface: OreoDataSource

A method that initializes a DataSource with a set of initialization properties. This is called internally within Oreo and should not be called by application code. As an implementor, you should make sure that this method is only called once, for example, throw a RuntimeException if an attempt is made to call this on a DataSource a second time.

Specified by:

init in interface OreoDataSource

Overrides:

init in class AbstractDataSource

java.io.IOException

delete

public Record delete(Record rec)
              throws java.io.IOException

Description copied from interface: OreoDataSource

Delete a record.

Specified by:

delete in interface OreoDataSource

Overrides:

delete in class AbstractDataSource

Parameters:

rec - the record to delete.

Returns:

the deleted Record of the given type, with the given lookup key.

java.io.IOException

delete

public Record delete(java.lang.String type,
                     java.lang.Object key)
              throws java.io.IOException

Description copied from interface: OreoDataSource

Delete a record.

Specified by:

delete in interface OreoDataSource

Overrides:

delete in class AbstractDataSource

Parameters:

type - the type of the record, if this is null, then any type will do.

key - the primary key of the record to delete.

Returns:

the deleted Record of the given type, with the given lookup key.

java.io.IOException

insert

public Record insert(Record rec)
              throws java.io.IOException

Description copied from interface: OreoDataSource

Adds a new record to the managed pool.

Specified by:

insert in interface OreoDataSource

Overrides:

insert in class AbstractDataSource

Parameters:

rec - the record to add

Returns:

the added record (frozen).

Throws:

java.io.IOException - if the record cannot be initialized (i.e. has missing fields or invalid field values, etc.), or in case of a low-level error.

update

public Record update(Record oldRec,
                     Record newRec)
              throws java.io.IOException

Description copied from interface: OreoDataSource

Replaces an existing version of a record with a new updated version. Some implementations may use the oldRec parameter to guarantee that there are no concurrency issues. In such case, it would throw a ConcurrentModificationException

Specified by:

update in interface OreoDataSource

Overrides:

update in class AbstractDataSource

Parameters:

oldRec - the record to replace.

newRec - the new record.

Returns:

the updated record (frozen).

Throws:

java.io.IOException - thrown in case of any other database or communication error.

keys

public java.util.List keys(java.lang.String type)
                    throws java.io.IOException

Specified by:

keys in interface OreoDataSource

Overrides:

keys in class AbstractDataSource

Parameters:

type - the record type we are interested, under some circumstances, this may be null.

Returns:

a list of all valid lookup keys that correspond to a given record type.

java.io.IOException

get

public Record get(java.lang.String type,
                  java.lang.Object key)
           throws java.io.IOException

Parameters:

type - the type of the record, if this is null, then any type will do.

key - the lookup key

Returns:

a Record of the given type, with the given lookup key.

java.io.IOException

wipeCache

public void wipeCache()

Description copied from interface: OreoDataSource

If this data source is backed by some external mechanism, like an RDBMS, wipes the in-memory cache, if one is being maintained. Otherwise, it does nothing.

Specified by:

wipeCache in interface OreoDataSource

Overrides:

wipeCache in class AbstractDataSource

select

public java.util.List select(RecordFilter filter,
                             RecordComparator comparator)
                      throws java.io.IOException

Description copied from interface: OreoDataSource

Fetches a list of records matching filter. If filter is null, returns all the records in the container. If the comparator is null, no sorting is carried out on the resulting list.

Specified by:

select in interface OreoDataSource

Overrides:

select in class AbstractDataSource

Parameters:

filter - the record filter, or null.

comparator - defines an ordering for the records.

Returns:

a List of all the records that are an instance of a given class. If no records match the filter, an empty List.

java.io.IOException

getConnection

protected JDBCConnection getConnection()

uniqueKey

protected java.lang.Object uniqueKey(Record rec)
                              throws java.io.IOException

Returns:

a unique primary key for a record.

java.io.IOException

close

public void close()
           throws java.io.IOException

Description copied from interface: OreoDataSource

A method that should be called to free any resources associated with the data source. Note that no other methods should be called on this object after this one. (In many implementations, this method will likely do nothing.)

Specified by:

close in interface OreoDataSource

Overrides:

close in class AbstractDataSource

java.io.IOException