com.boylesoftware.cb2
Class BLObject

java.lang.Object
  com.boylesoftware.cb2.BLObject

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

PropertySharedBLO, UserBLO

public abstract class BLObject

extends java.lang.Object

implements java.io.Serializable

Parent abstract class for Business Level Objects (the BLOs), that are software components in the CB2 architecture that represent various business entities and implement application's business logic.

This class provides API for BLO implementations as a set of protected methods. The public interface of a BLO implementation represents its business interface.

Version:

$Id: BLObject.java,v 1.5 2004/04/21 19:18:27 levahim Exp $

Author:

Lev Himmelfarb

See Also:

BLManager, BLOContainer, Serialized Form

Field Summary

protected BLOContainer	bloc Deprecated. use getBLOContainer or getBLO protected methods instead. Exposing this variable makes possible for a BLO to change it, which is illegal.
protected org.apache.commons.logging.Log	log Log to be used in the BLO's methods.

Constructor Summary

BLObject()

Method Summary

protected void	activate() Restore BLO after it has been recreated from the serialized form.
protected void	destroy() Destroyes the BLO.
protected ApplicationContext	getApplicationContext() Gets application context.
protected BLObject	getBLO(java.lang.String bloName) Gets a BLO from the same or the shared BLO container.
protected BLOContainer	getBLOContainer() Gets BLO container to which this BLO belongs.
protected DAO	getDAO() Gets DAO for the default data source.
protected DAO	getDAO(java.lang.String dataSourceName) Gets DAO for the specified data source.
protected DAOConfig	getDAOConfig() Gets DAO config object for the default data source.
protected DAOConfig	getDAOConfig(java.lang.String dataSourceName) Gets DAO config object for the specified data source.
java.lang.String	getDeploymentName() Gets the BLO's deployment name as specified by name attribute of the corresponding <blo> element in the blo-config.xml file.
protected java.lang.String	getInitParameter(java.lang.String parameterName) Gets a BLO initialization parameter.
BLErrors	getLastErrors() Gets errors for the last BLO business method call.
protected void	init() Initializes the BLO.
protected boolean	isRollbackOnly() Checks if the current transaction is marked for rollback only.
protected void	setErrors(BLErrors errors) Sets errors for the last BLO business method call.
protected void	setRollbackOnly() Marks current transaction for rollback only, or does nothing if there is no current transaction.

Methods inherited from class java.lang.Object

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

Field Detail

bloc

protected transient BLOContainer bloc

Deprecated. use getBLOContainer or getBLO protected methods instead. Exposing this variable makes possible for a BLO to change it, which is illegal.

Reference to the BLO container.

log

protected transient org.apache.commons.logging.Log log

Log to be used in the BLO's methods. The log is preconfigured to log messages to channel called "com.boylesoftware.cb2.BLOBJT.name", where name is the BLO's deployment name.

Constructor Detail

BLObject

public BLObject()

Method Detail

init

protected void init()
             throws BLException

Initializes the BLO. This method is called automatically on the BLO to notify it that a new BLO container has been created and this BLO is assigned to it. Subclasses redefine this method to implement BLO initialization logic. The default implementation does nothing.

Shared BLOs are created and initialized when the BL Manager is created and initialized, usually during application startup, making init methods of shared BLOs an ideal place for application initialization code.

If init method of a BLO throws an exception, it cancels the whole BLO container initialization - BLO container cannot be created and used unless all BLOs went through their init methods successfully.

BLOs are initialized in a transaction - one transaction to call init methods of all BLOs in the BLO container. If any of the BLOs throws an exception, the whole transaction, which includes anything done in init methods of other BLOs that has already been successfully called, gets rolled back.

Note, that BLOs are always initialized in the order their deployment descriptors appear in the blo-config.xml file. If one BLO needs service of another BLO in its init method, place the other BLO's deployment descriptor above the deployment descriptor of the first one in the blo-config.xml - it will guarantee that the other BLO will be initialized first.

Throws:

BLException - if the BLO cannot be initialized.

destroy

protected void destroy()

Destroyes the BLO. This method is called automatically when BLO container, to which this BLO belongs, is destroyed. BLO containers get destroyed when their respective user sessions finish or when the whole application shuts down. Subclasses redefine this method to free any used resources or to perform any other operations related to the fact that the BLO is no longer used. The default implementation does nothing.

Note, that the Shared BLO Container gets destroyed when the BL Manager gets destroyed, usually at the application shutdown, making destroy methods of shared BLOs an ideal place for code, which needs to be executed before the application goes down.

No database transaction is created for destroy methods, so it is not the best place to perform database operations.

BLOs are always destroyed in the reverse order their deployment descriptors appear in the blo-config.xml file (reverse order from how they are initialized).

activate

protected void activate()
                 throws BLException

Restore BLO after it has been recreated from the serialized form. This method is called automatically when a user session is being restored in the BL Manager via restoreUserSession call. Subclasses redefine this method to implement any logic specific to such an event. The default implementation does nothing.

Note, that activation is performed in non-transactional context, so avoid doing database related operations in activate method implementations. Also, keep the method implementation short, because it is called from a synchronized block, which prevents getting and locking BLO containers for all user sessions in the application.

BLOs are always activated in the order their deployment descriptors appear in the blo-config.xml file (the same order they are initialized).

Throws:

BLException - if the instance cannot be restored. Throwing exception cancels the whole user session restoration attempt - the restoreUserSession method on the BL Manager will throw an exception to the caller.

See Also:

BLManager.restoreUserSession(java.lang.String, com.boylesoftware.cb2.BLOContainer)

getLastErrors

public BLErrors getLastErrors()

Gets errors for the last BLO business method call. A business method creates BLErrors object and sets it in the BLO via setErrors protected method. Then it returns to the caller a special, method specific result indicating that there were errors and the call was not successful. The caller then call getLastErrors method on the BLO to find out what were the errors.

Calling this method resets the internal BLO variable that stores BLErrors object after last setErrors call. After it has been reset, all subsequent calls to getLastErrors will be returning an empty BLErrors object until another setErrors call sets new BLErrors.

Returns:

errors for the last business method call. Never returns null, but an empty errors object if there are no errors.

setErrors

protected final void setErrors(BLErrors errors)

Sets errors for the last BLO business method call. If a business method wants to indicate to the caller that the call was not successful, it creates a BLErrors object, sets it in the BLO using this method, and then returns to the caller a special kind of result, which tells the caller that there were errors and it should call getLastErrors on the BLO to find out what exactly it was.

If there was already a BLErrors object set by an earlier call, it is overwritten by this call.

Parameters:

errors - the errors bundle.

getInitParameter

protected final java.lang.String getInitParameter(java.lang.String parameterName)

Gets a BLO initialization parameter. A BLO can have custom initialization parameters specified in its deployment descriptor in the blo-config.xml file via <init-param> elements. They can be used to configure the BLO for the particular application in which it is used, so the BLO implementation can be reused in other applications with some functional changes.

Parameters:

parameterName - the init parameter's name as specified by the <param-name> element.

Returns:

the specified parameter's value or null if no such init parameter is defined in the BLO's deployment descriptor.

setRollbackOnly

protected void setRollbackOnly()
                        throws BLException

Marks current transaction for rollback only, or does nothing if there is no current transaction. This is a convenience method, which calls application context's appropriate method internally.

Throws:

BLException - could not mark current transaction for rollback only.

See Also:

ApplicationContext.setRollbackOnly()

isRollbackOnly

protected boolean isRollbackOnly()
                          throws BLException

Checks if the current transaction is marked for rollback only. Always returns false if there is no current transaction. This is a convenience method, which calls application context's appropriate method internally.

Returns:

true if the current transaction is marked for rollback only.

Throws:

BLException - could not get the current transaction's status.

See Also:

ApplicationContext.isRollbackOnly()

getDAOConfig

protected DAOConfig getDAOConfig(java.lang.String dataSourceName)

Gets DAO config object for the specified data source. DAO config objects are created from <dao-config> elements in the blo-config.xml file and are maintained by the BL Manager - one for each configured data source.

A BLO may need this object if it wants to create its own custom DAO for some reason, which is supposed to be a rather rare case.

Parameters:

dataSourceName - name of the data source as specified in the application context configuration and dataSource attribute of the <dao-config> element.

Returns:

reference to the appropriate DAO config object.

getDAOConfig

protected DAOConfig getDAOConfig()

Gets DAO config object for the default data source.

Returns:

reference to the DAO config object or null if the default source is not configured.

getDAO

protected DAO getDAO(java.lang.String dataSourceName)

Gets DAO for the specified data source. The DAO can be used in BLO's business methods to perform database operations. Although it is possible for a BLO to perform database operations directly via the JDBC interface (the application context provides access to configured database connections), it is more convenient to use the DAO, since it provides a higher level interface helping in the most use cases.

The BL Manager maintains a single DAO instance for each configured data source. The DAO's are built using DAO config objects created out of <dao-config> elements defined in the blo-config.xml file. This method allows to get reference to the appropriate DAO, maintained by the BL Manager, to be used in a BLO's business method.

Parameters:

dataSourceName - name of the data source as specified in the application context configuration and dataSource attribute of the <dao-config> element.

Returns:

reference to the appropriate DAO.

getDAO

protected DAO getDAO()

Gets DAO for the default data source.

Returns:

reference to the DAO or null if the default data source is not configured.

getBLOContainer

protected final BLOContainer getBLOContainer()

Gets BLO container to which this BLO belongs. Often BLOs need service of other BLOs in their methods. The getBLOContainer method provides access to the BLO container, which can be used to lookup other BLOs that belong to the same user session as well as shared BLOs.

The BLO container's state is properly maintained by the BL Manager - there is no need to release the BLO container aquired via this protected method, the reference can be abandoned after it is no longer needed.

Returns:

reference to the BLO container.

getBLO

protected final BLObject getBLO(java.lang.String bloName)

Gets a BLO from the same or the shared BLO container. This is a convenience method, which is equivalent to calling this.getBLOContainer().getBLO(bloName).

Parameters:

bloName - the BLO's deployment name.

Returns:

the BLO.

getApplicationContext

protected final ApplicationContext getApplicationContext()

Gets application context. This method is the way for the BLO's methods to access application context's services.

Returns:

reference to the application context.

getDeploymentName

public final java.lang.String getDeploymentName()

Gets the BLO's deployment name as specified by name attribute of the corresponding <blo> element in the blo-config.xml file. This is the name, under which the BLO can be looked up in a BLO container.

Returns:

the BLO's deployment name.