com.boylesoftware.cb2
Class BLOContainer

java.lang.Object
  com.boylesoftware.cb2.BLOContainer

All Implemented Interfaces:

java.io.Serializable

public final class BLOContainer

extends java.lang.Object

implements java.io.Serializable

As its name suggests, BLO container contains BLOs. BLOs never exist out of BLO container context and the only way to access a BLO is to find first the BLO container and then lookup the BLO in it by the BLO's deployment name. The BL Manager creates, maintains and destroys BLO containers as user sessions are created and destroyed. Since there is always one dedicated BLO container corresponding to every user session, in a sense, a BLO container is a representation of a user session in the Business Level. There is one exception to that though - the Shared BLO Container, which is an instance of BLOContainer class which contains shared BLOs and does not correspond to any particular user session. The instance of the Shared BLO Container is maintained by the BL Manager as well.

The only way to get a BLO container for the application code is through the BL Manager's getBLOContainer method. The getBLOContainer method also locks the BLO container so no other thread can access it until it is release by the current owner via release method call (or BL Manager's releaseBLOContainer). Because of that, all methods of this class are absolutely not thread-safe, counting on proper usage, which is never store references to BLO containers in your application. Instead, you should always call BLO container's methods between getBLOContainer and release calls, that is while it is locked.

This class logs messages related to its operation under "com.boylesoftware.cb2.BLOCNR" log channel.

Version:

$Id: BLOContainer.java,v 1.7 2004/04/23 17:49:55 levahim Exp $

Author:

Lev Himmelfarb

See Also:

BLManager, BLObject, Serialized Form

Method Summary

BLManager	getBLManager() Gets the BL Manager.
BLObject	getBLO(java.lang.String bloName) Gets a BLO from this container or the Shared BLO Container.
java.lang.Object	getSessionId() Gets id of the user session, to which this container corresponds.
java.security.Principal	getUserPrincipal() Gets currently authenticated for the session user principal set earlier by the processUserLogin call.
boolean	hasBLO(java.lang.String bloName) Checks if there is a BLO under the specified name in this container or in the Shared BLO Container.
boolean	isShared() Tells if this is the Shared BLO Container.
void	processUserLogin(java.security.Principal principal) Notifies the BLO container about a user login event for the session.
void	processUserLogout() Notifies the BLO container about a user logout event for the session.
void	release() Releases this BLO container after it has been locked by the BL Manager's getBLOContainer method.

Methods inherited from class java.lang.Object

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

Method Detail

getBLO

public BLObject getBLO(java.lang.String bloName)

Gets a BLO from this container or the Shared BLO Container. First, it checks if there is a BLO under the specified deployment name in this BLO container. If it finds it, it returns it immediately. If not, and this is not the Shared BLO Container, it tries to find and return the BLO from the Shared BLO Container. If it's not there either, the method throws an exception. Note however, that if it is the Shared BLO Container and it does not contain the requested BLO, this method does not throw an exception, but returns null instead.

Parameters:

bloName - case-insensitive deployment name of a BLO.

Returns:

reference to the named BLO or null if there is no such BLO and this is the Shared BLO Container.

Throws:

java.lang.IllegalArgumentException - if there is no BLO with the specified name and this container is not the Shared BLO Container.

hasBLO

public boolean hasBLO(java.lang.String bloName)

Checks if there is a BLO under the specified name in this container or in the Shared BLO Container.

Parameters:

bloName - BLO's deployment name as specified in the blo-config.xml file.

Returns:

true if the specified BLO exists and can be retrieved via getBLO method.

release

public void release()
             throws BLException

Releases this BLO container after it has been locked by the BL Manager's getBLOContainer method. This is a convenience method, which calls releaseBLOContainer on the BL Manager internally. It is often more convenient to call this method rather than the BL Manager's, because it does not require the session id.

Throws:

BLException - if an error happens in a BLO implementing BLOContainerStateListener interface and it throws an exception. Note, that the BLO container gets unlocked anyway.

java.lang.UnsupportedOperationException - if called on the Shared BLO Container.

See Also:

BLManager.releaseBLOContainer(java.lang.String)

processUserLogin

public void processUserLogin(java.security.Principal principal)
                      throws BLException

Notifies the BLO container about a user login event for the session. The BLO container calls processUserLogin method on all its BLOs that implement AuthenticationListener interface. A transaction is started for this operation and all BLOs are called within that one single transaction. This method checks if it has been already successfully called earlier and no user logout happened since then. If so, an IllegalStateException is thrown.

Standard CB2 Presentation Level implementations, such as the one located in com.boylesoftware.cb2.presentation.servlet package, call this method automatically when appropriate. But if you are implementing the presentation level yourself, you should take care of calling this method upon each successful user login (if you care about the notification at all).

Note also, that this method is never called on the Shared BLO Container, because the Shared BLO Container does not correspond to any user session. It makes impractical for shared BLOs to implement AuthenticationListener interface.

Parameters:

principal - the pricipal, who logged in. Should not be null, or a IllegalArgumentException is thrown.

Throws:

BLException - if one of the BLOs implementing AuthenticationListener interface threw an exception. It may also mean that not all listeners have been notified, and it certainly means that the trasnaction got rolled back.

java.lang.IllegalStateException - if there is already a logged in user.

See Also:

AuthenticationListener

processUserLogout

public void processUserLogout()
                       throws BLException

Notifies the BLO container about a user logout event for the session. This method works very similarly to the processUserLogin method, with the difference that processUserLogout method is called on the BLOs implementing AuthenticationListener interface, and that it does nothing if processUserLogin has not been successfully called earlier.

Throws:

BLException - if one of the BLOs implementing AuthenticationListener interface threw an exception. It may also mean that not all listeners have been notified, and it certainly means that the trasnaction got rolled back.

See Also:

AuthenticationListener, processUserLogin(java.security.Principal)

getBLManager

public BLManager getBLManager()

Gets the BL Manager.

Returns:

reference to the BL Manager.

getSessionId

public java.lang.Object getSessionId()

Gets id of the user session, to which this container corresponds.

Returns:

id of the session, or null if it is the Shared BLO Container.

getUserPrincipal

public java.security.Principal getUserPrincipal()

Gets currently authenticated for the session user principal set earlier by the processUserLogin call.

Returns:

the user principal or null if the session is not authenticated.

isShared

public boolean isShared()

Tells if this is the Shared BLO Container.

Returns:

true if this is the Shared BLO Container.