|
CoherenceTM v3.3 Copyright© 2000-2007 by Oracle Corporation |
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface HttpSessionCollection
This is the abstract model for a collection of HttpSessionModel objects. The interface is not at all concerned with how the sessions are communicated between the clients and the servers (e.g. cookies, URLs) and thus is decoupled from those concerns.
Some of the methods presented on this interface may seem out-of-place and better located on the HttpSessionModel itself; however, the choice was made to place them on the collection (this interface) if their purpose is related to managing the model, and to place the methods on the model only if their purpose is related to accessing and manipulating the data represented by the session model itself. This helps to simplify the model, making it a logical terminal (an object that is not dependent on other objects in the framework).
For consistency purposes, the API takes the session ID as a parameter, even when the HttpSessionModel reference is expected to be available.
There are three different session state transitions that the collection is
responsible for managing. The first is existence: A session enters the
exists state as a result of the create()
method, and is transitioned back to the does not exist
state only by the destroy()
method.
The second transition is ownership. Ownership refers to the ability for a
deployer to specify that a session be owned by a particular thread or a
particular server at a time, such that only that one thread or server could
modify the session, blocking any other thread or server attempting to
access the same session. (Note that "thread" level ownership is actually
"server+thread" ownership, since it implies that only one thread in the
entire cluster will own the session at a time, while "server" level
ownership implies that multiple threads on the same server can access the
session at the same time.) The state transition is from
not owned to owned state as a result of the
enter()
method, and from owned to
not owned as a result of the exit()
method.
Since the deployer may choose to allow multiple threads on multiple servers
to access the same session at the same time (a legitimate choice for many
applications, assuming that the session management implementation supports
it -- as the Coherence 2.2 and previous implementations do), the state
transition can be reduced to a no-op, or it can be as complex as using
cluster-wide locking and thread level synchronization on a server. Even
more complex is the ability for multiple threads on the same server to
access the session, while maintaining ownership for that session on that
server; this implies a sub-attribute of the ownership state to be a thread-
or reference-count.
As an added complexity for the ownership state, when a session is created
it is considered to be owned, as if the enter()
method were
called as part of the create()
method's processing.
This implies that, when an HTTP request results in a session being created,
the request processing must invoke the exit()
method although
the enter()
method has not been invoked. Correspondingly, the
destroy()
method will release the ownership state, implying
that the exit()
method should not be called in this case.
The third transition is activation. Activation refers to a state in which
the session can be manipulated, such that it is considered to be "alive"
on a particular server in the cluster. This primarily relates to the
optional event interface (HttpSessionActivationListener) that session
attributes can implement to find out when the session is passivated and
activated. Moreover, it implies strict adherence to the specification such
that a session is only able to be "alive" on one server at a time. (Since
such strict adherence may not be desired, it is possible to disable its
side-effects. However, like the ownership state, disabling the feature is
the easy part, while providing the feature is singularly daunting.) The
state transition is from passive to active
state as a result of the activate()
method, and from
active to passive as a result of the
passivate()
method.
The combination of the ownership and activation state transitions introduces a potential logical deadlock, resulting from the following set of rules:
activate()
or
passivate()
can be invoked for that session.
An extremely strict implementation would not suffer from this problem, in
that it would always passivate the session (which is to say, it would
always notify the session attributes of their passivation) at the end
of each request, and it would limit concurrent access to the session to
the thread level (i.e. only one thread could access the session at a time.)
The result is that, even in the case of unexpected server failure, the
passivation would have occurred if the request completed successfully,
thus allowing activation to occur without concern once the ownership
state is owned as a result of the enter()
method.
If the class implementating this interface requires configuration information, it should implement the XmlConfigurable interface.
Note: This API currently requires Servlet 2.3 because it uses the "newer" session event listener interface; to work with Servlet 2.2 and earlier, the necessary javax classes will have to be deployed as part of the application or into the application server itself.
Nested Class Summary | |
---|---|
static interface |
HttpSessionCollection.SessionDistributionController
An optional interface to override the default distribution of session objects in the cluster, allowing the sessions to remain "local" to the originating server until a later point in the life of the session, that point determined by the implementation of this interface. |
Method Summary | |
---|---|
void |
activate(String sId,
HttpSession session)
Move the session into an active state, if it is not already. |
void |
addHttpSessionAttributeListener(HttpSessionAttributeListener listener)
Sign up the specified listener to receive HttpSessionBindingEvent objects. |
void |
addHttpSessionListener(HttpSessionListener listener)
Sign up the specified listener to receive HttpSessionEvent objects. |
HttpSessionModel |
create(HttpSession session)
This method creates a new session, returning the session model for the new session. |
void |
destroy(String sId)
Destroy the specified session. |
boolean |
enter(String sId,
boolean fWait)
Obtain any necessary ownership for the specified session. |
void |
exit(String sId)
Release ownership for the specified session. |
void |
flush(String sId)
In a distributed environment, ensure that any changes to the specified session are flushed. |
HttpSessionModel |
get(String sId)
Obtain the HttpSessionModel for the specified session, or null if it does not exist. |
boolean |
isActive(String sId)
Determine if the specified session ID identifies a session that is in the active state. |
boolean |
isExistent(String sId)
Determine if the specified session ID identifies a session that exists. |
boolean |
isOwned(String sId)
Determine if the specified session ID identifies a session that exists and that this thread has ownership for, either by a call to enter(sId) or create() without a corresponding
call to exit(sId) . |
Iterator |
iterateIds()
Obtain an iterator of the session IDs. |
Iterator |
iterateLocalIds()
Obtain an iterator of the session IDs that this JVM is responsible for invalidating when the sessions for those IDs have timed out. |
void |
passivate(String sId)
Move the session into a passive state, if it is not already. |
void |
postCreate(HttpSession session)
This method is called at the end of the session creation process. |
void |
removeHttpSessionAttributeListener(HttpSessionAttributeListener listener)
Sign off the specified listener so it no longer will receive HttpSessionBindingEvent objects. |
void |
removeHttpSessionListener(HttpSessionListener listener)
Sign off the specified listener so it no longer will receive HttpSessionEvent objects. |
void |
shutdown()
Notify the session collection that it is being shut down. |
Method Detail |
---|
HttpSessionModel create(HttpSession session)
The session is created with the default timeout, and has an ID that is unique within the domain that the session management layer is configured for (e.g. within the JVM, or within the cluster.)
When the session model is returned, the session state is exists,
owned, active. Note that the responsibilities associated with
the enter()
method are included as part of the session
creation process.
The model will retain the reference to the HttpSession object until it is passivated or destroyed.
session
- the HttpSession object to bind the session model to;
used for issuing events; must not be null
void postCreate(HttpSession session)
When this method is called, the session state is exists, owned, active.
session
- the HttpSession object; must not be nullboolean isExistent(String sId)
The notion of ownership will affect whether or not the answer can be
trusted once the method has returned it. If the ownership state is
owned (the current thread called enter(sId)
),
then the caller should assume that session still exists. Otherwise,
the caller can only assume that the session did exist at the
point in time that the call to this method was made.
sId
- the session ID to check for existence
void destroy(String sId)
This method may only be called on a session that is exists, owned, active.
Session attributes will receive HttpSessionBindingListener as per the Servlet specification.
At the return point from this method, the session state is does
not exist. Note that the responsibilities associated with the
exit(sId)
method are included as part of the session
destruction process.
After this method completes, the model's HttpSession reference will be null.
sId
- the session ID; must not be nullboolean enter(String sId, boolean fWait)
If the session specified by the session ID does not exist, then this method has no effect; no exception is thrown.
This method must support Multiple Possession Semantics, meaning
that this method may be invoked multiple times, and each invocation
will require a corresponding call to the exit(sId)
method
in order to release the ownership.
sId
- the session ID; must not be nullfWait
- true if the thread should block until the session becomes
available; false otherwise
boolean isOwned(String sId)
enter(sId)
or create()
without a corresponding
call to exit(sId)
.
void exit(String sId)
enter(sId)
,
with the only exceptions being:
enter(sId)
method was never invoked.When ownership state of a new session changes from owned to not owned, the session will no longer be considered new.
If the session specified by the session ID does not exist, then this method has no effect; no exception is thrown.
sId
- the session ID; must not be nullvoid activate(String sId, HttpSession session)
Invoking this method will issue activation events for session attributes that implement the HttpSessionActivationListener interface. The model will retain the reference to the HttpSession object until it is passivated or destroyed.
sId
- the session ID; must not be nullsession
- the HttpSession object to bind the session model to;
used for issuing events; must not be nullboolean isActive(String sId)
This method may only be called within the bounds of a call to
enter(sId)
and exit(sId)
.
sId
- the session ID to check for the active state
void passivate(String sId)
Invoking this method will issue passivation events for session attributes that implement the HttpSessionActivationListener interface.
After this method completes, the model's HttpSession reference will be null.
sId
- the session ID; must not be nullIterator iterateIds()
The list of IDs is completely dynamic because of the nature of multi-threaded and distributed systems. The fact that an ID is returned from an iterator is no guarantee that the ID is still valid.
Iterator iterateLocalIds()
This may return an iterator with the same contents as the one
returned by the iterateIds()
method, or it may return
an iterator that iterates over a subset of those contents.
The list of IDs is completely dynamic because of the nature of multi-threaded and distributed systems. The fact that an ID is returned from an iterator is no guarantee that the ID is still valid.
HttpSessionModel get(String sId)
This method may only be called within the bounds of a call to
enter(sId)
and exit(sId)
.
sId
- the session ID; must not be null
void flush(String sId)
This method may only be called within the bounds of a call to
enter(sId)
and exit(sId)
.
sId
- the session ID; must not be nullvoid addHttpSessionListener(HttpSessionListener listener)
listener
- the HttpSessionListener to sign up for eventsvoid removeHttpSessionListener(HttpSessionListener listener)
listener
- the HttpSessionListener that was previously signed up
for eventsvoid addHttpSessionAttributeListener(HttpSessionAttributeListener listener)
listener
- the HttpSessionAttributeListener to sign up for eventsvoid removeHttpSessionAttributeListener(HttpSessionAttributeListener listener)
listener
- the HttpSessionAttributeListener that was previously
signed up for eventsvoid shutdown()
|
CoherenceTM v3.3 Copyright© 2000-2007 by Oracle Corporation |
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |