Package simpleorm.sessionjdbc

Class SSessionJdbc

java.lang.Object
simpleorm.dataset.SSessionI
simpleorm.sessionjdbc.SSessionJdbc
Direct Known Subclasses:
PersistenceSession
public class SSessionJdbc extends SSessionI
Performs all the interactions between a DataSet and a JDBC Connection.

SSessionJdbc.open creates a new session and associates it with the current thread.

All transactions must start with a begin(), which normally creates a new DataSet to store records in. They with either a commit() or a rollback() which normally destroy the DataSet and all records in it. commit also flush()es any outsanding changes.

Methods are then provided to retrieve recrods from the databse by primary key or general query.

There are also convenience method for performing raw SQL queries should that be required.

  • Constructor Details

    • SSessionJdbc

      protected SSessionJdbc()
      No direct creation of Connections.

  • Method Details

    • open

      public static SSessionJdbc open(DataSource source, String connectionName, SDriver driver)
      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 TestUte.java for an example of how to create a trivial DataSource from an old style DriverManager

    • open

      public static SSessionJdbc open(DataSource source, String connectionName)

    • innerOpen

      protected void innerOpen(DataSource source, String connectionName, SDriver driver)
      Allows SSession to be subclassed. connection should normally be null, in which case conf.obtainPrimaryJDBCConnection is used to open it. (rawConnection and sDriverName are deprecated.)

      We use DataSource rather than just Connection to allow a driver to create a second connection to generate keys etc. But that has never been used, and some old code that potentially supported it has been removed.

    • associateWithThread

      protected void associateWithThread()

    • dissassociateFromThread

      protected void dissassociateFromThread()

    • getThreadLocalSession

      public static SSessionJdbc getThreadLocalSession()
      Retrieve or create the SSession associated with this "Context". Normally this just means (indirectly) call getThreadedConnection which finds the connection associated with this thread.

      (In extras there is an unsupported EJB.SConnectionEJB class which 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.

      This is never used within SimpleOrm itself, it is just a convenience method for users.

    • close

      public void close()
      Main method for closing a session.

      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.

    • detachFromThread

      public SSessionJdbc detachFromThread()
      Enables the SimpleORM connection to be disassociated with the current thread, and then possibly attached to another thread. It also enables multiple sessions to be used within the same thread without getting mixed thread exceptions. (But not multiple threads to use the same session concurrently.)

      Rarely used, normally better to just create a session in the appropriate thread. Both Swing and EJBs can be used without doing this.

      Do not not do it unless you really have to.

    • attachToThread

      public void attachToThread()
      Re-attacheds a detached connection to the current thread.
      See Also:

    • getDataSource

      public DataSource getDataSource()

    • begin

      public void begin()
      Start a new transaction. A JDBC connection must already be attached to this thread, and must not be mid transaction.

    • begin

      public void begin(SDataSet ds)
      Begin a new transaction based on a previously detached data set

    • hasBegun

      public boolean hasBegun()
      Transaction is active between begin and commit.

    • commit

      public void commit()
      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 committed -- do not use JDBC commit directly. Once committed, begin() must be used to start the next transaction.

      Also closes any open SResultSets and SPreparedStatements

    • commitAndDetachDataSet

      public SDataSet commitAndDetachDataSet()

    • rollback

      public void rollback()
      Purges the cache and rolls back the transaction. Any uncommited updates to the database are also rolled back.

      Also closes any open SResultSets and SPreparedStatements

    • setTransactionIsolation

      public void setTransactionIsolation(int mode)
      Set the transaction isolation mode. SimpleORM does not normally change the isolation mode, but consider setting it to Connection.TRANSACTION_SERIALIZABLE to achieve greater reliability in many databases.
      Parameters:
      mode - as defined by java.sql.Connection.setTransactionIsolation

    • flush

      public void flush()
      Flush all records of tables in this transaction to the database.

    • flush

      public void flush(SRecordInstance instance)
      Flush this instance to the database. Normally called by SSession.flush() in reponse to commit but can also be called expicitly if the update order needs to be modified. This method does nothing unless the record is dirty.

      See Also:
      • SSession#flush

    • flushAndPurge

      public void flushAndPurge(SRecordInstance ri)
      Flushes this record instance to the database, removes it from the transaction cache, and then destroys the record so that it can no longer be used. Any future findOrCreate will requery the data base and produce a new record.

      This is useful if one wants to do raw JDBC updates on the record, and be guaranteed not to have an inconsistent cache. (Where bulk updates can be used they are several times faster than updates made via the JVM -- see the benchmarks section in the white paper.)

      It can also be useful to force a requery of records if optmistic locks are being broken, although care must be taken not to rely on values returned by a outdated query.

      See Also:
      • SSession#flush

    • flushAndPurge

      public void flushAndPurge()
      Flushes and Purges all record instances. Can be used before a raw JDBC update to ensure that the cache remains consistent after the query.
      See Also:
      • SRecordInstance#flushAndPurge
      • SRecordMeta#flushAndPurge

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • queryNoFlush

      public <RI extends SRecordInstance> List<RI> queryNoFlush(SQuery<RI> qry)
      Query, but without first flushing the cache, not normally used.
      See Also:

    • query

      public <RI extends SRecordInstance> List<RI> query(SQuery<RI> qry)
      Execute the query and return a list of records. First always flushes any dirty records to the database. (Flush but not commit.)

    • queryOnlyRecord

      public <RI extends SRecordInstance> RI queryOnlyRecord(SQuery<RI> qry)
      Same as query but throws an exception if there is more than one record returned.

    • findOrCreate

      public <RI extends SRecordInstance> RI findOrCreate(SRecordMeta<RI> rmeta, SFieldScalar[] selectList, SQueryMode queryMode, Object... keys)
      Find a record or create one if it does not already exist. Retrieve selectList fields, use queryMode.
      Specified by:
      findOrCreate in class SSessionI

    • findOrCreate

      public <RI extends SRecordInstance> RI findOrCreate(SRecordMeta<RI> rmeta, SSelectMode selectMode, SQueryMode queryMode, Object... keys)

    • findOrCreate

      public <RI extends SRecordInstance> RI findOrCreate(SRecordMeta<RI> rmeta, SSelectMode selectMode, Object... keys)

    • findOrCreate

      public <RI extends SRecordInstance> RI findOrCreate(SRecordMeta<RI> rmeta, SQueryMode queryMode, Object... keys)

    • findOrCreate

      public <RI extends SRecordInstance> RI findOrCreate(SRecordMeta<RI> rmeta, Object... keys)

    • mustFind

      public <RI extends SRecordInstance> RI mustFind(SRecordMeta<RI> rmeta, SQueryMode queryMode, Object... keys)

    • mustFind

      public <RI extends SRecordInstance> RI mustFind(SRecordMeta<RI> rmeta, Object... keys)

    • find

      public <RI extends SRecordInstance> RI find(SRecordMeta<RI> rmeta, SQueryMode queryMode, Object... keys)
      Same as findOrCreate but if not existing returns null rather than creating a new record. (Note that it may still need to query the database to determine if it is not there.)

    • find

      public <RI extends SRecordInstance> RI find(SRecordMeta<RI> rmeta, Object... keys)

    • create

      public <RI extends SRecordInstance> RI create(SRecordMeta<RI> rmeta, Object... keys)
      Create a new record.

      Assumes the record is new, will do an insert at flush time which will cause a unique index violation if it was not. Use a findOrCreate followed by assertNewRow if it is unclear whether the row is really new.

    • createWithGeneratedKey

      public <RI extends SRecordInstance> RI createWithGeneratedKey(SRecordMeta<RI> rmeta)
      Creates a new object with a newly generated key. Note that the SELECT MAX method is used unless a database dependent alternative is available (currently only for PostgreSQL). SGENERATED_KEY.

      Always creates a new empty record. ## This code is partially copied into SRecordInstance.attach() for records created while detached.

    • dirtyPurge

      public void dirtyPurge(SRecordInstance rinst)
      Removes this record from the cache but without flushing it. Any changes to it will be lost. This might be useful if the record is being manually updated/deleted and you want to deliberately ignore any direct changes.

      Dangerous, use with care.

      See Also:

    • rawUpdateDB

      public int rawUpdateDB(String sql, Object... params)
      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.

      Flushes before performing update. But does not requery any updated records.

    • rawUpdateDBNoFlush

      public int rawUpdateDBNoFlush(String sql, Object... params)

    • rawQueryMaps

      public List<Map> rawQueryMaps(String sql, boolean flush, Object... params)
      Executes sql with parameters, returns a list of Maps of values, one map per row. The key to the maps is the meta data returned by JDBC. This is normally just the column name, but can be specified in most SQLs. eg.

      SELECT MAX(SALARY) AS MAX_SAL ... FROM ....

    • rawQueryMap

      public Map rawQueryMap(String sql, boolean flush, Object... params)
      Returns at most one row, else exception. Null if none.

    • rawQueryOneMap

      public Map rawQueryOneMap(String sql, boolean flush, Object... params)
      Returns exactly one row, else exception. Exception if none.

    • rawQuerySingle

      public Object rawQuerySingle(String sql, boolean flush, Object... params)
      Returns a single value of at most one row.

    • getLogger

      public SLog getLogger()

    • getJdbcConnection

      public Connection getJdbcConnection()

    • getDataSet

      public SDataSet getDataSet()

    • getDriver

      public SDriver getDriver()
      Eg. if (getDriver() instanceOf SDriverPostgres) ... Also getDriver().setMyFavoritePerConnectionParameter.

    • getStatistics

      public SStatistics getStatistics()