com.goldencode.p2j.persist

Interface UnsafePersistence

All Known Implementing Classes:

Persistence, RemotePersistence

public interface UnsafePersistence

Interface used for unsafe persistence instances. An unsafe persistence is used for running SQL code directly inside the FWD engine without handling any kind of exception that occurs. All exceptions must be handled by the context in which it used. The implementation can be found in Persistence, using the unsafe variant will just make different choices during execution.

Method Summary

Modifier and Type	Method and Description
void	commit() Commit the current database transaction and close the current session.
void	delete(Record dmo) Delete the persisted object from the specified database.
int	deleteOrUpdate(java.lang.String fql, java.lang.Object[] values, java.lang.String entity, boolean noUndo) Perform a bulk delete or update of all objects which meet the specified criteria.
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.
int	executeSQL(java.lang.String sql, java.lang.Object[] args, boolean noUndo) Execute an arbitrary SQL statement which does not produce a result set.
void	executeSQLBatch(Persistence.Context local, java.util.List<java.lang.String> sql, boolean noFlush) Execute an arbitrary list of standard JDBC statements in batch.
void	executeSQLBatch(java.lang.String sql, java.util.function.Supplier<java.lang.Object[]> getArgs) Execute a batch SQL statement, while the argument supplier returns non-null values.
<T> ScrollableResults<T>	executeSQLQuery(java.lang.String sql, java.lang.Object[] args) Execute an arbitrary SQL query.
void	flush() Flush the current session, which synchronizes the in-memory state of DMOs to the database.
<T> T	getSingleSQLResult(java.lang.String sql, java.lang.Object[] args) Convenience method to retrieve a single result from a SQL statement.
<T> java.util.List<T>	list(java.lang.String[] entities, java.lang.String fql, java.lang.Object[] values, int maxResults, int startOffset, boolean hydrateRecords) Execute an FQL query and return the results as a list.
<T> java.util.List<T>	list(java.lang.String[] entities, java.lang.String fql, java.lang.Object[] values, int maxResults, int startOffset, DataRelation relation, boolean hydrateRecords) Execute an FQL query and return the results as a list.
<T> java.util.List<T>	list(java.lang.String fql, java.lang.Object[] values, int maxResults, int startOffset) Execute an FQL query and return the results as a list.
<T> java.util.List<T>	list(java.lang.String fql, java.lang.Object[] values, int maxResults, int startOffset, DataRelation relation) Execute an FQL query and return the results as a list.
Record	load(java.lang.Class<? extends Record> implClass, java.lang.Long id, LockType lockType, long timeout, boolean updateLock) Load a single record from the session-level cache or, optionally, refresh it from the database.
Record	load(java.lang.Class<? extends Record> implClass, java.lang.Long id, LockType lockType, long timeout, boolean updateLock, java.util.BitSet partialFields) Load a single record from the session-level cache or, optionally, refresh it from the database.
Record	load(RecordBuffer buffer, java.lang.String fql, java.lang.Object[] values, LockType lockType, long timeout, boolean unique, boolean updateLock, boolean forceRefresh, boolean findByKey) Execute an FQL query and load a single record from the session-level cache or, optionally, refresh it from the database.
Record	quickLoad(RecordIdentifier<java.lang.String> ident) Load a single record from the database or from the session-level cache.
Record	quickLoad(RecordIdentifier<java.lang.String> ident, boolean refresh) Load a single record from the database or from the session-level cache.
void	rollback() Roll back the current database transaction and close the current session.
void	save(Record dmo) Updates the existing record in the backing database session.
void	save(Record dmo, java.lang.Long id) Persist the specified object to the backing database session, using the given ID.
void	save(Record dmo, java.lang.Long id, boolean updateDmoState) Persist the specified object to the backing database session, using the given ID.
<T> ScrollableResults<T>	scroll(java.lang.String[] entities, java.lang.String fql, java.lang.Object[] values, int maxResults, int startOffset, DataRelation relation, int scrollMode) Execute an FQL query and get a scrollable cursor on the result set.
<T> ScrollableResults<T>	scroll(java.lang.String[] entities, java.lang.String fql, java.lang.Object[] values, int maxResults, int startOffset, DataRelation relation, int scrollMode, boolean lazyMode) Execute an FQL query and get a scrollable cursor on the result set.
<T> ScrollableResults<T>	scroll(java.lang.String[] entities, java.lang.String fql, java.lang.Object[] values, int maxResults, int startOffset, int scrollMode) Execute an FQL query and get a scrollable cursor on the result set.
<T> ScrollableResults<T>	scroll(java.lang.String[] entities, java.lang.String fql, java.lang.Object[] values, int maxResults, int startOffset, int scrollMode, boolean lazyMode) Execute an FQL query and get a scrollable cursor on the result set.
<T> ScrollableResults<T>	scroll(java.lang.String fql, java.lang.Object[] values) Execute an FQL query and get a scrollable cursor on the result set.
<T> ScrollableResults<T>	scroll(java.lang.String fql, java.lang.Object[] values, DataRelation relation) Execute an FQL query and get a scrollable cursor on the result set.
<T> ScrollableResults<T>	scroll(java.lang.String fql, java.lang.Object[] values, int maxResults, int startOffset) Execute an FQL query and get a scrollable cursor on the result set.
<T> ScrollableResults<T>	scroll(java.lang.String fql, java.lang.Object[] values, int maxResults, int startOffset, DataRelation relation) Execute an FQL query and get a scrollable cursor on the result set.
<T> ScrollableResults<T>	scroll(java.lang.String fql, java.lang.Object[] values, int maxResults, int startOffset, DataRelation relation, int scrollMode) Execute an FQL query and get a scrollable cursor on the result set.
<T> ScrollableResults<T>	scroll(java.lang.String fql, java.lang.Object[] values, int maxResults, int startOffset, int scrollMode) Execute an FQL query and get a scrollable cursor on the result set.

