| java.lang.Object
 simpleorm.properties.SPropertyMap
simpleorm.core.SConnection
All known Subclasses: EJB.SConnectionEJB,
| SConnection | | public class SConnection extends simpleorm.properties.SPropertyMap implements SConstants(Code) | | Links JDBC Connections to SimpleORM ones and handles transacitons
and flushing.
Associates existing JDBC transactions with the current thread so that
they can be used by other SimpleORM classes. Associating the
connection with threads avoids nasty threading problems that can
otherwise arrise.
SimpleORM takes no interest in how the JDBC connection was actually
obtained. It might be obtained directly using
DriverManager.getConnection(), connection pooling software such as
BitMechanic, or from a J2EE application server. SimpleORM therefor
does not restrict the environments in which it can be used.
But note that it is very important that transactions ONLY be COMMITED
by SimpleORM class, and NOT by raw JDBC calls.
All transactions must start with a
SConnection.begin and end with
either a
SConnection.commit or a
SConnection.rollback .
commit also
SConnection.flush es any outsanding changes.
(The complex AWT/Swing thread pattern is to have the main thread
sets up the forms, and then exit. A second AWT thread then does the
real work. In other words a single threaded application pointlessly
using two threads! SimpleORM works well with Swing but one needs to
use invokeAndWait() to set up the forms the AWT thread,
which is much cleaner anyway. See
simpleorm.examples.SwingTest for an example.)
This is specialized by SConnectionEJB for use within JTA transaction management.
|
| Inner Class :protected static class ConnectionGetter | |
| Constructor Summary | |
| protected | SConnection()
No direct creation of Connections. |
| Method Summary | |
| public static void | attach(SDataSource source, String connectionName)
Attaches a SimpleORM connection to the current thread based on conf.
Opens a JDBC connection.
connectionName is a simple name that can be used to identify this connection
in log traces etc. | | public static void | attach(Connection con, String connectionName, SDriver driver)
Attaches the already opened JDBC Connection con to
the current thread for future processing by SimpleORM. | | public static void | attach(Connection con, String connectionName)
Attaches the already opened JDBC Connection con to
the current thread for future processing by SimpleORM. | | public static void | begin()
Start a new transaction. | | public static void | commit()
Flush and purge the transaction cache to the database, and then
commit the transaction. | | static void | destroyAll()
Destroy all records in all tables so that they cannot be used
again and to encourage garbage collection. | | public static void | detachAndClose()
Closes the JDBC connection and then calls
detachWithoutClosing to detach the SimpleORM connection
from the current thread. | | public static void | detachWithoutClosing()
Detaches the SConnection from the current thread without
closing the JDBC connection so that it can be reattached to another thread. | | public static void | dropTableNoError(String table)
Utility routine for dropping tables. | | public static void | dumpCache()
Dumps out the entire cache of records for this connection. | | public static void | flush()
Flush all records of tables in this transaction to the database. | | public static void | flushAndPurge()
Flushes and Purges all record instances. | | static SConnection | getBegunConnection()
Gets current SConnection object for thread. | | public static Connection | getBegunDBConnection()
Asserts transaction Begin()ed and returns the JDBC connection.
Can be used to integrate direct JDBC calls with the SimpleORM
connection. | | public static Connection | getBegunJDBCConnection()
| | public static SConnection | getConnection()
Retrieve or create the SConnection associated with this "Context".
Normally this just means (indirectly) call getThreadedConnection
which finds the connection associated with this thread.
However, if EJB.SConnectionEJB is loaded, then this can be dispached
to getTransactionConnection instead. | | public SDataSource | getDataSource()
| | public static SDriver | getDriver()
Eg. | | Connection | getSequenceDBConnection()
Returns a secondary jdbc connection for generating sequence numbers, if required.
Creates a new one if necessary. | | static SConnection | getThreadedConnection()
| | public boolean | hasBegun()
Transaction is active between begin and commit. | | protected void | innerAttach(SDataSource source, String connectionName, Connection rawConnection, SDriver driver)
Allows SConnection to be subclassed. | | public boolean | isOpened()
If the JDBC connection has been attached and not closed. | | public boolean | mustCommitBeforeDetaching()
True iff commit must be called before the connection there are any (dirty) records that need to be
committed, regardless of whether they have been flushed. | | protected void | rawAttach()
| | protected void | rawDetach()
| | public static Object | rawQueryDB(String sql, String[] params, int nrColumns)
Convenience routine for doing single row queries using raw JDBC.
Be sure to flush the cache appropriately, or you will query
behind it.
if nrColumns == 0 (default) returns one result
column as a non array object, otherwise returns an array of
results. | | public static Object | rawQueryDB(String sql, String[] params)
| | public static Object | rawQueryDB(String sql, String param)
| | public static Object | rawQueryDB(String sql)
| | public static Object | rawQueryJDBC(String sql, String[] params, int nrColumns)
| | public static Object | rawQueryJDBC(String sql, String[] params)
| | public static Object | rawQueryJDBC(String sql, String param)
| | public static Object | rawQueryJDBC(String sql)
| | public static int | rawUpdateDB(String sql, Object[] params)
Convenience routine for doing bulk updates using raw JDBC.
Dangerous. | | public static int | rawUpdateDB(String sql, Object param)
| | public static int | rawUpdateDB(String sql)
| | public static int | rawUpdateJDBC(String sql, Object[] params)
| | public static int | rawUpdateJDBC(String sql, Object param)
| | public static int | rawUpdateJDBC(String sql)
| | public static void | rollback()
Purges the cache and rolls back the transaction. | | static String | shortToString()
Short connection/thread identifier for inclusion in log messages
to enable output from different threads to be separated. | | public String | toString()
| | public void | unsafeAttachToThread()
Re-attacheds a detached connection to the current thread. | | public static SConnection | unsafeDetachFromThread()
Enables the SimpleORM connection to be disassociated with the
current thread, and then associated with another thread.
Dangerous. |
| conNr | | long conNr(Code) | | Only to identify connection for toString()
|
| connectionGetter | | protected static ConnectionGetter connectionGetter(Code) | | |
| expensiveValidations | | static boolean expensiveValidations(Code) | | Enables Extra internal validations throughout SimpleORM. Cheap
tests are always enabled, but this can be used to turn on tests
that are expensive in times of trouble.
|
| hasBegun | | boolean hasBegun(Code) | | Transaction is active between begin and commit.
|
| name | | String name(Code) | | Provided by user to identify thread, eg. HTML session id. Keep
it short.
|
| transactionCache | | HashMap transactionCache(Code) | | Of all records retrieved. Both key and body are
SRecordInstances, which has redefined equals() and hashTable();
|
| uncommittedFlushes | | boolean uncommittedFlushes(Code) | | Data has been flushed but not committed in this transaction.
|
| updateList | | SArrayList updateList(Code) | | Ordered list of SRecordInstances to flush and purge.
|
| url | | String url(Code) | | The getMetaData() url. Saved here so that toString can dispaly
it even on a closed connection.
|
| SConnection | | protected SConnection()(Code) | | No direct creation of Connections.
|
| attach | | public static void attach(SDataSource source, String connectionName)(Code) | | Attaches a SimpleORM connection to the current thread based on conf.
Opens a JDBC connection.
connectionName is a simple name that can be used to identify this connection
in log traces etc. Eg. the session ID plus the user name. But keep it short
for logging.
The driver is usually determined automatically (if null) based on the conf,
but if it is overriden make sure to create a new driver instance for each connection.
See Also: SDataSource
See Also: for details. |
| attach | | public static void attach(Connection con, String connectionName, SDriver driver)(Code) | | Attaches the already opened JDBC Connection con to
the current thread for future processing by SimpleORM.
See Also: SDataSource
See Also: for details. |
| attach | | public static void attach(Connection con, String connectionName)(Code) | | Attaches the already opened JDBC Connection con to
the current thread for future processing by SimpleORM.
See Also: SDataSource
See Also: for details. |
| begin | | public static void begin()(Code) | | Start a new transaction. A JDBC connection must already be
attached to this thread, and must not be mid transaction.
|
| commit | | public static void commit()(Code) | | Flush and purge the transaction cache to the database, and then
commit the transaction. Note that this is the only way that a
transaction should be commited -- do not use JDBC commit
directly. Once commited, begin() must be used to
start the next transaction.
|
| destroyAll | | static void destroyAll()(Code) | | Destroy all records in all tables so that they cannot be used
again and to encourage garbage collection.
|
| detachAndClose | | public static void detachAndClose()(Code) | | Closes the JDBC connection and then calls
detachWithoutClosing to detach the SimpleORM connection
from the current thread. Should usually be put in a finally clause. No
error if already detached or closed so safe in finally clauses.
|
| detachWithoutClosing | | public static void detachWithoutClosing()(Code) | | Detaches the SConnection from the current thread without
closing the JDBC connection so that it can be reattached to another thread.
Rarely used, detachAndClose is normally what is used.
Checks and throws and issues a message if there are any unflushed
records that have been updated. One should normally commit() or
rollback() before detaching unless embedded within an EJB, in
which flush() is required.
|
| dropTableNoError | | public static void dropTableNoError(String table)(Code) | | Utility routine for dropping tables. Hides JDBC exception
caused if the table does not exist. Mainly used in test cases.
(Does not use the SRecord objects so that they do not all have
to be loaded during specific tests.) Dispatched to SDriver.
WARNING: JDBC error suppression is crude -- a table may indeed
exist and still not be dropped for other reasons,
eg. referential integrity.
WARNING: Due to bugs in JDBC etc. each dropped table must be in
its own transaction in case of errors. This routine commits changes.
|
| dumpCache | | public static void dumpCache()(Code) | | Dumps out the entire cache of records for this connection. For
debugging wierd bugs only.
|
| flush | | public static void flush()(Code) | | Flush all records of tables in this transaction to the database.
|
| getBegunConnection | | static SConnection getBegunConnection()(Code) | | Gets current SConnection object for thread. Throws an exception
if not attached and open AND between begin() and
commit() or rollback(). Package local.
|
| getBegunDBConnection | | public static Connection getBegunDBConnection()(Code) | | Asserts transaction Begin()ed and returns the JDBC connection.
Can be used to integrate direct JDBC calls with the SimpleORM
connection. Dangerous. Take care with caching and never use
this to commit a transaction. Should only be rarely used in
practice.
|
| getConnection | | public static SConnection getConnection()(Code) | | Retrieve or create the SConnection associated with this "Context".
Normally this just means (indirectly) call getThreadedConnection
which finds the connection associated with this thread.
However, if EJB.SConnectionEJB is loaded, then this can be dispached
to getTransactionConnection instead.
It may or may not be begun. May be used to set properties for
the connection, which persist between transactions but not
between attach ments.
|
| getDriver | | public static SDriver getDriver()(Code) | | Eg. if (getDriver() instanceOf SDriverPostgres) ...
Also getDriver().setMyFavoritePerConnectionParameter.
|
| getSequenceDBConnection | | Connection getSequenceDBConnection()(Code) | | Returns a secondary jdbc connection for generating sequence numbers, if required.
Creates a new one if necessary.
|
| hasBegun | | public boolean hasBegun()(Code) | | Transaction is active between begin and commit.
|
| innerAttach | | protected void innerAttach(SDataSource source, String connectionName, Connection rawConnection, SDriver driver)(Code) | | Allows SConnection to be subclassed.
connection should normally be null, in which case conf.obtainPrimaryJDBCConnection
is used to open it.
(rawConnection and sDriverName are deprecated.)
|
| isOpened | | public boolean isOpened()(Code) | | If the JDBC connection has been attached and not closed.
|
| mustCommitBeforeDetaching | | public boolean mustCommitBeforeDetaching()(Code) | | True iff commit must be called before the connection there are any (dirty) records that need to be
committed, regardless of whether they have been flushed.
(Overriden in SConnectionEJB.)
|
| rawAttach | | protected void rawAttach()(Code) | | |
| rawDetach | | protected void rawDetach()(Code) | | |
| rawQueryDB | | public static Object rawQueryDB(String sql, String[] params, int nrColumns)(Code) | | Convenience routine for doing single row queries using raw JDBC.
Be sure to flush the cache appropriately, or you will query
behind it.
if nrColumns == 0 (default) returns one result
column as a non array object, otherwise returns an array of
results. (nrColumns avoids the need to use JDBC meta data which
can be buggy.)
|
| rawUpdateDB | | public static int rawUpdateDB(String sql, Object[] params)(Code) | | Convenience routine for doing bulk updates using raw JDBC.
Dangerous. Take care with caching and never use this to commit
a transaction. Returns number of rows updated.
Does nothing if sql == null.
|
| rawUpdateJDBC | | public static int rawUpdateJDBC(String sql)(Code) | | |
| rollback | | public static void rollback()(Code) | | Purges the cache and rolls back the transaction. Any uncommited
updates to the database are also rolled back.
|
| shortToString | | static String shortToString()(Code) | | Short connection/thread identifier for inclusion in log messages
to enable output from different threads to be separated.
|
| unsafeDetachFromThread | | public static SConnection unsafeDetachFromThread()(Code) | | Enables the SimpleORM connection to be disassociated with the
current thread, and then associated with another thread.
Dangerous. When you pick up the connection you also pick up the
hash map of records retrieved during the transaction.
This is provided for completeness only. Note that both Swing
and EJBs can be used without doing this (see the examples). If
you end up with two threads accessing the same connection at the
same time you will have horrible, unreproduceable bugs.
Don not do it unless you really have to.
|
|
|