com.boylesoftware.cb2.BLManager
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Object
Business Level Manager singleton, which represents the Business Level of a CB2-based application. One instance of this class exists in the application, usually created at the application startup, and it is the second level up from the application context in terms of provided services. The BL Manager supports notion of user sessions, represented by BLO containers, and Business Level Objects (BLOs) that populate BLO containers and implement the application's business logic. A dedicated single BLO container is maintained by the BL Manager for shared BLOs - the Shared BLO Container. Also, the BL Manager maintains DAO instances for each configured in the application context data source, which it provides to the BLOs for database operations.
Clients of the BL Manager, usually the Presentation Level implementation,
have responsibility to manage user sessions within the BL Manager creating
and destroying them via createUserSession and
destroyUserSession methods. It is also a responsibility of the
client, if required by the application, to notify the BL Manager about user
authentication events, such as user login and logout, by calling appropriate
methods.
When the client needs to perform a business level operation, that is to
call a business method on a BLO, it first requests the BLO container for
the user session by calling getBLOContainer method and passing
to it the session id, previously aquired from the
createUserSession call. Then, the required BLO is looked up by
its deployment name in the BLO container and appropriate business methods
are called on it. When the BL Manager returns the BLO container to the
getBLOContainer caller, it locks the container, so any
consequent call to getBLOContainer with the same session id
will block until the BLO container is released by the previous requester by
calling releaseBLOContainer method (or release
convenience method on the container itself). This mechanism allows to forget
about providing access synchronization for the BLOs if used correctly, that
is if references to BLOs are not stored somewhere outside BLO container and
they are not called without aquiring and locking the BLO container via
getBLOContainer first. This does not concern the Shared BLO
Container, which never gets locked providing concurring access to the shared
BLOs. That is why appropriate access synchronization should be implemented
in the BLO level for shared BLOs.
The BL Manager is configured by file called blo-config.xml
and located in the configuration directory (see application context's
getConfigDirPath method). This configuration file contains
BLO deployment descriptors and configuration for the DAOs. The DTD can be
found at
http://www.cb2project.com/dtd/blo-config_1_0.dtd.
A few application properties control the BL Manager's behaviour:
com.boylesoftware.cb2.maxWaitingThreads -
allows to limit maximum number of threads waiting in the
getBLOContainer method for the BLO container to get unlocked.
If this property is not specified, there is no limit. Otherwise, if a thread
tries to get BLO container, which is locked by another thread, and there
are already com.boylesoftware.cb2.maxWaitingThreads threads
waiting, a TooManyWaitingThreadsException will be thrown by the
getBLOConatiner method.com.boylesoftware.cb2.keepBLSessions -
allows to disable destroying of BL Manager's state when the BL Manager gets
destroyed. Normally, when BL Manager is being destroyed via
destroy method call, it explicitely destroys all BLO containers
in it and all BLOs in the containers. If this application property is set
to "true" it does not happen, which may be useful if you (or your
presentation level framework) serializes BLO containers and stores them in a
persistent storage to restore user sessions after restart (see
restoreUserSession method).This class logs messages related to its operation under "com.boylesoftware.cb2.BLOMGR" log channel.
| Field Summary |
| Fields inherited from interface com.boylesoftware.cb2.StatusProvider |
TIMESTAMP_FORMAT |
| Constructor Summary | |
BLManager(ApplicationContext appCtx)
Creates BLManager and initializes the BLO
subsystem. |
|
| Method Summary | |
java.lang.String |
createUserSession()
Creates and initializes a new user session with BLO container and all the BLOs. |
void |
destroy()
Destroys the BLO subsystem. |
boolean |
destroyUserSession(java.lang.String sessionId)
Destroyes a user session including its BLO container and all the BLOs in it. |
ApplicationContext |
getApplicationContext()
Gets application context to which this BL Manager belongs. |
BLOContainer |
getBLOContainer(java.lang.String sessionId)
Gets BLO container for the specified user session. |
EventStatistics |
getEventStats(java.lang.String eventName)
Not used in this class, always returns null. |
BLObject |
getSharedBLO(java.lang.String bloName)
Gets a shared BLO from the Shared BLO Container. |
byte[] |
getStats()
Retrieves information about the Business Level as an XML text. |
void |
reconfigureDAL(org.w3c.dom.Document bloConfig)
Re/initializes the database access level. |
void |
releaseBLOContainer(java.lang.String sessionId)
Releases BLO container that was previously locked by a getBLOContainer call. |
void |
restoreUserSession(java.lang.String sessionId,
BLOContainer bloContainer)
Binds the specified BLO container instance with the specified session id effectively creating a new session. |
| Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Constructor Detail |
public BLManager(ApplicationContext appCtx)
throws ApplicationException
BLManager and initializes the BLO
subsystem. There should be only one BLManager
instance in the application. Usually an instance of
BLManager created once during the application
startup just after the application context is created and
intialized.
appCtx - the application context.
ApplicationException - the BLO subsystem cannot be initialized and
is unavailable.| Method Detail |
public void reconfigureDAL(org.w3c.dom.Document bloConfig)
throws BLException
bloConfig - a preparsed blo-config.xml
document or null if you want the method to find
and parse the file itself.
BLException - the DAL cannot be reconfigured, the
application is probably left in an unstable state.public void destroy()
Unless com.boylesoftware.cb2.keepBLSessions application
property is set to "true", calling this method causes the BL Manager to
explicitely destroy all BLO containers within it, which, in turn, causes
the BLO containers to explicitely destroy all BLOs contained within them
by calling their destroy methods.
If at the moment of this call threads exist that are waiting for BLO
containers in getBLOContainer method, they will get a
NoBLOContainerException. Basically, it is a good practice
to write the presentation level in a way that there is a guarantee that
no BLO containers are being used at the moment of the
destroy call.
public BLObject getSharedBLO(java.lang.String bloName)
All BLO containers perform lookup in the Shared BLO Container if there is no requested BLO in them, so it is a relatively rare case when this method needs to be called directly. The need may arise when you don't have any context of current user session, or for some reason don't want to lock the session's BLO container, while all you need is a shared BLO. Then it can be aquired via this method.
bloName - case-insensitive deployment name of a shared BLO.
null if there is no
BLO under the specified name in the Shared BLO Container.public ApplicationContext getApplicationContext()
public void restoreUserSession(java.lang.String sessionId,
BLOContainer bloContainer)
throws BLException
This method can be used to restore a session from a serialized BLO
container. It also internally "activates" the specified BLO container
instance, which causes activate methods to be called on the
BLOs in the container.
sessionId - session id, to which to bind the container. Must not
already exist, or a BLException is thrown.bloContainer - BLO container instance restored from the serialized
form (transient fields are not set).
BLException - if the session cannot be restored.
public java.lang.String createUserSession()
throws BLException
init methods.
BLException - could not initialize the BLO container or one of the
BLOs (a BLO's init method has thrown an exception).public boolean destroyUserSession(java.lang.String sessionId)
destroy methods.
Note, that if the BLO container is locked at the moment of the call, the method blocks and waits indefinitely until the BLO container gets unlocked by another thread.
sessionId - id of the session to destroy.
true if the session has been successfully
destroyed by this call, false if no session with
the specified id exists or the session is already being destroyed by
another call from a different thread.
public BLOContainer getBLOContainer(java.lang.String sessionId)
throws NoBLOContainerException,
TooManyWaitingThreadsException,
BLException
When this method returns a BLO container it locks it, meaning that
any subsequent getBLOContainer call for the same session
will block and wait indefinitely until the BLO container is released by
the previous requester through calling releaseBLOContainer
method (or release convenience method on the BLO container
itself). We suggest having an invocation of release method
in a finally block of your client code so there is a
guarantee that the BLO container always gets unlocked.
Never keep references to BLOs that are got from a BLO container after the BLO container is released, nor any references to the BLO container itself - always reaquire the BLO container when you need any service provided by the BLOs.
sessionId - id of the user session, for which we are requesting the
BLO container.
NoBLOContainer - if there is no BLO container for the requested
session. Note, that the session can be destroyed by another thread
during this method call. If that happens, this exception is thrown
with an appropriate message.
TooManyWaitingThreadsException - if the BLO container is locked
and there are already too many threads waiting for its release. The
maximum number of waiting threads is specified by
com.boylesoftware.cb2.maxWaitingThreads application
property. If it is not specified, the number of waiting threads is not
limited.
BLException - if an error happens in a BLO implementing
BLOContainerStateListener interface and it throws an
exception.
NoBLOContainerExceptionreleaseBLOContainer(String),
BLOContainer.release()
public void releaseBLOContainer(java.lang.String sessionId)
throws BLException
getBLOContainer call. After the BLO conatiner has been
unlocked by this call, it can be reaquired again by another
getBLOContainer mathod invocation.
Note, that it is usually more convenient to call
release method on the BLO container itself, which calls
this method internally, but does not require session id.
sessionId - id of the user session, whose BLO container we are
releasing.
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.IllegalArgumentException - if there is no session with the
specified session id.getBLOContainer(String),
BLOContainer.release()
public byte[] getStats()
throws java.lang.Exception
getStats in interface StatusProviderjava.lang.Exception - if an unexpected error happens.public EventStatistics getEventStats(java.lang.String eventName)
null.
getEventStats in interface StatusProvidereventName - implementation specific event name, for which current
statistics are requested.
null if the event is unknown.
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||