org.astrogrid.acr.builtin
Interface SessionManager


public interface SessionManager

AR Service: Create and manage sessions.

When using the Astro Runtime in a multi-user or server-side setting, it may be necessary to have more than one user simultaneously interacting with the AR. Without some additional mechanism, all users would share the same authentication and program state - in particular, 2 users could not be simultaneously logged in as different identities.

The SessionManager allows the programmer to create new sessions. Each user session contains the authentication and program state of a single user. More than one session may exist simultaneously within the AR, and the state within sessions are isolated from each other. By creating a new session for each user, multiple users with different identities can access a single AR.

By default, all AR api calls are made within the default session. The connection properties for this session are described in ~/.astrogrid-properties (for XMLRPC & HTTP) and this is the session that RMI clients connect to automatically using the Finder.

From the default session, a new user session can be created by calling SessionManager.createNewSession(long). A unique session identifier is returned. A session can be checked for availability using SessionManager.exists(String) and disposed of using SessionManager.dispose(String).

Once a session has been created, it must be connected to. The connection method depends on how the AR is being accessed:

XMLRPC
Pass the session identifier to SessionManager.findXmlRpcSession(String), which returns a URL that can then be connected to using an XMLRPC library
HTTP
Pass the session identifier to SessionManager.findHttpSession(String), which returns the base URL for performing HTTP function calls in this session
RMI
Pass the session identifier to Finder.findSession(String), which returns an instance of ACR for this session
No matter how the session is accessed, it presents an unaltered AR API - it's just that user authentication and state is isolated from other sessions. Not all data is isolated - in particular cached information (such as registry entries), and configuration settings (accessed from Configuration) are shared between all sessions.

Warning:

This session manager does not make any strong guarantees about security - the purpose of this feature is to enable multiple user identities within the same AR - not to enforce strict isolation between users of the same AR. In particular, all clients of the AR must first use the default user session to create a new session, and it may also be possible to determine how to connect to other sessions - hence it is recommended that all clients connecting to the AR are mutually trusting.

Python XMLRPC Example

# connect to the AR (in the default session)
from xmlrpc import Server
from os.path import expanduser
ar = Server(file(expanduser('~/.astrogrid-desktop')).next().strip() +'xmlrpc')
sm = ar.builtin.sessionManager

# create a new user session (with timeout of 10 mins)
sessID = sm.createNewSession(10)

#find xmlrpc endpoint for the new session
sessURL = sm.findXmlRpcSession(sessID)

#connect to the new session
sessAR = Server(sessURL)

#work within the neww session
sessAR.astrogrid.community.login("username","password","community")
...

Service Name
builtin.sessionManager

Method Summary
 String createNewSession(long inactivityTimeout)
          create a new session.
 void dispose(String sessionId)
          dispose of a session.
 boolean exists(String sessionId)
          check whether a session exists and is accessible
 URL findHttpSession(String sessionId)
          Find the endpoint to connect to a session using HTTP
 URL findXmlRpcSession(String sessionId)
          Find the endpoint to connect to a session using XML-RPC
 

Method Detail

createNewSession

String createNewSession(long inactivityTimeout)
                        throws NotApplicableException,
                               SecurityException
create a new session.

Parameters:
inactivityTimeout - number of minutes that this session can be inactive before it is disposed.
Returns:
a sessionId - an identifier for the newly created session.
Throws:
NotApplicableException - if this AR does not support creating new sessions.
SecurityException - if the current user or client is not permitted to create new sessions.

exists

boolean exists(String sessionId)
check whether a session exists and is accessible


dispose

void dispose(String sessionId)
dispose of a session.

Notes:
Once disposed of, a session cannot be connected to.
Parameters:
sessionId - a sessionId that currently exists. If this is the id of the default session, nothing happens.

findXmlRpcSession

URL findXmlRpcSession(String sessionId)
                      throws InvalidArgumentException
Find the endpoint to connect to a session using XML-RPC

Parameters:
sessionId - an existing sessionId
Returns:
a full URL that an XML-RPC client should connect to to work with this session. No further manipulation of this URL is required.
Throws:
InvalidArgumentException - if the sessionId is invalid.

findHttpSession

URL findHttpSession(String sessionId)
                    throws InvalidArgumentException
Find the endpoint to connect to a session using HTTP

Parameters:
sessionId - an existing sessionId
Returns:
a URL that should be used as the base for HTTP invocations of the services in this session.
Throws:
InvalidArgumentException - if the sessionId is invalid.


Copyright © 2002-2010 AstroGrid. All Rights Reserved.