public class Persistence
extends java.lang.Object
An instance of this class is retrieved from the factory method get(java.lang.String)
. One instance of this class is associated with a single, physical
database, per user context.
An instance of a concrete LockManager
implementation
is created for each each instance of this class. The implementation to use is
queried from the directory service, and defaults to the InMemoryLockManager
if no other implementation is specified in the
directory.
Transactions are explicitly managed with beginTransaction()
, commit()
and rollback()
. Only one transaction per client context
may be active at a time. These are database-level transactions, which may
or may not coincide with application-level transactions.
Most methods which perform some sort of query will open an implicit transaction before the query is executed, but only if no transaction already is active. Implicit transactions are closed in one of two ways:
The exception to this rule are the variants of the scroll
method. Because of the nature of ScrollableResults
, a commit
should not take place until after calling code is finished using this
object. This is necessary because fetching results may require additional
trips to the database within the transaction. In this case, the
scroll
methods themselves do not trigger implicit
transactions. Rather, it is up to calling code (see ScrollingResults
) to bracket its use of the result set with calls to
pushImplicitTransaction()
and popImplicitTransaction(Context)
.
The implicit transaction mechanism is intended only to support legacy use
cases. External code which directly accesses query methods within
the Persistence
class should always properly bracket its use
of these methods with explicit transactions. Otherwise,
unpredictable behavior may result as implicit transactions are opened and
closed automatically. Take special care to initialize any necessary
collection associations (for example, converted extent fields within DMOs
are implemented as lazily initialized, associated collections), before
ending a transaction.
Hibernate sessions are managed implicitly, transparently to application
code and even to other classes within the persistence framework. No more
than one session per user context may be active at a time. Sessions are
opened lazily as they are needed to fulfill database operations: executing
a query, persisting a record, creating a temp table, etc. They are closed
upon committing or rolling back a transaction, or if any exception is
caught during the processing of a database operation. Upon opening a new
session, the current context's BufferManager
instance is
interrogated for all active records. These are the current records stored
in all open record buffers for the database matching the current
Persistence
instance; they represent detached records
previously associated with the last open session (if any).
Modifier and Type | Class and Description |
---|---|
private static class |
Persistence.ColumnKey
A hash key for a unique combination of table and column name.
|
(package private) class |
Persistence.Context
A storage and work area for context-local variables used by the
enclosing class.
|
private static class |
Persistence.QueryKey
A hash key for a unique combination of HQL, maximum results, and starting row offset.
|
Modifier and Type | Field and Description |
---|---|
private static boolean |
active
true if the persistence layer can be used. |
private java.util.Map<java.sql.Connection,org.hibernate.Session> |
borrowedSessions
Sessions in use for special connection requests
|
private static java.util.Map<java.sql.Connection,java.util.Map<Persistence.ColumnKey,java.lang.Integer>> |
columnTypes
A transient mapping of JDBC connections to column data type maps
|
private ContextLocal<Persistence.Context> |
context
Context local object to manage persistence variables
|
private Database |
database
Database served by this object
|
private static java.lang.String |
DEFAULT_IDENTITY_MANAGER
Default identity manager implementation
|
private static java.lang.String |
DEFAULT_LOCK_MANAGER
Default lock manager implementation
|
private org.hibernate.dialect.Dialect |
dialect
Hibernate database dialect helper
|
private static boolean |
foreignKeysEnabled
Flag indicating whether records are joined using foreign keys
|
private int |
hashCode
Cached hash code
|
static java.lang.String |
ID_GEN_SEQUENCE
Well-known name of ID generator sequence
|
private IdentityManager |
identityManager
Identity manager
|
private static java.util.Map<java.lang.String,java.util.Map<java.lang.String,java.util.List<P2JIndex>>> |
indexesByTable
Mappings of table names to index lists, organized by schema
|
private long |
listThreshold
Milliseconds a list query may take before being reported
|
private long |
loadByIDThreshold
Milliseconds a load-by-id query may take before being reported
|
private long |
loadThreshold
Milliseconds a load query may take before being reported
|
private LockManager |
lockManager
Pessimistic lock manager
|
private LockTableUpdater |
lockTableUpdater
Object which keeps lock metadata in sync with record lock activity
|
private static java.util.logging.Logger |
LOG
Logger
|
private long |
scrollThreshold
Milliseconds a scrolling query may take before being reported
|
private boolean |
temporary
Does this object represent the temporary database?
|
Modifier | Constructor and Description |
---|---|
protected |
Persistence(Database database,
org.hibernate.dialect.Dialect dialect)
Construct an instance for a particular, physical database, storing the
dialect class which Hibernate uses to create a portability layer.
|
Modifier and Type | Method and Description |
---|---|
void |
attach(java.lang.Object object)
Ensure the specified object is being managed by the session associated
with the backing database in the current context.
|
boolean |
beginTransaction()
Begin a new Hibernate transaction and store the instance in the local
context.
|
(package private) boolean |
beginTransaction(Persistence.Context local)
Begin a new Hibernate transaction and store the instance in the local
context.
|
(package private) org.hibernate.Session |
bind(Persistence.Context local)
Bind this instance to a backing, Hibernate session, in case it is not
currently backed by one.
|
(package private) void |
checkInConnection(java.sql.Connection connection)
Check in a JDBC connection previously obtained with
checkOutConnection() . |
(package private) java.sql.Connection |
checkOutConnection()
Get a JDBC connection from the current, context local session, creating
the session first if necessary.
|
private boolean |
checkReadOnly(java.lang.String[] entities)
Determine whether all of the given DMO entity names represent read-only tables.
|
void |
cleanup()
Clean up the current context.
|
void |
commit()
Commit the current Hibernate transaction and close the current session.
|
(package private) void |
commit(Persistence.Context local)
Commit the current Hibernate transaction and close the current session.
|
(package private) static boolean |
containedInSession(java.lang.Object object,
org.hibernate.Session session)
Check if the given object is associated with the given Hibernate session.
|
protected IdentityManager |
createIdentityManager()
Create and initialize the identity manager to be used with this
instance of persistence services for the given database.
|
protected LockManager |
createLockManager()
Create and initialize the lock manager to be used with this instance of
persistence services for the given database.
|
void |
delete(java.lang.Object object)
Delete the persisted object from the specified database.
|
int |
deleteOrUpdate(java.lang.String hql,
java.lang.Object[] values,
org.hibernate.type.Type[] types,
java.lang.String entity)
Perform a bulk delete or update of all objects which meet the specified
criteria.
|
(package private) void |
deregisterSessionListener(SessionListener listener)
Deregister a session listener when it no longer needs to receive session life cycle events.
|
void |
detach(java.lang.Object object)
Evict the specified object from the session associated with the backing
database in the current context.
|
(package private) void |
enableTransactionTrace(boolean enable)
Set enable mode for transaction tracing in the current context.
|
boolean |
equals(java.lang.Object o)
Override the parent's implementation to ensure it is consistent with
hashCode . |
(package private) void |
evict(java.util.Collection<Persistable> evictees)
Evict a collection of DMOs from the current Hibernate session.
|
(package private) void |
evict(Persistence.Context local,
Persistable dmo)
Evict the given DMO from the current session immediately.
|
int |
executeSQL(java.lang.String sql)
Execute an arbitrary SQL statement which does not produce a result set.
|
int |
executeSQL(java.lang.String sql,
java.lang.Object[] args)
Execute an arbitrary SQL statement which does not produce a result set.
|
(package private) int |
executeSQL(java.lang.String sql,
java.lang.Object[] args,
java.lang.String[] entities,
boolean noFlush)
Execute an arbitrary SQL statement which does not produce a result set.
|
void |
executeSQLBatch(java.util.List<java.lang.String> sql,
java.lang.String[] entities,
boolean noFlush)
Execute an arbitrary list of SQL statements in batch.
|
org.hibernate.ScrollableResults |
executeSQLQuery(java.lang.String sql)
Execute an arbitrary SQL query.
|
org.hibernate.ScrollableResults |
executeSQLQuery(java.lang.String sql,
java.lang.Object[] args)
Execute an arbitrary SQL query.
|
org.hibernate.ScrollableResults |
executeSQLQuery(java.lang.String sql,
java.lang.Object[] args,
java.lang.String[] entities,
boolean noFlush)
Execute an arbitrary SQL query.
|
void |
flush()
Flush the current session, which synchronizes the in-memory state of
DMOs to the database.
|
private void |
flush(boolean clear)
Flush the current session, which synchronizes the in-memory state of
DMOs to the database.
|
private void |
flush(Persistence.Context local,
org.hibernate.Session session,
boolean clear)
Flush the current session, which synchronizes the in-memory state of
DMOs to the database.
|
void |
flushBatch()
Flush a batch of records to the database, typically while inserting
records in bulk.
|
void |
flushMetaLockEvents()
Force the lock table updater to process all record lock events which are pending at the time
this method is invoked.
|
static Persistence |
get(java.lang.String name)
Deprecated.
Use
PersistenceFactory.getInstance(String) instead. |
(package private) java.lang.Throwable |
getBeginTxTrace()
Retrieve trace information about where the current transaction, if any, was started.
|
private static int |
getColumnDataType(Database database,
java.lang.String table,
java.lang.String column)
Use database metadata to determine the data type of a database column.
|
(package private) Persistence.Context |
getContext()
Get the context for the current user session.
|
Database |
getDatabase()
Get the database information object associated with this persistence
service object.
|
org.hibernate.dialect.Dialect |
getDialect()
Get the database dialect helper object associated with the database
backing this object.
|
IdentityManager |
getIdentityManager()
Get the identity manager associated with this
Persistence
instance. |
LockManager |
getLockManager()
Get the lock manager associated with this
Persistence
instance. |
private org.hibernate.Query |
getQuery(Persistence.Context local,
java.lang.String hql,
int maxResults,
int startOffset,
java.lang.Object[] values,
org.hibernate.type.Type[] types,
boolean readOnly)
Get or create a query for the given HQL query string.
|
RecordLockContext |
getRecordLockContext()
Get the record lock context associated with the current client session.
|
org.hibernate.Session |
getSession()
Get the Hibernate session associated with the current context.
|
java.lang.Object |
getSingleSQLResult(java.lang.String sql,
java.lang.Object[] args,
java.lang.String entity,
boolean noFlush)
Convenience method to retrieve a single result from a SQL statement.
|
private void |
handleException(java.lang.String message,
org.hibernate.HibernateException exc)
Raise a STOP condition, if the given exception represents a catastrophic, JDBC failure;
else throw a
PersistenceException . |
int |
hashCode()
Override the parent's implementation to return a hash code cached at construction.
|
static void |
initialize()
Initialize various infrastructure components of the persistence framework:
DataTypeHelper , which is used when preprocessing HQL where clauses. |
protected void |
initializeInstance()
Initialize the helper objects to which this object delegates certain service requests.
|
static boolean |
isActive()
Reports if the persistence layer can be used or not.
|
(package private) static boolean |
isForeignKeysEnabled()
Detemine whether records are joined using foreign keys.
|
(package private) boolean |
isTemporary()
Determine whether this persistence object is for a temporary table database.
|
boolean |
isTransactionOpen()
Indicate whether an explicit, database-level transaction currently is open.
|
<T> java.util.List<T> |
list(java.lang.String[] entities,
java.lang.String hql,
java.lang.Object[] values,
org.hibernate.type.Type[] types,
int maxResults,
int startOffset,
boolean readOnlyQuery,
boolean noFlush)
Execute an HQL query and return the results as a list.
|
<T> java.util.List<T> |
list(java.lang.String hql,
java.lang.Object[] values,
org.hibernate.type.Type[] types,
int maxResults,
int startOffset,
boolean readOnlyQuery)
Execute an HQL query and return the results as a list.
|
Persistable |
load(RecordBuffer buffer,
java.io.Serializable id,
LockType lockType,
long timeout,
boolean updateLock,
boolean forceRefresh)
Load a single record from the database or from the session-level cache.
|
Persistable |
load(RecordBuffer buffer,
java.lang.String hql,
java.lang.Object[] values,
org.hibernate.type.Type[] types,
LockType lockType,
long timeout,
boolean unique,
boolean updateLock,
boolean forceRefresh,
boolean findByKey)
Execute an HQL query and load a single record from the session-level cache or, optionally,
refresh it from the database.
|
Persistable |
load(java.lang.String table,
java.lang.Class<?> dmoClass,
java.io.Serializable id,
LockType lockType,
boolean updateLock)
Load a single record from the database or from the session-level cache.
|
Persistable |
load(java.lang.String table,
java.lang.String entityName,
java.io.Serializable id,
LockType lockType,
boolean updateLock,
boolean forceRefresh)
Load a single record from the session-level cache or, optionally, refresh it from the
database.
|
Persistable |
load(java.lang.String table,
java.lang.String entityName,
java.io.Serializable id,
LockType lockType,
long timeout,
boolean updateLock,
boolean forceRefresh)
Load a single record from the session-level cache or, optionally, refresh it from the
database.
|
void |
lock(LockType lockType,
RecordIdentifier ident,
boolean update)
Attempt to obtain the specified lock type on a particular record.
|
void |
lock(LockType lockType,
RecordIdentifier ident,
boolean update,
long timeout)
Attempt to obtain the specified lock type on a particular record.
|
LockType |
lockTable(java.lang.String table,
LockType lockType,
boolean update)
Attempt to obtain the specified lock type on a table.
|
(package private) void |
maybeFlush()
Flush the current session (if any), if there are any pending changes.
|
Persistable |
merge(Persistable dmo)
Merges the state of the given object with the persistent object with the same identifier and
returns the merged object.
|
java.lang.String |
message(java.lang.String message)
Format the given message text by prepending a descriptor including the
user's current context and the physical name of the database.
|
java.io.Serializable |
nextPrimaryKey(java.lang.String table)
Obtain the next available primary key ID on a per-table basis.
|
int |
popImplicitTransaction(Persistence.Context local)
Decrement the implicit transaction use counter.
|
static java.lang.Object |
preprocessQueryParameter(java.lang.Object arg,
P2JDialect dialect)
Perform special handling on a query substitution parameter to avoid
errors during query execution.
|
private void |
preprocessQueryParameters(java.lang.Object[] args)
Perform special handling on query substitution parameters to avoid
errors during query execution.
|
int |
pushImplicitTransaction()
Increment the implicit transaction use counter and begin an implicit
transaction if none is currently active, and the use count currently
is at zero.
|
(package private) static void |
queryAllIndexData(Database database,
java.lang.String schema)
Query all index metadata from the given database, using a thread pool with 1 thread per
available CPU.
|
(package private) static java.util.List<P2JIndex> |
queryIndexData(Database database,
java.lang.String table)
Gather a list of
P2JIndex objects which describe the
indices on the given table. |
LockType |
queryLock(RecordIdentifier ident)
Query the lock type currently held by the current context for the
specified database record.
|
Persistable |
quickLoad(RecordIdentifier ident)
Load a single record from the database or from the session-level cache.
|
Persistable |
quickLoad(RecordIdentifier ident,
boolean refresh)
Load a single record from the database or from the session-level cache.
|
(package private) void |
registerSessionListener(SessionListener listener,
SessionListener.Scope scope)
Register a
SessionListener to receive session life
cycle event notifications. |
(package private) static void |
reportUDFVersion(Database database)
Logs the FWD version returned by the getFWDVersion user-defined function (UDF/p2jpl) for
this database.
|
(package private) static java.util.Map<java.lang.String,P2JIndex> |
retrieveIndexData(java.sql.ResultSet rs,
Database database,
java.lang.String table)
Given a the result set of an index metadata query (for a certain table),
this method is responsible for creating a map which will hold, for each
index, a
P2JIndex object. |
void |
rollback()
Roll back the current Hibernate transaction and close the current
session.
|
(package private) void |
rollback(Persistence.Context local)
Roll back the current Hibernate transaction and close the current
session.
|
void |
save(Persistable dmo,
java.io.Serializable id)
Persist the specified object to the backing database session, using the
given ID.
|
org.hibernate.ScrollableResults |
scroll(java.lang.String[] entities,
java.lang.String hql,
java.lang.Object[] values,
org.hibernate.type.Type[] types,
int maxResults,
int startOffset,
org.hibernate.ScrollMode scrollMode)
Execute an HQL query and get a scrollable cursor on the result set.
|
org.hibernate.ScrollableResults |
scroll(java.lang.String hql,
java.lang.Object[] values,
org.hibernate.type.Type[] types)
Execute an HQL query and get a scrollable cursor on the result set.
|
org.hibernate.ScrollableResults |
scroll(java.lang.String hql,
java.lang.Object[] values,
org.hibernate.type.Type[] types,
int maxResults,
int startOffset)
Execute an HQL query and get a scrollable cursor on the result set.
|
org.hibernate.ScrollableResults |
scroll(java.lang.String hql,
java.lang.Object[] values,
org.hibernate.type.Type[] types,
int maxResults,
int startOffset,
org.hibernate.ScrollMode scrollMode)
Execute an HQL query and get a scrollable cursor on the result set.
|
(package private) void |
shareLockTableUpdater(Database database)
If this object is associated with a metadata database, set this object's lock table updater
to be the same as that of the
Persistence instance associated with the given,
primary database. |
(package private) void |
uniqueResultViolation(RecordBuffer buffer,
java.lang.Exception exc)
Process an error condition in which a unique result should have been
found, but multiple results occurred.
|
public static final java.lang.String ID_GEN_SEQUENCE
private static final java.util.logging.Logger LOG
private static final java.lang.String DEFAULT_LOCK_MANAGER
private static final java.lang.String DEFAULT_IDENTITY_MANAGER
private static final java.util.Map<java.sql.Connection,java.util.Map<Persistence.ColumnKey,java.lang.Integer>> columnTypes
private static boolean foreignKeysEnabled
private static volatile boolean active
true
if the persistence layer can be used.private final ContextLocal<Persistence.Context> context
private final Database database
private final org.hibernate.dialect.Dialect dialect
private final boolean temporary
private final int hashCode
private final long scrollThreshold
private final long listThreshold
private final long loadThreshold
private final long loadByIDThreshold
private LockManager lockManager
private LockTableUpdater lockTableUpdater
private IdentityManager identityManager
private java.util.Map<java.sql.Connection,org.hibernate.Session> borrowedSessions
private static java.util.Map<java.lang.String,java.util.Map<java.lang.String,java.util.List<P2JIndex>>> indexesByTable
protected Persistence(Database database, org.hibernate.dialect.Dialect dialect)
database
- Database with which this instance is permanently associated.dialect
- Portability object used by Hibernate to issue commands to the database.public static Persistence get(java.lang.String name)
PersistenceFactory.getInstance(String)
instead.name
- Name of physical database with which the instance is
permanently associated.public static void initialize() throws PersistenceException
DataTypeHelper
, which is used when preprocessing HQL where clauses.
BufferManager
, which tracks open buffers and transactions.
ChangeBroker
, which dispatches notifications about changes to DMO properties.
DatabaseManager
, which configures the Hibernate environment for the databases
to which the framework connects.
P2OLookup
, instances of which are used for runtime, on-the-fly query and
temp-table conversion.
DatabaseTriggerManager
, which tracks and fires database triggers at the
appropriate times.
java.lang.IllegalStateException
- if invoked more than once.PersistenceException
- if any error is encountered initializing the persistence framework.DataTypeHelper.initialize()
,
BufferManager.initialize()
,
ChangeBroker.initialize()
,
DatabaseManager.initialize()
,
P2OLookup.initialize()
,
DatabaseTriggerManager.initialize(String)
public static boolean isActive()
true
if the persistence layer is initialized and can be used.public static java.lang.Object preprocessQueryParameter(java.lang.Object arg, P2JDialect dialect)
character
. Any
parameter affected is replaced with a new character
instance at the same index position within args
.
date
instance at the same index position within args
.
Note: this method has special processing for null
bytes
embedded in character
variables. The text of the variable
is truncated starting at the first embedded null
byte.
This means that the resulting substitution parameters are guaranteed
to never include null
bytes.
arg
- A single substitution parameter.dialect
- Database dialect.static java.util.List<P2JIndex> queryIndexData(Database database, java.lang.String table) throws PersistenceException
P2JIndex
objects which describe the
indices on the given table. This method uses the database metadata,
if any, exposed by the database's JDBC driver.database
- Database which contains table
.table
- Name of table to inspect.P2JIndex
objects, one per index found,
or null
if the JDBC metadata query throws
SQLException
, indicating a database error, or
that the JDBC driver does not support the requested feature.
An empty list is returned if the driver supported the query,
but no indices were found.PersistenceException
- if there is an error getting a Hibernate session or determining
an indexed column's data type.java.lang.UnsupportedOperationException
- if the JDBC driver cannot query database metadata.static void queryAllIndexData(Database database, java.lang.String schema) throws PersistenceException
database
- Database from which to query index metadata.schema
- Schema containing index information.PersistenceException
- if there is an error accessing the database or querying metadata.static java.util.Map<java.lang.String,P2JIndex> retrieveIndexData(java.sql.ResultSet rs, Database database, java.lang.String table) throws PersistenceException
P2JIndex
object.rs
- The ResultSet
instance used to retrieve the index
metadata.database
- Database which contains table
.table
- The table for which the indexes are retrieved.P2JIndex
instances for each existing table
index.PersistenceException
- if any database error is encountered.static boolean isForeignKeysEnabled()
true
if records are joined using foreign keys.
false
if records are joined using legacy key
fields.static boolean containedInSession(java.lang.Object object, org.hibernate.Session session)
Session.contains(Object)
in Hibernate 3 (in Hibernate 4
Session.contains(Object)
returns false
if the entity is
kept in the session context, but enqueued for deletion or was actually deleted from the
database).object
- An instance of a persistent class.session
- Hibernate session presumably containing target object.true
if the given object is associated with the given Hibernate
session.static void reportUDFVersion(Database database) throws PersistenceException
PersistenceException
private static int getColumnDataType(Database database, java.lang.String table, java.lang.String column) throws PersistenceException
database
- Target database.table
- Target table.column
- Target column.java.sql.Types
constants.PersistenceException
- if there is any database error, or if the metadata query fails
to produce a result for the given column.public final int hashCode()
hashCode
in class java.lang.Object
public final boolean equals(java.lang.Object o)
hashCode
.equals
in class java.lang.Object
public org.hibernate.dialect.Dialect getDialect()
public Database getDatabase()
public LockManager getLockManager()
Persistence
instance. For temp tables, this will be null
, since temp
table data is naturally compartmentalized and record locking is
meaningless in this case. For permanent databases, this method will
return the lock manager created when this class was instantiated.public void flushMetaLockEvents()
public IdentityManager getIdentityManager()
Persistence
instance. For temp tables, this will be null
, since for
temp tables unique primary keys generated using TemporaryBuffer.nextPrimaryKey()
. For permanent databases, this
method will return the identity manager created when this class was
instantiated.public org.hibernate.ScrollableResults scroll(java.lang.String hql, java.lang.Object[] values, org.hibernate.type.Type[] types) throws PersistenceException
Note: while this method attempts to use a server-side database
cursor to fetch results, some JDBC driver implementations (e.g.,
PostgreSQL) may store an intermediate form of the entire result
set in memory instead, effectively doubling the amount of memory
required. To avoid this, consider using scroll(String, Object[], Type[], int, int, ScrollMode)
instead. Using
that method with a ScrollMode
of FORWARD_ONLY
and setting a JDBC fetch size to a reasonable value may allow a JDBC
driver to use a server-side cursor to fetch smaller batches of results
at a time. Consult your JDBC driver documentation and/or source code to
determine whether this is an issue for your JDBC implementation.
hql
- HQL query statement passed to Hibernate.values
- Substitution values for the query. If none, this should be an
empty array.types
- Hibernate types for the values
array. If none,
this should be an empty array.PersistenceException
- if there was an error executing the query.DBUtils.makeTypeArray(Object[])
,
DBUtils.makeTypeArray(Object[], Type[])
public org.hibernate.ScrollableResults scroll(java.lang.String hql, java.lang.Object[] values, org.hibernate.type.Type[] types, int maxResults, int startOffset) throws PersistenceException
Note: while this method attempts to use a server-side database
cursor to fetch results, some JDBC driver implementations (e.g.,
PostgreSQL) may store an intermediate form of the entire result
set in memory instead, effectively doubling the amount of memory
required. To avoid this, consider using scroll(String, Object[], Type[], int, int, ScrollMode)
instead. Using
that method with a ScrollMode
of FORWARD_ONLY
and setting a JDBC fetch size to a reasonable value may allow a JDBC
driver to use a server-side cursor to fetch smaller batches of results
at a time. Consult your JDBC driver documentation and/or source code to
determine whether this is an issue for your JDBC implementation.
hql
- HQL query statement passed to Hibernate.values
- Substitution values for the query. If none, this should be an
empty array.types
- Hibernate types for the values
array. If none,
this should be an empty array.maxResults
- The maximum number of elements to be returned in the list.
If this value is non-positive, no upper limit is applied.startOffset
- The 0-based offset of the first record to retrieve. If this
value is non-positive, an offset of 0 is used by default.PersistenceException
- if there was an error executing the query.DBUtils.makeTypeArray(Object[])
,
DBUtils.makeTypeArray(Object[], Type[])
public org.hibernate.ScrollableResults scroll(java.lang.String hql, java.lang.Object[] values, org.hibernate.type.Type[] types, int maxResults, int startOffset, org.hibernate.ScrollMode scrollMode) throws PersistenceException
hql
- HQL query statement passed to Hibernate.values
- Substitution values for the query. If none, this should be an
empty array.types
- Hibernate types for the values
array. If none,
this should be an empty array.maxResults
- The maximum number of elements to be returned in the list.
If this value is non-positive, no upper limit is applied.startOffset
- The 0-based offset of the first record to retrieve. If this
value is non-positive, an offset of 0 is used by default.scrollMode
- Scroll mode which should apply to the result set.PersistenceException
- if there was an error executing the query.public org.hibernate.ScrollableResults scroll(java.lang.String[] entities, java.lang.String hql, java.lang.Object[] values, org.hibernate.type.Type[] types, int maxResults, int startOffset, org.hibernate.ScrollMode scrollMode) throws PersistenceException
entities
- Names of the DMO entities associated with this query statement.hql
- HQL query statement passed to Hibernate.values
- Substitution values for the query. If none, this should be an
empty array.types
- Hibernate types for the values
array. If none,
this should be an empty array.maxResults
- The maximum number of elements to be returned in the list.
If this value is non-positive, no upper limit is applied.startOffset
- The 0-based offset of the first record to retrieve. If this
value is non-positive, an offset of 0 is used by default.scrollMode
- Scroll mode which should apply to the result set.PersistenceException
- if there was an error executing the query.public <T> java.util.List<T> list(java.lang.String hql, java.lang.Object[] values, org.hibernate.type.Type[] types, int maxResults, int startOffset, boolean readOnlyQuery) throws PersistenceException
Object
s.
No locking is attempted.
Note: this method should be used only for queries that are
expected to return a relatively small result set, since the entire
result set is stored in the returned list. Additionally, some JDBC
driver implementations (e.g., PostgreSQL) may store an intermediate form
of the result set in memory, effectively doubling the amount of memory
required. To avoid this, consider using scroll(String, Object[], Type[], int, int, ScrollMode)
instead. Using
that method with a ScrollMode
of FORWARD_ONLY
and setting a JDBC fetch size to a reasonable value may allow a JDBC
driver to use a server-side cursor to fetch smaller batches of results
at a time. Consult your JDBC driver documentation and/or source code to
determine whether this is an issue for your JDBC implementation.
hql
- HQL query statement passed to Hibernate. This method makes no
assumptions as to the types of object(s) returned.values
- Substitution values for the query. If none, this should be an
empty array.types
- Hibernate types for the values
array. If none,
this should be an empty array.maxResults
- The maximum number of elements to be returned in the list.
If this value is non-positive, no upper limit is applied.startOffset
- The 0-based offset of the first record to retrieve. If this
value is non-positive, an offset of 0 is used by default.readOnlyQuery
- true
to execute the query in read-only mode, else
false
.null
if no result was found.PersistenceException
- if there was an error executing the query.DBUtils.makeTypeArray(Object[])
,
DBUtils.makeTypeArray(Object[], Type[])
public <T> java.util.List<T> list(java.lang.String[] entities, java.lang.String hql, java.lang.Object[] values, org.hibernate.type.Type[] types, int maxResults, int startOffset, boolean readOnlyQuery, boolean noFlush) throws PersistenceException
Object
s.
No locking is attempted.
Note: this method should be used only for queries that are
expected to return a relatively small result set, since the entire
result set is stored in the returned list. Additionally, some JDBC
driver implementations (e.g., PostgreSQL) may store an intermediate form
of the result set in memory, effectively doubling the amount of memory
required. To avoid this, consider using scroll(String, Object[], Type[], int, int, ScrollMode)
instead. Using
that method with a ScrollMode
of FORWARD_ONLY
and setting a JDBC fetch size to a reasonable value may allow a JDBC
driver to use a server-side cursor to fetch smaller batches of results
at a time. Consult your JDBC driver documentation and/or source code to
determine whether this is an issue for your JDBC implementation.
entities
- Names of the DMO entities associated with this query statement.hql
- HQL query statement passed to Hibernate. This method makes no
assumptions as to the types of object(s) returned.values
- Substitution values for the query. If none, this should be an
empty array.types
- Hibernate types for the values
array. If none,
this should be an empty array.maxResults
- The maximum number of elements to be returned in the list.
If this value is non-positive, no upper limit is applied.startOffset
- The 0-based offset of the first record to retrieve. If this
value is non-positive, an offset of 0 is used by default.readOnlyQuery
- true
to execute the query in read-only mode, else
false
.null
if no result was found.PersistenceException
- if there was an error executing the query.DBUtils.makeTypeArray(Object[])
,
DBUtils.makeTypeArray(Object[], Type[])
public Persistable load(RecordBuffer buffer, java.lang.String hql, java.lang.Object[] values, org.hibernate.type.Type[] types, LockType lockType, long timeout, boolean unique, boolean updateLock, boolean forceRefresh, boolean findByKey) throws PersistenceException
buffer
argument is used only to extract information needed
to perform the query.buffer
- Record buffer which holds information about the DMO class type
and name of the table being queried.hql
- HQL query statement passed to Hibernate. This may be either an
ID-only projection query or a full query (see above).values
- Substitution values for the query. If none, this should be an
empty array.types
- Hibernate types for the values
array. If none,
this should be an empty array.lockType
- Type of lock the lock manager should register on the resulting
record for the current user context.timeout
- Number of milliseconds to wait to acquire the requested lock type.
Throws LockTimeoutException
if this time elapses before the
lock is acquired. Specify 0 to wait indefinitely for the lock. Ignored
if lockType
is NONE
.unique
- true
if no more than one result is expected from this query;
false
if the query could result in
more than one record.updateLock
- true
to update the current lock state;
false
to leave the current lock state unchanged.forceRefresh
- If true
forces the record to be refreshed from database. Otherwise
it will be refreshed only if the lockType has been upgraded from NONE.findByKey
- If true
, this overrides the current rereadnolock
setting;
if false
, honor rereadnolock
.null
if no result was found.LockTimeoutException
- if a record was found, but its lock could not be acquired within the positive
timeout
period specified.LockUnavailableException
- if a record was found and a no-wait lock type was specified, but the lock could
not be acquired immediately.PersistenceException
- if there was an error executing the query or if a unique query
(i.e., unique == true
) returned multiple results,public Persistable load(RecordBuffer buffer, java.io.Serializable id, LockType lockType, long timeout, boolean updateLock, boolean forceRefresh) throws PersistenceException
buffer
argument is used
only to extract information needed to perform the locking and loading.buffer
- Record buffer which holds information about the DMO class type
and name of the table being queried.id
- Primary key of the record to be loaded into the buffer. May
not be null
.lockType
- Type of lock the lock manager should register on the resulting
record for the current user context.timeout
- Number of milliseconds to wait to acquire the requested lock type.
Throws LockTimeoutException
if this time elapses before the
lock is acquired. Specify 0 to wait indefinitely for the lock. Ignored
if lockType
is NONE
.updateLock
- true
to update the current lock state;
false
to leave the current lock state unchanged.forceRefresh
- If true
forces the record to be refreshed from database. Otherwise
it will be refreshed only if the lockType has been upgraded from NONE.null
if no result was found.LockTimeoutException
- if a record was found, but its lock could not be acquired within the positive
timeout
period specified.LockUnavailableException
- if a record was found and a no-wait lock type was specified, but the lock could
not be acquired immediately.PersistenceException
- if there was an error loading the DMO from the Hibernate
session and/or database.public Persistable load(java.lang.String table, java.lang.Class<?> dmoClass, java.io.Serializable id, LockType lockType, boolean updateLock) throws PersistenceException
table
- Table from which record is to be read.dmoClass
- DMO implementation class of record being read.id
- Primary key of the record to be loaded into the buffer. May
not be null
.lockType
- Type of lock the lock manager should register on the resulting
record for the current user context.updateLock
- true
to update the current lock state;
false
to leave the current lock state unchanged.null
if no result was found.LockUnavailableException
- if a record was found but its lock could not be acquired.PersistenceException
- if there was an error loading the DMO from the Hibernate
session and/or database.public Persistable load(java.lang.String table, java.lang.String entityName, java.io.Serializable id, LockType lockType, boolean updateLock, boolean forceRefresh) throws PersistenceException
table
- Table from which record is to be read.entityName
- Name of DMO implementation class of record being read.id
- Primary key of the record to be loaded into the buffer. May
not be null
.lockType
- Type of lock the lock manager should register on the resulting
record for the current user context.updateLock
- true
to update the current lock state;
false
to leave the current lock state unchanged.forceRefresh
- If true
forces the record to be refreshed from database. Otherwise
it will be refreshed only if the lockType has been upgraded from NONE.null
if no result was found.LockUnavailableException
- if a record was found and a no-wait lock type was specified, but the lock could
not be acquired immediately.PersistenceException
- if there was an error loading the DMO from the Hibernate
session and/or database.public Persistable load(java.lang.String table, java.lang.String entityName, java.io.Serializable id, LockType lockType, long timeout, boolean updateLock, boolean forceRefresh) throws PersistenceException, LockTimeoutException
table
- Table from which record is to be read.entityName
- Name of DMO implementation class of record being read.id
- Primary key of the record to be loaded into the buffer. May
not be null
.lockType
- Type of lock the lock manager should register on the resulting
record for the current user context.timeout
- Number of milliseconds to wait to acquire the requested lock type.
Throws LockTimeoutException
if this time elapses before the
lock is acquired. Specify 0 to wait indefinitely for the lock. Ignored
if lockType
is NONE
.updateLock
- true
to update the current lock state;
false
to leave the current lock state unchanged.forceRefresh
- If true
forces the record to be refreshed from database. Otherwise
it will be refreshed only if the lockType has been upgraded from NONE.null
if no result was found.LockTimeoutException
- if a record was found, but its lock could not be acquired within the positive
timeout
period specified.LockUnavailableException
- if a record was found and a no-wait lock type was specified, but the lock could
not be acquired immediately.PersistenceException
- if there was an error loading the DMO from the Hibernate
session and/or database.public Persistable quickLoad(RecordIdentifier ident) throws PersistenceException
ident
- Record identifier of the record to be loaded. Consists of the
primary key and the fully qualified DMO entity name.null
if no result was found.PersistenceException
- if there was an error creating a Hibernate session or getting
the requested record.public Persistable quickLoad(RecordIdentifier ident, boolean refresh) throws PersistenceException
ident
- Record identifier of the record to be loaded. Consists of the
primary key and the fully qualified DMO entity name.refresh
- If true
then re-read the state of the record from
the underlying database. This is useful when record has been
changed bypassing Hibernate.null
if no result was found.PersistenceException
- if there was an error creating a Hibernate session or getting
the requested record.public int executeSQL(java.lang.String sql) throws PersistenceException
sql
- SQL statement text.-1
if the statement
did not complete normally.PersistenceException
- if any error occurs executing the statement.public int executeSQL(java.lang.String sql, java.lang.Object[] args) throws PersistenceException
sql
- SQL statement text.args
- The statement arguments.-1
if the statement
did not complete normally.PersistenceException
- if any error occurs executing the statement.public org.hibernate.ScrollableResults executeSQLQuery(java.lang.String sql) throws PersistenceException
It is the responsibility of the calling code to close the returned
result set. In addition, if this method is called outside of a database
transaction, the caller must invoke pushImplicitTransaction()
before calling this method and popImplicitTransaction(Context)
after
fully processing the result set returned by this method. This will
ensure a transaction is opened and properly closed if necessary.
sql
- SQL query text.PersistenceException
- if any error occurs executing the statement.public org.hibernate.ScrollableResults executeSQLQuery(java.lang.String sql, java.lang.Object[] args) throws PersistenceException
It is the responsibility of the calling code to close the returned
result set. In addition, if this method is called outside of a database
transaction, the caller must invoke pushImplicitTransaction()
before calling this method and popImplicitTransaction(Context)
after
fully processing the result set returned by this method. This will
ensure a transaction is opened and properly closed if necessary.
sql
- SQL query text.args
- The query parameters.PersistenceException
- if any error occurs executing the statement.public org.hibernate.ScrollableResults executeSQLQuery(java.lang.String sql, java.lang.Object[] args, java.lang.String[] entities, boolean noFlush) throws PersistenceException
It is the responsibility of the calling code to close the returned
result set. In addition, if this method is called outside of a database
transaction, the caller must invoke pushImplicitTransaction()
before calling this method and popImplicitTransaction(Context)
after
fully processing the result set returned by this method. This will
ensure a transaction is opened and properly closed if necessary.
sql
- SQL query text.args
- The query parameters.entities
- Array of entity names involved in the SQL operation represented by this
statement, or null
to check whether a flush is required for
any entity type.noFlush
- If true
, flushing is bypassed.PersistenceException
- if any error occurs executing the statement.public java.lang.Object getSingleSQLResult(java.lang.String sql, java.lang.Object[] args, java.lang.String entity, boolean noFlush) throws PersistenceException
An implicit transaction will be opened, if an explicit one does not already exist. The result set and statement are closed immediately; no additional cleanup is required by the caller.
sql
- SQL statement to execute.args
- Query substitution parameters, if any. If present, these should match the number
of placeholders in the SQL statement. If not present, this argument may either be
null
or an empty array.entity
- Entity associated with the SQL statement, if any. Used to check whether a session
flush is needed before execution.noFlush
- If true
, flushing is bypassed.PersistenceException
- if any error occurs, either during the statement's execution, or when pushing or
popping an implicit transaction.public void executeSQLBatch(java.util.List<java.lang.String> sql, java.lang.String[] entities, boolean noFlush) throws PersistenceException
sql
- List of SQL statements to execute in batch.entities
- Array of entity names involved in the SQL operation represented by the batched
statements, or null
to check whether a flush is required for
any entity type.noFlush
- If true
, flushing is bypassed.PersistenceException
- if any error occurs executing the statements.public void lock(LockType lockType, RecordIdentifier ident, boolean update) throws LockUnavailableException
In the no-wait case, an exception is raised indicating that the lock is not available.
The current thread continues normally once the lock is obtained.
A lock currently held can be released by specifying LockType.NONE
for the
lockType
parameter.
The normal return of this method indicates that the lock request (or lack thereof) completed successfully, and that the current context now holds a lock of the requested type.
NOTE: legacy persistence framework code should access this method only via a RecordLockContext
method, unless simply testing whether a lock is available (i.e.,
update == false
). This ensures that record locks shared across record buffers
within a client context are managed properly. Non-legacy code may access this API
directly.
lockType
- Type of lock to be obtained. LockType.NONE
is used to release an existing
lock, and to continue with no lock.ident
- ID which uniquely identifies the record being locked.update
- true
if the lock state for the current record should be updated;
else false
.LockUnavailableException
- if a "no-wait" lock cannot be acquired immediately.getRecordLockContext()
public void lock(LockType lockType, RecordIdentifier ident, boolean update, long timeout) throws LockUnavailableException
In the no-wait case, an exception is raised indicating that the lock is not available. In the timeout case, an exception is raised indicating that the timeout period elapsed.
The current thread continues normally once the lock is obtained.
A lock currently held can be released by specifying LockType.NONE
for the
lockType
parameter.
The normal return of this method indicates that the lock request (or lack thereof) completed successfully, and that the current context now holds a lock of the requested type.
NOTE: legacy persistence framework code should access this method only via a RecordLockContext
method, unless simply testing whether a lock is available (i.e.,
update == false
). This ensures that record locks shared across record buffers
within a client context are managed properly. Non-legacy code may access this API
directly.
lockType
- Type of lock to be obtained. LockType.NONE
is used to release an existing
lock, and to continue with no lock.ident
- ID which uniquely identifies the record being locked.update
- true
if the lock state for the current record should be updated;
else false
.timeout
- Number of milliseconds to wait to acquire the requested lock type.
Throws LockTimeoutException
if this time elapses before the
lock is acquired. Specify 0 to wait indefinitely for the lock. Ignored
if lockType
is NONE
.LockTimeoutException
- if a lock cannot be acquired within the positive timeout
period specified.LockUnavailableException
- if a "no-wait" lock cannot be acquired immediately.getRecordLockContext()
public LockType lockTable(java.lang.String table, LockType lockType, boolean update) throws LockUnavailableException
A lock currently held can be released by specifying
LockType.NONE
for the lockType
parameter.
Method returns previous lock type (so that calling code knows what to set it back to after bulk delete). The normal return of this method indicates that the lock request (or lack thereof) completed successfully, and that the current context now holds a lock of the requested type.
table
- Table name.lockType
- Type of lock to be obtained. LockType.NONE
is used to release an
existing lock, and to continue with no lock.update
- true
if the lock state for the current table should be updated;
else false
.LockUnavailableException
- if a "no-wait" lock cannot be acquired immediately.public LockType queryLock(RecordIdentifier ident)
This method will always return the non-NO_WAIT
variants of a lock type. That is, even if the actual lock type is
LockType.EXCLUSIVE_NO_WAIT
or
LockType.SHARE_NO_WAIT
, the simpler types of
LockType.EXCLUSIVE
and LockType.SHARE
,
respectively, are returned. The lack of a lock returns
LockType.NONE
rather than null
.
ident
- ID which uniquely identifies the record being queried.null
.public java.io.Serializable nextPrimaryKey(java.lang.String table) throws PersistenceException
table
- Table for which next primary key will be returned.PersistenceException
- if there is an error determining the next primary key ID.java.lang.IllegalStateException
- if identity manager was not initialized.public void save(Persistable dmo, java.io.Serializable id) throws PersistenceException
dmo
- DMO to be persisted.id
- Primary key to associate with the persisted DMO.PersistenceException
- if a problem occurs saving the object in the current session.public Persistable merge(Persistable dmo) throws PersistenceException
Session.merge(Object)
for more
information.dmo
- DMO to merge.PersistenceException
public org.hibernate.Session getSession()
public void attach(java.lang.Object object) throws PersistenceException
object
- DMO to be persisted.PersistenceException
- if a problem occurs attaching the object to the current
session.public void detach(java.lang.Object object) throws PersistenceException
object
- Persistent entity to be evicted from the session.PersistenceException
- if a problem occurs evicting the object from the current
session.public void cleanup()
public void delete(java.lang.Object object) throws PersistenceException
object
- Persistent entity to be deleted.PersistenceException
- if a problem occurs deleting the object.public int deleteOrUpdate(java.lang.String hql, java.lang.Object[] values, org.hibernate.type.Type[] types, java.lang.String entity) throws PersistenceException
This action must take place within a database transaction, so this method attempts to begin one and commit it, if one is not already active.
This method should only be used for temp-tables (where an exclusive lock is irrelevant) or in cases where the current context already holds locks on all records which meet the specified criteria.
hql
- Query string which defines the criteria which determine which
records are deleted or updated.values
- Query substitution parameters, if any.types
- Types of the query substitution parameters, if any.entity
- Entity associated with the HQL statement, if any. Used to check whether a session
flush is needed before execution.PersistenceException
- if a problem occurs performing the bulk delete or update.public boolean beginTransaction() throws PersistenceException
true
if a new transaction was begun;
false
if there was already an active transaction.PersistenceException
- if there is an error beginning the new transaction.public void commit() throws PersistenceException
java.lang.IllegalStateException
- if no transaction is active in the current session; this
represents a programming error.PersistenceException
- if there is an error committing the transaction.public void rollback() throws PersistenceException
java.lang.IllegalStateException
- if no transaction is active in the current session; this
represents a programming error.PersistenceException
- if there is an error rolling back the transaction.public int pushImplicitTransaction() throws PersistenceException
PersistenceException
- if there is an error beginning a new transaction.public int popImplicitTransaction(Persistence.Context local)
local
- Cached context. If null
, will use {code get()} to obtain it.public void flushBatch() throws PersistenceException
This request bypasses the current client context's setting as to whether flushing is enabled.
It is expected that this method will only be called within an active transaction. If no session is active, this method will raise an exception.
java.lang.IllegalStateException
- if no session currently is active.PersistenceException
- if an error occurs during session flush.public void flush() throws PersistenceException
This request bypasses the current client context's setting as to whether flushing is enabled.
It is expected that this method will only be called within an active transaction. If no session is active, this method will raise an exception.
java.lang.IllegalStateException
- if no session currently is active.PersistenceException
- if an error occurs during session flush.public boolean isTransactionOpen()
true
if open, else false
.public java.lang.String message(java.lang.String message)
message
- Core messagepublic RecordLockContext getRecordLockContext()
persist
package and its sub-packages.protected void initializeInstance()
protected LockManager createLockManager() throws java.lang.IllegalAccessException, java.lang.InstantiationException, java.lang.ClassNotFoundException
InMemoryLockManager
.java.lang.IllegalAccessException
- if the LockManager
concrete implementation's default constructor
cannot be accessed.java.lang.InstantiationException
- if the LockManager
concrete implementation cannot be instantiated.java.lang.ClassNotFoundException
- if the LockManager
concrete implementation class cannot be located.java.lang.IllegalArgumentException
- if lock metadata is used by the current application, but no lock table updater is
found for the current database.protected IdentityManager createIdentityManager() throws java.lang.ClassNotFoundException, java.lang.IllegalAccessException, java.lang.InstantiationException
DEFAULT_IDENTITY_MANAGER
.null
if given
database is temporary.java.lang.IllegalAccessException
- if the IdentityManager
concrete implementation's
default constructor cannot be accessed.java.lang.InstantiationException
- if the IdentityManager
concrete implementation
cannot be instantiated.java.lang.ClassNotFoundException
- if the IdentityManager
concrete implementation
class cannot be located.boolean isTemporary()
true
if temporary, else false
.boolean beginTransaction(Persistence.Context local) throws PersistenceException
local
- User context.true
if a new transaction was begun;
false
if there was already an active transaction.PersistenceException
- if there is an error beginning the new transaction.void commit(Persistence.Context local) throws PersistenceException
local
- User context.java.lang.IllegalStateException
- if no transaction is active in the current session; this
represents a programming error.PersistenceException
- if there is an error committing the transaction.void rollback(Persistence.Context local) throws PersistenceException
local
- User context.java.lang.IllegalStateException
- if no transaction is active in the current session; this
represents a programming error.PersistenceException
- if there is an error rolling back the transaction.int executeSQL(java.lang.String sql, java.lang.Object[] args, java.lang.String[] entities, boolean noFlush) throws PersistenceException
sql
- SQL statement text.args
- The statement arguments.entities
- Array of entity names involved in the SQL operation represented by this
statement, or null
to check whether a flush is required for
any entity type.noFlush
- If true
, flushing is bypassed.-1
if the statement
did not complete normally.PersistenceException
- if any error occurs executing the statement.void enableTransactionTrace(boolean enable)
enable
- true
to enable; false
to disable.java.lang.Throwable getBeginTxTrace()
enableTransactionTrace(boolean)
, or this method
always will return null
.Throwable
containing stack trace from last transaction start, or
null
.void shareLockTableUpdater(Database database) throws PersistenceException
Persistence
instance associated with the given,
primary database.database
- Primary database presumably associated with the metadata database represented by
this object.PersistenceException
- if this object is not associated with a metadata database or the given database is
not a primary database.java.sql.Connection checkOutConnection() throws PersistenceException
Note: the caller must not call close()
on the returned
connection, since the connection may be "borrowed" from the current,
active session; rather, checkInConnection(Connection)
must be
used.
PersistenceException
- if a session cannot be created.checkInConnection(Connection)
void checkInConnection(java.sql.Connection connection) throws PersistenceException
checkOutConnection()
. This will close the connection if it is not
otherwise in use in the current, context local session.connection
- JDBC connection which is no longer needed by the caller.PersistenceException
- if there is an error closing the session associated with the
connection.Persistence.Context getContext()
NOTE: this method is package private and should remain so. It is meant to allow optimized calls to certain frequently used methods of this class, in order to avoid the overhead of an unnecessary context local lookup.
org.hibernate.Session bind(Persistence.Context local) throws PersistenceException
This is the only method in this class which exposes the Hibernate session to the outside world. Because of this, this method is intentionally package private. Use with care.
local
- User context.PersistenceException
- if an error occurs creating a session.void evict(Persistence.Context local, Persistable dmo)
local
- Persistence context.dmo
- Data model object to be evicted.void evict(java.util.Collection<Persistable> evictees)
evictees
- Collection of DMOs to be evicted.void maybeFlush() throws PersistenceException
PersistenceException
- if there is any error flushing the session.void registerSessionListener(SessionListener listener, SessionListener.Scope scope)
SessionListener
to receive session life
cycle event notifications. The listener will be deregistered
according to the following rules at the earlier of:
scope
parameter:
ENCLOSING_EXTERNAL_SCOPE
CURRENT_SCOPE
NEXT_EXTERNAL_SCOPE
listener
- Session listener to be registered.scope
- SessionListener.Scope
enum indicating the scope to
which this listener should be registered. When the scope ends,
the listener is deregistered as described above.void deregisterSessionListener(SessionListener listener)
listener
- Listener to deregister.void uniqueResultViolation(RecordBuffer buffer, java.lang.Exception exc) throws PersistenceException
buffer
- Record buffer associated with the failed query.exc
- Optional root cause exception.PersistenceException
- always; indicates the nature of the error.private void flush(boolean clear) throws PersistenceException
It is expected that this method will only be called within an active transaction. If no session is active, this method will raise an exception.
clear
- true
to clear the session (used during bulk
inserts or updates to prevent a progressive memory leak) after
the flush.PersistenceException
- if no session currently is active or if an error occurs during
session flush.private void flush(Persistence.Context local, org.hibernate.Session session, boolean clear) throws PersistenceException
local
- Context-local state.session
- Hibernate sessionclear
- true
to clear the session (used during bulk
inserts or updates to prevent a progressive memory leak) after
the flush.PersistenceException
- if an error occurs during session flush.private void preprocessQueryParameters(java.lang.Object[] args)
character
. Any
parameter affected is replaced with a new character
instance at the same index position within args
.
date
instance at the same index position within args
.
Note: this method has special processing for null
bytes
embedded in character
variables. The text of the variable
is truncated starting at the first embedded null
byte.
This means that the resulting substitution parameters are guaranteed
to never include null
bytes.
args
- Array of query substitution parameters or null
if
none.private boolean checkReadOnly(java.lang.String[] entities)
entities
- DMO entity names to check, or null
.false
if entities
is null
or if any entity represents a
non-read-only table, else true
.private org.hibernate.Query getQuery(Persistence.Context local, java.lang.String hql, int maxResults, int startOffset, java.lang.Object[] values, org.hibernate.type.Type[] types, boolean readOnly) throws PersistenceException
local
- Context-local state.hql
- HQL query string.maxResults
- The maximum number of results to be returned by the query.
If this value is non-positive, no upper limit is applied.startOffset
- The 0-based offset of the first record to retrieve. If this
value is non-positive, an offset of 0 is used by default.values
- Substitution values for the query. If none, this should be an
empty array.types
- Hibernate types for the values
array. If none,
this should be an empty array.readOnly
- true
to prepare the query in read-only mode, else
false
.PersistenceException
- if there was an error creating a Hibernate session.private void handleException(java.lang.String message, org.hibernate.HibernateException exc) throws PersistenceException
PersistenceException
.message
- Error text for the exception.exc
- A Hibernate exception which may or may not represent an unrecoverable database
error.StopConditionException
- if the error is unrecoverable.PersistenceException
- if the error is likely recoverable.