Method Detail

executeSQL

int executeSQL(java.lang.String sql)
        throws PersistenceException

Execute an arbitrary SQL statement which does not produce a result set.

Parameters:

sql - SQL statement text.

Returns:

The number of entities updated or deleted, or -1 if the statement did not complete normally.

Throws:

PersistenceException - if any error occurs executing the statement.

executeSQL

int executeSQL(java.lang.String sql,
               java.lang.Object[] args)
        throws PersistenceException

Execute an arbitrary SQL statement which does not produce a result set.
Note: Do not forget to invalidate the index-based cache (FastFindCache) of each buffer affected by this statement. This cannot be done here because the method is not aware of the buffer list and if multiple SQL statements are batch executed, then is better to issue a single invalidate command for all of then.

Parameters:

sql - SQL statement text.

args - The statement arguments.

Returns:

The number of entities updated or deleted, or -1 if the statement did not complete normally.

Throws:

PersistenceException - if any error occurs executing the statement.

executeSQL

int executeSQL(java.lang.String sql,
               java.lang.Object[] args,
               boolean noUndo)
        throws PersistenceException

Execute an arbitrary SQL statement which does not produce a result set.

Parameters:

sql - SQL statement text.

args - The statement arguments.

noUndo - If true, the update is on a NO-UNDO temp-table.

Returns:

The number of entities updated or deleted, or -1 if the statement did not complete normally.

Throws:

PersistenceException - if any error occurs executing the statement.

rollback

void rollback()
       throws PersistenceException

Roll back the current database transaction and close the current session. If the transaction cannot be rolled back, raise an error.

Throws:

PersistenceException - if there is an error rolling back the transaction.

scroll

<T> ScrollableResults<T> scroll(java.lang.String fql,
                                java.lang.Object[] values)
                         throws PersistenceException

Execute an FQL query and get a scrollable cursor on the result set. Records represented by the result set are not locked by this method. This method creates a new, context local ORM session if necessary.

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[], int, int, DataRelation, int) 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.

Parameters:

fql - FQL query statement.

values - Substitution values for the query. If none, this should be an empty array.

Returns:

An object which provides access to a scrollable cursor on the result set.

Throws:

PersistenceException - if there was an error executing the query.

scroll

<T> ScrollableResults<T> scroll(java.lang.String fql,
                                java.lang.Object[] values,
                                DataRelation relation)
                         throws PersistenceException

