org.garret.consus
Interface ConsusConnection

All Superinterfaces:
java.sql.Connection, PersistentObjectStorage

public interface ConsusConnection
extends java.sql.Connection, PersistentObjectStorage

A connection (session) with a specific database. Within the context of a Connection, SQL statements are executed and results are returned.

A Connection's database is able to provide information describing its tables, supported SQL grammar, its stored procedures, the capabilities of this connection and so on. This information is obtained with the getMetaData method.

Note: By default the Connection automatically commits changes after executing each statement. If auto commit has been disabled, an explicit commit must be done or the database changes will not be saved.

See Also:
Statement, ResultSet, DatabaseMetaData

Field Summary
 
Fields inherited from interface java.sql.Connection
TRANSACTION_NONE, TRANSACTION_READ_COMMITTED, TRANSACTION_READ_UNCOMMITTED, TRANSACTION_REPEATABLE_READ, TRANSACTION_SERIALIZABLE
 
Method Summary
 void backup(java.io.OutputStream stream)
          Online backup of the database.
 void checkInTable(java.lang.String tableName, java.sql.Connection conxn)
          Synchronize the replica and master table.
 void checkOutTable(java.lang.String tableName, java.sql.Connection conxn)
          Update replica table by transfering all changes from the master table.
 void commitSubtransaction()
          Commit nested subtransaction.
 java.sql.Blob createBlob(long length, java.io.InputStream in)
          Create BLOB
 java.sql.Clob createClob(long length, java.io.Reader in)
          Create CLOB
 java.sql.Clob createClob(java.lang.String str)
          Create CLOB
 void createObjectCache()
          Allocate object cache (instance manager) if not yet allocated.
 StringIndex createStringIndex()
          Create a new String index in the database.
 void doGarbageCollection()
          Explicitly initiate new garbage collection (if not yet started)
 void enableTracing(boolean enabled)
          Switch tracing on/off.
 java.lang.Object get(java.sql.Ref ref)
          Get object by it's OID
 java.lang.String getMasterFieldName()
          Get the name of the field containing the referenence to the master object instance on the server (used for table replication) if null then an existing primary key will be used instead.
 boolean getThreadAutoCommit()
          Gets the current auto-commit state.
 java.lang.String getTimestampFieldName()
          Get the name of the timestamp field used for data replication.
 long getUsedSize()
          Get the size used by objects in the database
 java.sql.Ref insert(java.lang.Object obj)
          Insert the specified object into the database.
 void lock()
          Lock the database in exclusive mode.
 void remove(java.sql.Ref ref)
          Remove object with specifed OID
 void setGCRoots(java.lang.String[] tableNames)
          Specify root tables for garbage collection.
 void setGCThreshold(long threshold)
          Specify the size of allocated objects after which GC should be initiated.
 void setMasterFieldName(java.lang.String name)
          Set the name of the field containing the refenence to the master object instance on the server (used for table replication).
 void setThreadAutoCommit(boolean autoCommit)
          Set autocommit mode only for the current thread.
 void setTimestampFieldName(java.lang.String name)
          Set the name of the timestamp field used for data replication.
 void update(java.sql.Ref ref, java.lang.Object obj)
          Update the object in the table.
 
Methods inherited from interface java.sql.Connection
clearWarnings, close, commit, createStatement, createStatement, createStatement, getAutoCommit, getCatalog, getHoldability, getMetaData, getTransactionIsolation, getTypeMap, getWarnings, isClosed, isReadOnly, nativeSQL, prepareCall, prepareCall, prepareCall, prepareStatement, prepareStatement, prepareStatement, prepareStatement, prepareStatement, prepareStatement, releaseSavepoint, rollback, rollback, setAutoCommit, setCatalog, setHoldability, setReadOnly, setSavepoint, setSavepoint, setTransactionIsolation, setTypeMap
 
Methods inherited from interface org.garret.consus.PersistentObjectStorage
becomeObject, clearComponents, clearObjectCache, deleteObject, fetchObject, getObjectByOid, getObjectCacheSize, getTableIterator, isInitialized, loadComponents, loadObject, open, storeObject, updateObject
 

Method Detail

backup

void backup(java.io.OutputStream stream)
            throws java.sql.SQLException,
                   java.io.IOException
Online backup of the database.

Parameters:
stream - to were backup is performed
Throws:
java.sql.SQLException
java.io.IOException

checkInTable

void checkInTable(java.lang.String tableName,
                  java.sql.Connection conxn)
                  throws java.sql.SQLException
Synchronize the replica and master table. This method will first transfer to the client all the records that were changed on the server from the moment of the check out. If some of these records was also changed by the client, then a merge conflict is detected and MergeConflictException is thrown. The exception object is given the value of the key of the record that caused the conflict. Then Consus will transfer all the records which were changed by the client to the master table, assigning them the value of timestamp greater than of any other record in the master table. It is possible to perform check-ins several times, synchronizing content of the master and replica tables.

Parameters:
tableName - name of the table to check-in
conxn - database connection
Throws:
MergeConflictException
java.sql.SQLException

checkOutTable

void checkOutTable(java.lang.String tableName,
                   java.sql.Connection conxn)
                   throws java.sql.SQLException
