ome.api
Interface ISession

All Superinterfaces:
ServiceInterface
All Known Implementing Classes:
SessionBean

public interface ISession
extends ServiceInterface

Start here: Session creation service for OMERO. Access to all other services is dependent upon a properly created and still active Session. The session's uuid can be considered a capability token, or temporary single use password. Simply by possessing it the client has access to all information available to the Session. Note: Both the RMI ServiceFactory as well as the Ice ServiceFactoryPrx use ISession to acquire a Session. In the RMI case, the ISession instance is the first remote proxy accessed. In the Ice case, Glacier2 contacts ISession itself and returns a ServiceFactory remote proxy. From both ServiceFactory instances, it is possible but not necessary to access ISession.

Since:
3.0-Beta3
Author:
Josh Moore, josh at glencoesoftware.com

Method Summary
 int closeSession(ome.model.meta.Session session)
          Closes session and releases all resources.
 ome.model.meta.Session createSession(Principal principal, String credentials)
          Creates a new session and returns it to the user.
 ome.model.meta.Session createSessionWithTimeout(Principal principal, long timeToLiveMilliseconds)
          Allows an admin to create a Session for the give Principal
 ome.model.meta.Session createSessionWithTimeouts(Principal principal, long timeToLiveMilliseconds, long timeToIdleMilliseconds)
          Allows an admin to create a Session for the give Principal
 ome.model.meta.Session createUserSession(long timeToLiveMilliseconds, long timeToIdleMillisecond, String defaultGroup, ome.model.internal.Permissions umask)
          Allows a user to open up another session for him/herself with the given defaults without needing to re-enter password.
 Object getInput(String session, String key)
          Retrieves an entry from the given session's input environment.
 Set<String> getInputKeys(String session)
          Retrieves all keys in the sesson's input environment.
 Object getOutput(String session, String key)
          Retrieves an entry from the session's output environment.
 Set<String> getOutputKeys(String session)
          Retrieves all keys in the sesson's output environment.
 int getReferenceCount(String sessionUuid)
          Retrieves the current reference count for the given uuid.
 ome.model.meta.Session getSession(String sessionUuid)
          Retrieves the session associated with this uuid, updating the last access time as well.
 void setInput(String session, String key, Object objection)
          Places an entry in the given session's input environment.
 void setOutput(String session, String key, Object objection)
          Places an entry in the given session's output environment.
 ome.model.meta.Session updateSession(ome.model.meta.Session session)
          Updates subset of the fields from the Session object to the Session matching the given uuid.
 

Method Detail

createUserSession

ome.model.meta.Session createUserSession(long timeToLiveMilliseconds,
                                         long timeToIdleMillisecond,
                                         String defaultGroup,
                                         ome.model.internal.Permissions umask)
Allows a user to open up another session for him/herself with the given defaults without needing to re-enter password.

To do:
Review the security of this method.

createSessionWithTimeout

ome.model.meta.Session createSessionWithTimeout(Principal principal,
                                                long timeToLiveMilliseconds)
Allows an admin to create a Session for the give Principal

Parameters:
principal - Non-null Principal with the target user's name
timeToLiveMilliseconds - The time that this Session has until destruction. This is useful to override the server default so that an initial delay before the user is given the token will not be construed as idle time. A value less than 1 will cause the default max timeToLive to be used; but timeToIdle will be disabled.

createSessionWithTimeouts

ome.model.meta.Session createSessionWithTimeouts(Principal principal,
                                                 long timeToLiveMilliseconds,
                                                 long timeToIdleMilliseconds)
Allows an admin to create a Session for the give Principal

Parameters:
principal - Non-null Principal with the target user's name
timeToLiveMillseconds - The time that this Session has until destruction. Setting the value to 0 will prevent destruction unless the session remains idle.
timeToIdleMilliseconds - The time that this Session can remain idle before being destroyed. Setting the value to 0 will prevent idleness based destruction.

createSession

ome.model.meta.Session createSession(Principal principal,
                                     String credentials)
Creates a new session and returns it to the user.

Throws:
ome.conditions.ApiUsageException - if principal is null
ome.conditions.SecurityViolation - if the password check fails

updateSession

ome.model.meta.Session updateSession(ome.model.meta.Session session)
Updates subset of the fields from the Session object to the Session matching the given uuid. If the uuid is not present, then a RemovedSessionException is thrown. Updated: group, Session.userAgent, Session.message, Session#defaultUmask, Session.setDefaultEventType(String) Conditionally updated: timeToLive, timeToIdle These can only be set within boundaries provided by the system administrator. Currently this is hard-coded to mean 10 times the defaultTimeToLive and defaultTimeToIdle, respectively. Ignored: All others, but especially user, Session.events Session.uuid, and the timestamps.

Parameters:
session - The Session instance to be updated.
Returns:
The Session updated instance. Should replace the current value: session = iSession.updateSession(session);

getSession

ome.model.meta.Session getSession(String sessionUuid)
Retrieves the session associated with this uuid, updating the last access time as well. Throws a RemovedSessionException if not present, or a SessionTimeoutException if expired. This method can be used as a Session ping.


getReferenceCount

int getReferenceCount(String sessionUuid)
Retrieves the current reference count for the given uuid. Has the same semantics as getSession(String).


closeSession

int closeSession(ome.model.meta.Session session)
Closes session and releases all resources. It is preferred that all clients call this method as soon as possible to free memory, but it is possible to not call close, and rejoin a session later. The current reference count for the session is returned. If the session does not exist, -1. If this call caused the death of the session, then -2.


getInput

Object getInput(String session,
                String key)
Retrieves an entry from the given session's input environment. If the value is null, the key will be removed.


getInputKeys

Set<String> getInputKeys(String session)
Retrieves all keys in the sesson's input environment.

Parameters:
session -
Returns:

setInput

void setInput(String session,
              String key,
              Object objection)
Places an entry in the given session's input environment. If the value is null, the key will be removed.


getOutputKeys

Set<String> getOutputKeys(String session)
Retrieves all keys in the sesson's output environment.


getOutput

Object getOutput(String session,
                 String key)
Retrieves an entry from the session's output environment.


setOutput

void setOutput(String session,
               String key,
               Object objection)
Places an entry in the given session's output environment. If the value is null, the key will be removed.



OmeroJava Api

Version: Beta-4.1.1-r5927-b91

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