Execute an FQL query and get a scrollable cursor on the result set. Records represented by the result set are not locked by this method. This method creates a new, context local ORM session if necessary.

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[], int, int, DataRelation, int) 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.

Parameters:

fql - FQL query statement.

values - Substitution values for the query. If none, this should be an empty array.

relation - The recursive DATA-RELATION the query is to FILL for.

Returns:

An object which provides access to a scrollable cursor on the result set.

Throws:

PersistenceException - if there was an error executing the query.

scroll

<T> ScrollableResults<T> scroll(java.lang.String fql,
                                java.lang.Object[] values,
                                int maxResults,
                                int startOffset)
                         throws PersistenceException

Execute an FQL query and get a scrollable cursor on the result set. Records represented by the result set are not locked by this method. This method creates a new, context local ORM session if necessary.

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[], int, int, DataRelation, int) 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.

Parameters:

fql - FQL query statement.

values - Substitution values for the query. 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.

Returns:

An object which provides access to a scrollable cursor on the result set.

Throws:

PersistenceException - if there was an error executing the query.

scroll

<T> ScrollableResults<T> scroll(java.lang.String[] entities,
                                java.lang.String fql,
                                java.lang.Object[] values,
                                int maxResults,
                                int startOffset,
                                DataRelation relation,
                                int scrollMode,
                                boolean lazyMode)
                         throws PersistenceException

Execute an FQL query and get a scrollable cursor on the result set. Records represented by the result set are not locked by this method.

Parameters:

entities - Names of the DMO entities associated with this query statement (Unused parameter).

fql - FQL query statement to be parsed and executed by ORM framework.

values - Substitution values for the query. 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.

relation - The recursive DATA-RELATION the query is to FILL for.

scrollMode - Scroll mode which should apply to the result set.

lazyMode - Flag that indicates whether the query should be executed in a lazy manner.

Returns:

An object which provides access to a scrollable cursor on the result set.

Throws:

PersistenceException - if there was an error executing the query.

scroll

<T> ScrollableResults<T> scroll(java.lang.String fql,
                                java.lang.Object[] values,
                                int maxResults,
                                int startOffset,
                                DataRelation relation)
                         throws PersistenceException

Execute an FQL query and get a scrollable cursor on the result set. Records represented by the result set are not locked by this method. This method creates a new, context local ORM session if necessary.

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[], int, int, DataRelation, int) 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.

Parameters:

fql - FQL query statement.

values - Substitution values for the query. 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.

relation - The recursive DATA-RELATION the query is to FILL for.

Returns:

An object which provides access to a scrollable cursor on the result set.

Throws:

PersistenceException - if there was an error executing the query.

scroll

<T> ScrollableResults<T> scroll(java.lang.String fql,
                                java.lang.Object[] values,
                                int maxResults,
                                int startOffset,
                                int scrollMode)
                         throws PersistenceException

Execute an FQL query and get a scrollable cursor on the result set. Records represented by the result set are not locked by this method. This method creates a new, context local ORM session if necessary.

Parameters:

fql - FQL query statement.

values - Substitution values for the query. 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.

Returns:

An object which provides access to a scrollable cursor on the result set.

Throws:

PersistenceException - if there was an error executing the query.

scroll

<T> ScrollableResults<T> scroll(java.lang.String fql,
                                java.lang.Object[] values,
                                int maxResults,
                                int startOffset,
                                DataRelation relation,
                                int scrollMode)
                         throws PersistenceException

Execute an FQL query and get a scrollable cursor on the result set. Records represented by the result set are not locked by this method. This method creates a new, context local ORM session if necessary.

Parameters:

fql - FQL query statement.

values - Substitution values for the query. 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.

relation - The recursive DATA-RELATION the query is to FILL for.

scrollMode - Scroll mode which should apply to the result set.

Returns:

An object which provides access to a scrollable cursor on the result set.

Throws:

PersistenceException - if there was an error executing the query.

scroll

<T> ScrollableResults<T> scroll(java.lang.String[] entities,
                                java.lang.String fql,
                                java.lang.Object[] values,
                                int maxResults,
                                int startOffset,
                                int scrollMode)
                         throws PersistenceException

