ome.services.sessions

Interface SessionManager

All Known Implementing Classes:

SessionManagerImpl

public interface SessionManager

Responsible for holding onto Session instances for optimized login. SessionManager implementations should strive to be only in-memory representations of the database used as a performance optimization. When possible, all changes should be made to the database as quickly and as synchronously as possible.

Since:

3.0-Beta3

Author:

Josh Moore, josh at glencoesoftware.com

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	SessionManager.CreationRequest Extensible data object which can be passed to create* methods to stop the explosion of different methods.

Method Summary

Modifier and Type	Method and Description
int	close(String uuid) If reference count for the session is less than 1, close the session.
int	closeAll() Close all sessions with checking for the necessary reference counts.
Session	createFromRequest(SessionManager.CreationRequest request)
Share	createShare(Principal principal, boolean enabled, long timeToLive, String eventType, String description, long groupId)
Session	createWithAgent(Principal principal, String agent, String ip)
Session	createWithAgent(Principal principal, String credentials, String agent, String ip)
int	detach(String uuid) Allows decrementing the reference count for a session without calling the actual close(String) logic.
boolean	executePasswordCheck(String name, String credentials) Executes a password check using the Executor framework.
Session	find(String uuid)
List<Session>	findByUser(String user)
List<Session>	findByUserAndAgent(String user, String... agent) Returns a non-null, possibly empty list of session instances belonging to the given user and with one of the given agents.
EventContext	getEventContext(Principal principal) Provides a partial EventContext for the current Session.
Object	getInput(String session, String key) Returns the input environment Object stored under the given key or null if none present.
Object	getOutput(String session, String key) Returns the output environment Object stored under the given key or null if none present.
int	getReferenceCount(String uuid) Return the number of client which are presumed to be attached to this session or throw an exception if there's no such session.
Map<String,Map<String,Object>>	getSessionData() Return all sessions that are active with associated possibly varying session data information.
SessionStats	getSessionStats(String uuid) Return the SessionStats which are being counted for the given session or throw an exception if it has been removed.
List<String>	getUserRoles(String uuid)
net.sf.ehcache.Ehcache	inMemoryCache(String uuid) Returns after possibly creating an in-memory cache which can be used throughout the session.
Map<String,Object>	inputEnvironment(String session) Returns a copy of the input environment.
net.sf.ehcache.Ehcache	onDiskCache(String uuid) Returns after possibly creating an on-disk cache which can be used throughout the session.
Map<String,Object>	outputEnvironment(String session) Returns a copy of the output environment.
EventContext	reload(String uuid) Similar to getEventContext(Principal) but uses the internal reload logic to get a fresh representation of the context.
void	setInput(String session, String key, Object object) Places the argument in the input environment under the given key, possibly initializing the Map Throws an exception if there is no Session with the given identifier.
void	setOutput(String session, String key, Object object) Places the argument in the output environment under the given key, possibly initializing the Map Throws an exception if there is no Session with the given identifier.
IObject	setSecurityContext(Principal principal, IObject obj) Sets the context for the current session to the given value.
Session	update(Session session) Certain fields from the Session instance will be copied and then saved to the db, as well as a new SessionContext created.
Session	update(Session session, boolean trust) Same as update(Session) but some security checks can be overridden.

Method Detail

createFromRequest

Session createFromRequest(SessionManager.CreationRequest request)

createWithAgent

Session createWithAgent(Principal principal,
                        String credentials,
                        String agent,
                        String ip)

Parameters:

principal -

credentials -

agent -

ip -

Returns:

Not null. Instead an exception will be thrown.

createWithAgent

Session createWithAgent(Principal principal,
                        String agent,
                        String ip)

Parameters:

principal -

agent -

ip -

Returns:

Not null. Instead an exception will be thrown.

createShare

Share createShare(Principal principal,
                  boolean enabled,
                  long timeToLive,
                  String eventType,
                  String description,
                  long groupId)

Parameters:

principal -

enabled -

timeToLive -

eventType -

description -

groupId -

Returns:

Not null. Instead an exception will be thrown.

setSecurityContext

IObject setSecurityContext(Principal principal,
                           IObject obj)

Sets the context for the current session to the given value. If it is an ExperimenterGroup then the active group is changed, and any active shares are deactivated. If it is an Share then the share is activate (the group is left alone). Unless otherwise specified, the user's default group is used as the initial context. Passing any other object will result in an ApiUsageException.

Parameters:

principal - Principal for which the context should be set.

obj - IObject which represents the new context.

Returns:

See above.

update

Session update(Session session)

Certain fields from the Session instance will be copied and then saved to the db, as well as a new SessionContext created. This method assumes that the user is NOT an admin.