Update replica table by transfering all changes from the master table. It is not necessary for master and replica table to be exactly the same. Replica table can contain a subset of master table columns. But they both should have recordTimestamp and optionally masterOID fields. Then the application can close connection with the server and work normally with replica table, autonomously.

Parameters:
tableName - name of the table to check-out
conxn - database connection
Throws:
java.sql.SQLException

commitSubtransaction

void commitSubtransaction()
                          throws java.sql.SQLException
Commit nested subtransaction. Exterior transaction will be committed when all nested subtransaction are successfully committed.

Throws:
java.sql.SQLException

createBlob

java.sql.Blob createBlob(long length,
                         java.io.InputStream in)
Create BLOB

Parameters:
length - size of stored data
in - input stream to provide BLOB data
Returns:
ConsusBlob

createClob

java.sql.Clob createClob(long length,
                         java.io.Reader in)
Create CLOB

Parameters:
length - number of characters
in - reader to provide CLOB data
Returns:
ConsusClob

createClob

java.sql.Clob createClob(java.lang.String str)
Create CLOB

Parameters:
str - - string which will be stored as CLOB body
Returns:
ConsusClob

createObjectCache

void createObjectCache()
Allocate object cache (instance manager) if not yet allocated. With object caching enabled for each OID, there is exactly one instance of the object in memory. The object cache is implicitly created when the PersistentObjectStorage interface is used.


createStringIndex

StringIndex createStringIndex()
                              throws java.sql.SQLException
Create a new String index in the database.

Returns:
persistent object representing string index
Throws:
java.sql.SQLException

doGarbageCollection

void doGarbageCollection()
                         throws java.sql.SQLException
Explicitly initiate new garbage collection (if not yet started)

Throws:
java.sql.SQLException

enableTracing

void enableTracing(boolean enabled)
Switch tracing on/off.

Parameters:
enabled - - switch on tracing when true

get

java.lang.Object get(java.sql.Ref ref)
                     throws java.sql.SQLException
Get object by it's OID

Parameters:
ref - reference to the object
Returns:
reference to the fetched object
Throws:
java.sql.SQLException

getMasterFieldName

java.lang.String getMasterFieldName()
Get the name of the field containing the referenence to the master object instance on the server (used for table replication) if null then an existing primary key will be used instead.

Returns:
name of master field ("masterOID" by default)

getThreadAutoCommit

boolean getThreadAutoCommit()
                            throws java.sql.SQLException
Gets the current auto-commit state.

Returns:
the current state of the auto-commit mode
Throws:
java.sql.SQLException - if a database access error occurs
See Also:
Connection.setAutoCommit(boolean)

getTimestampFieldName

java.lang.String getTimestampFieldName()
Get the name of the timestamp field used for data replication.

Returns:
timestamp field name (recordTimestamp" by default)

getUsedSize

long getUsedSize()
                 throws java.sql.SQLException
Get the size used by objects in the database

Returns:
total size of all the objects in the database (bytes)
Throws:
java.sql.SQLException

insert

java.sql.Ref insert(java.lang.Object obj)
                    throws java.sql.SQLException
Insert the specified object into the database. The table in which object will be inserted is determined by the object class.

Parameters:
obj - Java object to be inserted
Returns:
reference to the cerated object
Throws:
java.sql.SQLException

lock

void lock()
          throws java.lang.Exception
Lock the database in exclusive mode. Lock will be released by transaction commit/rollback

Specified by:
lock in interface PersistentObjectStorage
Throws:
java.lang.Exception

remove

void remove(java.sql.Ref ref)
            throws java.sql.SQLException
Remove object with specifed OID

Parameters:
ref - reference to the removed object
Throws:
java.sql.SQLException

setGCRoots

void setGCRoots(java.lang.String[] tableNames)
                throws java.sql.SQLException
Specify root tables for garbage collection. All tables should already exist. All records (objects) for these tables will be marked as accessible. Then all other objects in the database, recursively referenced from these objects, will be marked. At the final stage, all unmarked objects will be removed.

Parameters:
tableNames - array with table names
Throws:
java.sql.SQLException

setGCThreshold

void setGCThreshold(long threshold)
                    throws java.sql.SQLException
Specify the size of allocated objects after which GC should be initiated.

Parameters:
threshold - difference between allocated and deallocated object since last GC after which a new GC is initiated. By default it is set to Long.MAX_VALUE so GC is disabled.
Throws:
java.sql.SQLException

setMasterFieldName

void setMasterFieldName(java.lang.String name)
Set the name of the field containing the refenence to the master object instance on the server (used for table replication).

Parameters:
name - name of the field, if null then an existing primary key will be used instead

setThreadAutoCommit

void setThreadAutoCommit(boolean autoCommit)
                         throws java.sql.SQLException
Set autocommit mode only for the current thread. Transaction commit modes of other threads are not changed. Transactions will be automatically committed after each statement when either the global auto-commit mode is set or the current thread is in the auto-commit state.

Throws:
java.sql.SQLException

setTimestampFieldName

void setTimestampFieldName(java.lang.String name)
Set the name of the timestamp field used for data replication.

Parameters:
name - name of the timestamp field

update

void update(java.sql.Ref ref,
            java.lang.Object obj)
            throws java.sql.SQLException
Update the object in the table.

Parameters:
ref - reference to the updated object
obj - object with new values
Throws:
java.sql.SQLException