Execute an FQL query and get a scrollable cursor on the result set. Records represented by the result set are not locked by this method.

Parameters:

entities - Names of the DMO entities associated with this query statement (Unused parameter).

fql - FQL query statement to be parsed and executed by ORM framework.

values - Substitution values for the query. 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.

Returns:

An object which provides access to a scrollable cursor on the result set.

Throws:

PersistenceException - if there was an error executing the query.

scroll

<T> ScrollableResults<T> scroll(java.lang.String[] entities,
                                java.lang.String fql,
                                java.lang.Object[] values,
                                int maxResults,
                                int startOffset,
                                DataRelation relation,
                                int scrollMode)
                         throws PersistenceException

Execute an FQL query and get a scrollable cursor on the result set. Records represented by the result set are not locked by this method.

Parameters:

entities - Names of the DMO entities associated with this query statement (Unused parameter).

fql - FQL query statement to be parsed and executed by ORM framework.

values - Substitution values for the query. 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.

relation - The recursive DATA-RELATION the query is to FILL for.

scrollMode - Scroll mode which should apply to the result set.

Returns:

An object which provides access to a scrollable cursor on the result set.

Throws:

PersistenceException - if there was an error executing the query.

scroll

<T> ScrollableResults<T> scroll(java.lang.String[] entities,
                                java.lang.String fql,
                                java.lang.Object[] values,
                                int maxResults,
                                int startOffset,
                                int scrollMode,
                                boolean lazyMode)
                         throws PersistenceException

Execute an FQL query and get a scrollable cursor on the result set. Records represented by the result set are not locked by this method.

Parameters:

entities - Names of the DMO entities associated with this query statement (Unused parameter).

fql - FQL query statement to be parsed and executed by ORM framework.

values - Substitution values for the query. 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.

lazyMode - Flag that indicates whether the query should be executed in a lazy manner.

Returns:

An object which provides access to a scrollable cursor on the result set.

Throws:

PersistenceException - if there was an error executing the query.

list

<T> java.util.List<T> list(java.lang.String fql,
                           java.lang.Object[] values,
                           int maxResults,
                           int startOffset)
                    throws PersistenceException

Execute an FQL query and return the results as a list. If the query returns multiple results per row, each element in the list will be an array of Objects.

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[], int, int, DataRelation, int) 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.

This overloaded variant always attempts to hydrate and return the result as Records.

Parameters:

fql - FQL query statement.

values - Substitution values for the query. 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.

Returns:

A list of results, or null if no result was found.

Throws:

PersistenceException - if there was an error executing the query.

list

<T> java.util.List<T> list(java.lang.String fql,
                           java.lang.Object[] values,
                           int maxResults,
                           int startOffset,
                           DataRelation relation)
                    throws PersistenceException

Execute an FQL query and return the results as a list. If the query returns multiple results per row, each element in the list will be an array of Objects.

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[], int, int, DataRelation, int) 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.

This overloaded variant always attempts to hydrate and return the result as Records.

Parameters:

fql - FQL query statement.

values - Substitution values for the query. 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.

relation - The recursive DATA-RELATION the query is to FILL for.

Returns:

A list of results, or null if no result was found.

Throws:

PersistenceException - if there was an error executing the query.

list

<T> java.util.List<T> list(java.lang.String[] entities,
                           java.lang.String fql,
                           java.lang.Object[] values,
                           int maxResults,
                           int startOffset,
                           boolean hydrateRecords)
                    throws PersistenceException

Execute an FQL query and return the results as a list. If the query returns multiple results per row, each element in the list will be an array of Objects.

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[], int, int, DataRelation, int) 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.

Type Parameters:

T - Type of object being listed.

Parameters:

entities - Names of the DMO entities associated with this query statement (Unused parameter).

fql - FQL query statement to be processed. 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.

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.

hydrateRecords - If true the result is interpreted as legacy records, and they will be hydrated. Otherwise, the returned List contains an array of Java objects for each row.

Returns:

A list of results, or null if no result was found.

Throws:

