org.sormula.operation.cascade.lazy
Class AbstractLazySelector<R>

java.lang.Object
  org.sormula.operation.cascade.lazy.AbstractLazySelector<R>

Type Parameters:

R - type of row class that is to be lazily selected

All Implemented Interfaces:

java.io.Serializable, LazySelectable

Direct Known Subclasses:

DurableLazySelector, SimpleLazySelector

public abstract class AbstractLazySelector<R>
extends java.lang.Object
implements LazySelectable, java.io.Serializable

Typical state and behavior for performing lazy select cascades. This class keeps track of fields with pending lazy selects and performs checkLazySelects(String) only once per lazy select field.

This class may be used as a super class of row that has a reference to a lazy select field or it may be used as a delegate when row requires a different super class.

Subclass must implement initDatabase() to create the Database to use for the lazy select. Usually pendingLazySelects(Database) is overridden to record information about the current Database to be used by initDatabase().

Since:

1.8 and 2.2

Author:

Jeff Miller

See Also:

Serialized Form

Constructor Summary

AbstractLazySelector()
Constructs for use when AbstractLazySelector is base class of row that will contain lazy select fields.

AbstractLazySelector(R source)
Constructs for use as delegate for row that will contain lazy select fields.

Method Summary

protected void	begin() Starts a transaction for lazySelect(Field).
void	checkLazySelects(java.lang.String fieldName) Checks if field should be selected.
protected abstract void	closeDatabase() Invoked by checkLazySelects(String) to close the Database instance that was used to perform the lazy selects.
protected void	commit() Commits the transaction for lazySelect(Field).
Database	getDatabase() Gets the database to use for lazy select.
java.util.Map<java.lang.String,java.lang.reflect.Field>	getPendingLazySelectFields() Gets the fields that will be initialized with lazy select.
R	getSource() Gets the owner of the field(s) that will be lazily selected.
protected Database	initDatabase() Deprecated.
protected void	initPendingLazySelectCascadeFields() Initializes map of all fields that have a lazy select.
boolean	isLocalTransaction() Reports if this class has created a transaction for use when performing a lazy select.
boolean	isPendingLazySelects() Reports lazy select status.
boolean	isUseTransaction() Reports if a transaction will be created if needed.
protected void	lazySelect(java.lang.reflect.Field field) Performs lazy select for all select cascades of field where SelectCascade.lazy() is true.
protected abstract void	openDatabase() Invoked by checkLazySelects(String) to create a Database instance that will be used to perform the lazy selects.
void	pendingLazySelects(Database database) Notifies selector that at least one field has lazy select to be performed.
protected void	rollback() Rolls back the transaction for lazySelect(Field).
void	setDatabase(Database database) Sets the database to use for lazy selects.
void	setUseTransaction(boolean useTransaction) Sets transaction use.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AbstractLazySelector

public AbstractLazySelector()

Constructs for use when AbstractLazySelector is base class of row that will contain lazy select fields. Typically the derived class is the one side of a one-to-many relationship or subclass has a reference to the other class in a one-to-one relationship. setUseTransaction(boolean) is true by default.

AbstractLazySelector

public AbstractLazySelector(R source)

Constructs for use as delegate for row that will contain lazy select fields. setUseTransaction(boolean) is true by default.

Parameters:

source - row that contains fields with SelectCascade.lazy() is true; typically source is the one side of a one-to-many relationship or source has a reference to the other class in a one-to-one relationship

Method Detail

initDatabase

@Deprecated
protected Database initDatabase()
                         throws LazyCascadeException

Deprecated.

Invoked once to create a Database instance that will be used to perform the lazy selects. The first time that getDatabase() is used, it will invoke initDatabase().

Returns:

a sormula database from which to select rows

Throws:

LazyCascadeException - if error

openDatabase

protected abstract void openDatabase()
                              throws LazyCascadeException

Invoked by checkLazySelects(String) to create a Database instance that will be used to perform the lazy selects.

Throws:

LazyCascadeException - if error

Since:

1.9 and 2.3

