com.sun.identity.plugin.session

Interface SessionProvider

public interface SessionProvider

Interface used for creating sessions, and for accessing session information.

Method Summary

Modifier and Type	Method and Description
void	addListener(Object session, SessionListener listener) Registers a listener for the session.
void	applyCookies(Object session, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) For the given user session, generate the appropriate SSO and load-balancer cookies in the response.
Object	createSession(Map info, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, StringBuffer targetApplication) Meaningful only for Service Provider side, the implementation of this method will create a local session for the local user identified by the information in the map.
String	getPrincipalName(Object session) Returns princiapl name, or user name given the session object.
String[]	getProperty(Object session, String name) Returns property value of a session object.
Object	getSession(javax.servlet.http.HttpServletRequest request) Returns the corresponding session object.
Object	getSession(String sessionID) Returns the corresponding session object.
String	getSessionID(Object session) Returns session ID.
long	getTimeLeft(Object session) Returns the time left for this session in seconds.
void	invalidateSession(Object session, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) May be used by both SP and IDP side to invalidate a session.
boolean	isValid(Object session) Returns true if the session is valid.
void	setLoadBalancerCookie(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Sets a load balancer cookie in the suppled HTTP response.
void	setProperty(Object session, String name, String[] values) Stores a property in the session object.

Method Detail

createSession

Object createSession(Map info,
                     javax.servlet.http.HttpServletRequest request,
                     javax.servlet.http.HttpServletResponse response,
                     StringBuffer targetApplication)
              throws SessionException

Meaningful only for Service Provider side, the implementation of this method will create a local session for the local user identified by the information in the map. The underline mechanism of the session creation and management is application specific. For example, it could be cookie setting or URL rewriting, which is expected to be done by the implementation of this method. Note that only the first input parameter is mandatory. Normally, at least one of the last two parameters should not be null

Parameters:

info - a Map with keys and values being of type String; The keys will include SessionProvider.PRINCIPAL_NAME (returned from SPAccountMapper), SessionProvider.REALM, SessionProvider.AUTH_LEVEL, SessionProvider.AUTH_INSTANT, and may include "resourceOffering" and/or "idpEntityID"; The implementation of this method could choose to set some of the information contained in the map into the newly created Session by calling setProperty(), later the target application may consume the information.

request - the HttpServletRequesat the user made to initiate the Single Sign On; Note that it should be the initial request coming from the browser as opposed to the possible subsequent back-channel HTTP request for delivering SOAP message.

response - the HttpServletResponse that will be sent to the user (for example it could be used to set a cookie).

targetApplication - the original resource that was requested as the target of the Single Sign On by the end user; If needed, this String could be modified, e.g., by appending query string(s) or by URL rewriting, hence this is an in/out parameter.

Returns:

the newly created local user session.

Throws:

SessionException - if an error occurred during session creation.

applyCookies

void applyCookies(Object session,
                  javax.servlet.http.HttpServletRequest request,
                  javax.servlet.http.HttpServletResponse response)

For the given user session, generate the appropriate SSO and load-balancer cookies in the response. Should be called as late in the process as possible to ensure that when using client-based sessions, any properties that have been set during processing are available when creating the SSO cookie.

Parameters:

session - the current user session

request - the request used to initiate the sign-on process

response - the response to add the cookies to

getSession

Object getSession(String sessionID)
           throws SessionException

Returns the corresponding session object. May be used by both SP and IDP side for getting an existing session given an session ID.

Parameters:

sessionID - the unique session handle.

Returns:

the corresponding session object.

Throws:

SessionException - if an error occurred during session retrieval.

getSession

Object getSession(javax.servlet.http.HttpServletRequest request)
           throws SessionException

Returns the corresponding session object. May be used by both SP and IDP side for getting an existing session given a browser initiated HTTP request.

Parameters:

request - the browser initiated HTTP request.

Returns:

the corresponding session object.

Throws:

SessionException - if an error occurred during session retrieval.

invalidateSession

void invalidateSession(Object session,
                       javax.servlet.http.HttpServletRequest request,
                       javax.servlet.http.HttpServletResponse response)
                throws SessionException

May be used by both SP and IDP side to invalidate a session. In case of SLO with SOAP, the last two input parameters would have to be null

Parameters:

session - the session to be invalidated

request - the browser initiated HTTP request.

response - the HTTP response going back to browser.

Throws:

SessionException - if an error occurred during session retrieval.

isValid

boolean isValid(Object session)
         throws SessionException

Returns true if the session is valid. This is useful for toolkit clean-up thread.

Parameters:

session - Session object.

Returns:

true if the session is valid.

Throws:

SessionException

getSessionID

String getSessionID(Object session)

Returns session ID. The returned session ID should be unique and not change during the lifetime of this session

Returns:

session ID.

getPrincipalName

String getPrincipalName(Object session)
                 throws SessionException

Returns princiapl name, or user name given the session object.

Parameters:

session - Session object.

Returns:

principal name, or user name.

Throws:

SessionException - if getting the principal name causes an error.

setProperty

void setProperty(Object session,
                 String name,
                 String[] values)
          throws UnsupportedOperationException,
                 SessionException

Stores a property in the session object. This is an optional method.

Parameters:

session - the session object.

name - the property name.

values - the property values.

Throws:

UnsupportedOperationException - if this method is not supported.

SessionException - if setting the property in the session causes an error.

getProperty

String[] getProperty(Object session,
                     String name)
              throws UnsupportedOperationException,
                     SessionException

Returns property value of a session object. This is an optional method.

Parameters:

session - the session object.

name - the property name.

Returns:

the property values.

Throws:

UnsupportedOperationException - if this method is not supported.

SessionException - if getting the property from the session causes an error.

addListener

void addListener(Object session,
                 SessionListener listener)
          throws UnsupportedOperationException,
                 SessionException

Registers a listener for the session. This is an optional method.

Parameters:

session - the session object.

listener - listener for the session invalidation event.

Throws:

UnsupportedOperationException - if this method is not supported.

SessionException - if adding the listener in the session causes an error.

setLoadBalancerCookie

void setLoadBalancerCookie(javax.servlet.http.HttpServletRequest request,
                           javax.servlet.http.HttpServletResponse response)

Sets a load balancer cookie in the suppled HTTP response. The load balancer cookie's value is set per server instance and is used to support sticky load balancing.

Parameters:

response - the HttpServletResponse that will be sent to the user.

getTimeLeft

long getTimeLeft(Object session)
          throws SessionException

Returns the time left for this session in seconds.

Parameters:

session - Session object.

Returns:

The time left for this session.

Throws:

SessionException - is thrown if the session reached its maximum session time, or the session was destroyed, or there was an error during communication with session service.