PersistenceException - if there was an error executing the query.

list

<T> java.util.List<T> list(java.lang.String[] entities,
                           java.lang.String fql,
                           java.lang.Object[] values,
                           int maxResults,
                           int startOffset,
                           DataRelation relation,
                           boolean hydrateRecords)
                    throws PersistenceException

Execute an FQL query and return the results as a list. If the query returns multiple results per row, each element in the list will be an array of Objects.

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[], int, int, DataRelation, int) 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.

Type Parameters:

T - Type of object being listed.

Parameters:

entities - Names of the DMO entities associated with this query statement (Unused parameter).

fql - FQL query statement to be processed. 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.

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.

relation - The recursive DATA-RELATION the query is to FILL for.

hydrateRecords - If true the result is interpreted as legacy records, and they will be hydrated. Otherwise, the returned List contains an array of Java objects for each row.

Returns:

A list of results, or null if no result was found.

Throws:

PersistenceException - if there was an error executing the query.

load

Record load(RecordBuffer buffer,
            java.lang.String fql,
            java.lang.Object[] values,
            LockType lockType,
            long timeout,
            boolean unique,
            boolean updateLock,
            boolean forceRefresh,
            boolean findByKey)
     throws PersistenceException

Execute an FQL query and load a single record from the session-level cache or, optionally, refresh it from the database. The record will be locked with the specified lock type upon return from this method. Note that the lock refers to a runtime-level lock, not a database-level lock. The record is not automatically loaded into the record buffer provided. The buffer argument is used only to extract information needed to perform the query.

Parameters:

buffer - Record buffer which holds information about the DMO class type and name of the table being queried.

fql - FQL query statement. 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.

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.

Returns:

A single DMO instance representing the query result, or null if no result was found.

Throws:

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,

load

Record load(java.lang.Class<? extends Record> implClass,
            java.lang.Long id,
            LockType lockType,
            long timeout,
            boolean updateLock)
     throws PersistenceException,
            LockTimeoutException

Load a single record from the session-level cache or, optionally, refresh it from the database. The record will be locked with the specified lock type upon return from this method. Note that the lock refers to a runtime-level lock, not a database-level lock.

Parameters:

implClass - The 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.

Returns:

A single DMO instance loaded from the database, or null if no result was found.

Throws:

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 ORM session and/or database.

load

Record load(java.lang.Class<? extends Record> implClass,
            java.lang.Long id,
            LockType lockType,
            long timeout,
            boolean updateLock,
            java.util.BitSet partialFields)
     throws PersistenceException,
            LockTimeoutException

Load a single record from the session-level cache or, optionally, refresh it from the database. The record will be locked with the specified lock type upon return from this method. Note that the lock refers to a runtime-level lock, not a database-level lock.

Parameters:

implClass - The 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.

partialFields - For an incomplete record, read only these fields.

Returns:

A single DMO instance loaded from the database, or null if no result was found.

Throws:

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 ORM session and/or database.

quickLoad

Record quickLoad(RecordIdentifier<java.lang.String> ident)
          throws PersistenceException

Load a single record from the database or from the session-level cache. No locking is attempted, the assumption being that any required lock previously was acquired.

Parameters:

ident - Record identifier of the record to be loaded. Consists of the primary key and the fully qualified DMO entity name.

Returns:

A single DMO instance loaded from the database, or null if no result was found.

Throws:

PersistenceException - if there was an error creating an ORM session or getting the requested record.

quickLoad

Record quickLoad(RecordIdentifier<java.lang.String> ident,
                 boolean refresh)
          throws PersistenceException

Load a single record from the database or from the session-level cache. No locking is attempted, the assumption being that any required lock previously was acquired.

Parameters:

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 the FWD ORM.

Returns:

A single DMO instance loaded from the database, or null if no result was found.

Throws:

PersistenceException - if there was an error creating an ORM session or getting the requested record.

executeSQLQuery

<T> ScrollableResults<T> executeSQLQuery(java.lang.String sql,
                                         java.lang.Object[] args)
                                  throws PersistenceException

Execute an arbitrary SQL query.

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 should optionally invoke Persistence.beginTransaction() before calling this method and Persistence.commit() or Persistence.rollback() after fully processing the result set returned by this method. This will ensure a transaction is opened and properly closed if necessary.

Parameters:

sql - SQL query text.

args - The query parameters.

Returns:

Result set produced by query.

Throws:

PersistenceException - if any error occurs executing the statement.

getSingleSQLResult

<T> T getSingleSQLResult(java.lang.String sql,
                         java.lang.Object[] args)
                  throws PersistenceException

Convenience method to retrieve a single result from a SQL statement. This is intended to be used for SQL statements that return only one result. Only the first result is checked; if there is more than one in the result set, all but the first are ignored.

The result set and statement are closed immediately; no additional cleanup is required by the caller.

Parameters:

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.

Returns:

The first (and presumably only) result returned by the SQL statement.

Throws:

PersistenceException - if any error occurs, either during the statement's execution, or when pushing or popping an implicit transaction.

save

void save(Record dmo)
   throws PersistenceException

Updates the existing record in the backing database session. It is assumed this method will be invoked only within a database transaction.

Parameters:

dmo - DMO to be persisted.

Throws:

PersistenceException - if a problem occurs saving the object in the current session.

save

void save(Record dmo,
          java.lang.Long id)
   throws PersistenceException

Persist the specified object to the backing database session, using the given ID. It is assumed this method will be invoked only within a database transaction.

Parameters:

dmo - DMO to be persisted.

id - Primary key to associate with the persisted DMO.

Throws:

PersistenceException - if a problem occurs saving the object in the current session.

save

void save(Record dmo,
          java.lang.Long id,
          boolean updateDmoState)
   throws PersistenceException

Persist the specified object to the backing database session, using the given ID. It is assumed this method will be invoked only within a database transaction.

Parameters:

dmo - DMO to be persisted.

id - Primary key to associate with the persisted DMO.

updateDmoState - true to update the record state of the DMO. Should be false for non-legacy use cases).

Throws:

PersistenceException - if a problem occurs saving the object in the current session.

delete

void delete(Record dmo)
     throws PersistenceException

Delete the persisted object from the specified database.

Parameters:

dmo - Persistent entity to be deleted.

Throws:

PersistenceException - if a problem occurs deleting the object.

deleteOrUpdate

int deleteOrUpdate(java.lang.String fql,
                   java.lang.Object[] values,
                   java.lang.String entity,
                   boolean noUndo)
            throws PersistenceException

Perform a bulk delete or update of all objects which meet the specified criteria. The criteria must indicate a single DMO type only.

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.

Parameters:

fql - Query string which defines the criteria which determine which records are deleted or updated.

values - Query substitution parameters, if any.

entity - Entity associated with the FQL statement, if any. Used to check whether a session flush is needed before execution.

noUndo - true if this operation is being performed on a NO-UNDO temp-table, else false.

Returns:

The number of entities deleted or updated.

Throws:

PersistenceException - if a problem occurs performing the bulk delete or update.

executeSQLBatch

void executeSQLBatch(java.lang.String sql,
                     java.util.function.Supplier<java.lang.Object[]> getArgs)
              throws PersistenceException

Execute a batch SQL statement, while the argument supplier returns non-null values.

Parameters:

sql - The SQL statement to execute.

getArgs - The argument supplier.

Throws:

PersistenceException

executeSQLBatch

void executeSQLBatch(Persistence.Context local,
                     java.util.List<java.lang.String> sql,
                     boolean noFlush)
              throws PersistenceException

Execute an arbitrary list of standard JDBC statements in batch.

Parameters:

local - Persistence context.

sql - List of SQL statements to execute in batch.

noFlush - If true, flushing is bypassed.

Throws:

PersistenceException - if any error occurs executing the statements.

flush

void flush()
    throws PersistenceException

Flush the current session, which synchronizes the in-memory state of DMOs to the database.

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.

Throws:

java.lang.IllegalStateException - if no session currently is active.

PersistenceException - if an error occurs during session flush.

commit

void commit()
     throws PersistenceException

Commit the current database transaction and close the current session. If the transaction cannot be committed, roll it back and raise an error.

Throws:

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.