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

Method Summary
 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.
 ome.model.meta.Share createShare(Principal principal, boolean enabled, long timeToLive, String eventType, String description, long groupId)
           
 ome.model.meta.Session createWithAgent(Principal principal, String agent)
           
 ome.model.meta.Session createWithAgent(Principal principal, String credentials, String agent)
           
 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.
 ome.model.meta.Session find(String uuid)
           
 List<ome.model.meta.Session> findByUser(String user)
           
 List<ome.model.meta.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.
 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.
 ome.model.IObject setSecurityContext(Principal principal, ome.model.IObject obj)
          Sets the context for the current session to the given value.
 ome.model.meta.Session update(ome.model.meta.Session session)
          See ISession#updateSession(Session) for the logic that's implemented here.
 ome.model.meta.Session update(ome.model.meta.Session session, boolean trust)
          Same as update(Session) but some security checks can be overriden.
 

Method Detail

createWithAgent

ome.model.meta.Session createWithAgent(Principal principal,
                                       String credentials,
                                       String agent)
Parameters:
principal -
credentials -
Returns:
Not null. Instead an exception will be thrown.

createWithAgent

ome.model.meta.Session createWithAgent(Principal principal,
                                       String agent)
Parameters:
principal -
Returns:
Not null. Instead an exception will be thrown.

createShare

ome.model.meta.Share createShare(Principal principal,
                                 boolean enabled,
                                 long timeToLive,
                                 String eventType,
                                 String description,
                                 long groupId)
Parameters:
principal -
enabled -
Returns:

setSecurityContext

ome.model.IObject setSecurityContext(Principal principal,
                                     ome.model.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.

update

ome.model.meta.Session update(ome.model.meta.Session session)
See ISession#updateSession(Session) for the logic that's implemented here. 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

ome.model.meta.Session update(ome.model.meta.Session session,
                              boolean trust)
Same as update(Session) but some security checks can be overriden. 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:

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

ome.model.meta.Session find(String uuid)
Parameters:
sessionId -
Returns:
A current session.
Throws:
ome.conditions.SessionTimeoutException - if the session has timed out during this call. It will then be removed and subsequent calls will throw a RemovedSessionException
ome.conditions.RemovedSessionException - if a previous call already excised this session

findByUser

List<ome.model.meta.Session> findByUser(String user)
Parameters:
user -
Returns:

findByUserAndAgent

List<ome.model.meta.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.


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 ome.conditions.RemovedSessionException
Provides a partial EventContext for the current Session.

Parameters:
uuid - Non null.
Returns:
Never null.
Throws:
ome.conditions.RemovedSessionException - if no session with the given Principal.getName()

reload

EventContext reload(String uuid)
                    throws ome.conditions.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:
Throws:
ome.conditions.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 -

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 ome.conditions.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:
ome.conditions.RemovedSessionException

getOutput

Object getOutput(String session,
                 String key)
                 throws ome.conditions.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:
ome.conditions.RemovedSessionException

setInput

void setInput(String session,
              String key,
              Object object)
              throws ome.conditions.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:
ome.conditions.RemovedSessionException

setOutput

void setOutput(String session,
               String key,
               Object object)
               throws ome.conditions.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:
ome.conditions.RemovedSessionException

inputEnvironment

Map<String,Object> inputEnvironment(String session)
Returns a copy of the input environment.

Returns:
Not null

outputEnvironment

Map<String,Object> outputEnvironment(String session)
Returns a copy of the output environment.

Returns:
Not null.


OmeroJava Api

Version: 4.3.3-00d1137e-b2894

Copyright © 2009 The University of Dundee. All Rights Reserved.