update

Session update(Session session,
               boolean trust)

Same as update(Session) but some security checks can be overridden. This is usually done by checking with the SecuritySystem but here the server is in a critical state, and instead will trust the method invoker.

detach

int detach(String uuid)

Allows decrementing the reference count for a session without calling the actual close(String) logic. This is useful when it is assumed that another user will re-attach to the same session. A timeout can still cause the session to be removed.

Parameters:

uuid -

Returns:

See above.

getReferenceCount

int getReferenceCount(String uuid)

Return the number of client which are presumed to be attached to this session or throw an exception if there's no such session.

getSessionStats

SessionStats getSessionStats(String uuid)

Return the SessionStats which are being counted for the given session or throw an exception if it has been removed.

find

Session find(String uuid)

Parameters:

uuid -

Returns:

A current session.

Throws:

SessionTimeoutException - if the session has timed out during this call. It will then be removed and subsequent calls will throw a RemovedSessionException

RemovedSessionException - if a previous call already excised this session

findByUser

List<Session> findByUser(String user)

Parameters:

user -

Returns:

See above.

findByUserAndAgent

List<Session> findByUserAndAgent(String user,
                                 String... agent)

Returns a non-null, possibly empty list of session instances belonging to the given user and with one of the given agents. If the agent list is empty, then only sessions without agent values will be returned.

getSessionData

Map<String,Map<String,Object>> getSessionData()

Return all sessions that are active with associated possibly varying session data information.

close

int close(String uuid)

If reference count for the session is less than 1, close the session. Otherwise decrement the reference count. The current reference count is returned. If -1, then no such session existed. If -2, then the session was removed.

closeAll

int closeAll()

Close all sessions with checking for the necessary reference counts.

getEventContext

EventContext getEventContext(Principal principal)
                      throws RemovedSessionException

Provides a partial EventContext for the current Session.

Parameters:

principal - Non null.

Returns:

Never null.

Throws:

RemovedSessionException - if no session with the given Principal.getName()

reload

EventContext reload(String uuid)
             throws RemovedSessionException

Similar to getEventContext(Principal) but uses the internal reload logic to get a fresh representation of the context. This queries all of the user management tables (experimenter, experimentergroup, etc) and so should not be used anywhere in a critical path.

Parameters:

uuid - non null.

Returns:

See above.

Throws:

RemovedSessionException - If the uuid does not exist.

getUserRoles

List<String> getUserRoles(String uuid)

executePasswordCheck

boolean executePasswordCheck(String name,
                             String credentials)

Executes a password check using the Executor framework. Also checks the credentials against current session uuids.

Parameters:

name -

credentials -

Returns:

See above.

inMemoryCache

net.sf.ehcache.Ehcache inMemoryCache(String uuid)

Returns after possibly creating an in-memory cache which can be used throughout the session. On close, the cache will be disposed.

onDiskCache

net.sf.ehcache.Ehcache onDiskCache(String uuid)

Returns after possibly creating an on-disk cache which can be used throughout the session. On close, the cache will be disposed.

getInput

Object getInput(String session,
                String key)
         throws RemovedSessionException

Returns the input environment Object stored under the given key or null if none present. Throws an exception if there is no Session with the given identifier.

Parameters:

session - Not null.

key - Not null.

Returns:

Possibly null.

Throws:

RemovedSessionException

getOutput

Object getOutput(String session,
                 String key)
          throws RemovedSessionException

Returns the output environment Object stored under the given key or null if none present. Throws an exception if there is no Session with the given identifier.

Parameters:

session - Not null.

key - Not null.

Returns:

Possibly null.

Throws:

RemovedSessionException

setInput

void setInput(String session,
              String key,
              Object object)
       throws RemovedSessionException

Places the argument in the input environment under the given key, possibly initializing the Map Throws an exception if there is no Session with the given identifier.

Parameters:

session - Not null.

key - Not null.

object - If null, key will be removed.

Throws:

RemovedSessionException

setOutput

void setOutput(String session,
               String key,
               Object object)
        throws RemovedSessionException

Places the argument in the output environment under the given key, possibly initializing the Map Throws an exception if there is no Session with the given identifier.

Parameters:

session - Not null.

key - Not null.

object - If null, key will be removed.

Throws:

RemovedSessionException

inputEnvironment

Map<String,Object> inputEnvironment(String session)

Returns a copy of the input environment.

Parameters:

session - The session id.

Returns:

Not null

outputEnvironment

Map<String,Object> outputEnvironment(String session)

Returns a copy of the output environment.

Parameters:

session - The session id.

Returns:

Not null.