closeDatabase

protected abstract void closeDatabase()
                               throws LazyCascadeException

Invoked by checkLazySelects(String) to close the Database instance that was used to perform the lazy selects.

Throws:

LazyCascadeException

Since:

1.9 and 2.3

getSource

public R getSource()

Gets the owner of the field(s) that will be lazily selected.

Returns:

reference to this class if this class is a super class of row or source parameter if this class is a delegate selector for row

isUseTransaction

public boolean isUseTransaction()

Reports if a transaction will be created if needed. The default value is true.

Returns:

true if a transaction is to be created if none is active

setUseTransaction

public void setUseTransaction(boolean useTransaction)

Sets transaction use. If true and Database.getTransaction() reports false from Transaction.isActive(), meaning no transaction is active, then this class will create a transaction with begin() prior to performing the lazy selects.

Parameters:

useTransaction - true to create a transaction for lazy select if none is active; false to never create a transaction

See Also:

begin(), commit(), rollback()

isLocalTransaction

public boolean isLocalTransaction()

Reports if this class has created a transaction for use when performing a lazy select.

Returns:

true when a transaction was created by this class

getDatabase

public Database getDatabase()

Gets the database to use for lazy select.

Returns:

database to use for lazy select

setDatabase

public void setDatabase(Database database)

Sets the database to use for lazy selects.

Parameters:

database - lazy select database (typically created in openDatabase()

Since:

1.9 and 2.3

isPendingLazySelects

public boolean isPendingLazySelects()

Reports lazy select status. Set to true when pendingLazySelects(Database) is invoked. Set to false when checkLazySelects(String) determines that there are no more fields to select.

Returns:

true if one or more fields have lazy selects that have not been performed

getPendingLazySelectFields

public java.util.Map<java.lang.String,java.lang.reflect.Field> getPendingLazySelectFields()

Gets the fields that will be initialized with lazy select. Field map is initialized the first time that checkLazySelects(String) is invoked while isPendingLazySelects() is true.

Returns:

map of fields (key is field name); null if fields have not been initialized

pendingLazySelects

public void pendingLazySelects(Database database)
                        throws LazyCascadeException

Notifies selector that at least one field has lazy select to be performed. Subclasses typically save some information about the database that can be used by checkLazySelects(String) to perform the lazy select.

Specified by:

pendingLazySelects in interface LazySelectable

Parameters:

database - perform lazy selects from this database

Throws:

LazyCascadeException - if error

checkLazySelects

public void checkLazySelects(java.lang.String fieldName)
                      throws LazyCascadeException

Checks if field should be selected. If field is defined with a lazy select and the lazy select has not been performed, then lazySelect(Field) will be invoked to select the field. A field is selected only once.

Specified by:

checkLazySelects in interface LazySelectable

Parameters:

fieldName - name of field to select with lazy select

Throws:

LazyCascadeException - if error

lazySelect

protected void lazySelect(java.lang.reflect.Field field)
                   throws LazyCascadeException

Performs lazy select for all select cascades of field where SelectCascade.lazy() is true.

Parameters:

field - field to affect

Throws:

LazyCascadeException - if error

initPendingLazySelectCascadeFields

protected void initPendingLazySelectCascadeFields()
                                           throws LazyCascadeException

Initializes map of all fields that have a lazy select. Map is available with getPendingLazySelectFields().

Throws:

LazyCascadeException - if error

begin

protected void begin()
              throws SormulaException

Starts a transaction for lazySelect(Field). A transaction is used only if isUseTransaction() is true and the transaction for database is not already in use.

Throws:

SormulaException - if error

commit

protected void commit()
               throws SormulaException

Commits the transaction for lazySelect(Field). A transaction is committed only if begin() started a transaction as indicated by true from isLocalTransaction().

Throws:

SormulaException - if error

rollback

protected void rollback()
                 throws SormulaException

Rolls back the transaction for lazySelect(Field). A transaction is rolled back only if begin() started a transaction as indicated by true from isLocalTransaction().

Throws:

SormulaException - if error