com.novell.service.session
Interface Session

public interface Session

extends Authenticatable

Provides a communication channel between the owning/initiating object that creates a session and the target domain (tree, server, or any other object). It provides those methods that are common to all Sessions. All objects returned by the SessionManager are of type Session.

See Also:

SessionManager

Field Summary

static java.lang.String	DOMAIN_NAME_ATTR_ID Attribute ID describing the domain name of a Session.
static java.lang.String	INITIAL_SESSION_TYPE Attribute value returned for SESSION_TYPE_ATTR_ID in initial Sessions.
static java.lang.String	IS_REAL_ATTR_ID Attribute ID describing the "realness" of a Session.
static java.lang.String	MANAGER_SESSION_TYPE Attribute value returned for SESSION_TYPE_ATTR_ID in SessionManager Sessions.
static java.lang.String	PROVIDER_NAME_ATTR_ID Attribute ID describing the provider of a Session.
static java.lang.String	SESSION_MANAGER_TYPE Deprecated. Use MANAGER_SESSION_TYPE Attribute value returned for SESSION_TYPE_ATTR_ID for SessionManager Sessions. (SESSION_MANAGER_TYPE = "SESSION_MANAGER")
static java.lang.String	SESSION_STATE_ATTR_ID Attribute ID describing the state of a Session.
static java.lang.String	SESSION_TYPE_ATTR_ID Attribute ID describing the type of a Session.
static java.lang.String	UID_ATTR_ID Attribute ID describing the unique ID of a Session.

Fields inherited from class com.novell.service.session.Authenticatable

IS_AUTHENTICATED_ATTR_ID, USER_NAME_ATTR_ID

Method Summary

void	close() Closes and invalidates this session and its children, removing all stored credentials.
Session	findSession(java.lang.String domainName) Returns the first session found with a domain name matching the passed-in domaine parameter value.
Session	findSessionTop(java.lang.String domainName) Returns the first session found with a matching domain name, starting at the session manager.
SessionAttrs	getAttributes() Returns a selected default subset of all attributes for this session.
SessionAttrs	getAttributes(java.lang.String[] attrIds) Returns the attributes for this session listed in the attrIds[] parameter.
SessionEnumerator	getChildren() Returns an enumeration of child sessions of this session.
java.lang.String	getDomainName() Returns the domain name of this session.
SessionEnv	getEffectiveEnvironment() Returns the environment affecting this session.
SessionEnv	getEnvironment() Returns the environment for this session.
Session	getParent() Returns this session's parent session, or NULL if its parent Session doesn't exist.
SessionService	getService(java.lang.String serviceKey) Returns a service extension for this session.
Session	getSession(java.lang.String domainName) Adds a child session to the parent based on the session from which this operation is called.
Session	getSession(java.lang.String domainName, SessionEnv environment) Adds a child session to the parent based on the session from which this operation is called.
Session	getSessionTop(java.lang.String domainName) Creates a session with no consideration of the session from which this operation was called.
Session	getSessionTop(java.lang.String domainName, SessionEnv environment) Creates a session with no consideration of the session from which this operation was called.
java.rmi.server.UID	getUID() Return the unique ID for this session.
boolean	hasChildren() Determines if this session has children.
boolean	hasParent() Determines if this session has a parent.
void	invalidate() Remove the passed-in Session from its children, if possible without actually closing the Session.
boolean	isValid() Determines if this session is in a valid state.
SessionEnumerator	search(SessionAttrs matchingSessionAttrSet) Searches for sessions with matching attributes.
SessionEnv	setEnvironment(SessionEnv environment) Sets/replaces the environment for this session and returns the old environment.
void	validateLinks() Validate the children of this session.

Methods inherited from interface com.novell.service.session.Authenticatable

authenticate, authenticate, createIdentity, getName, isAuthenticated, unauthenticate

Field Detail

PROVIDER_NAME_ATTR_ID

public static final java.lang.String PROVIDER_NAME_ATTR_ID

Attribute ID describing the provider of a Session.

(PROVIDER_NAME_ATTR_ID = "SESSION_PROVIDER")

See Also:

SessionAttr, getAttributes()

SESSION_STATE_ATTR_ID

public static final java.lang.String SESSION_STATE_ATTR_ID

Attribute ID describing the state of a Session.

(SESSION_STATE_ATTR_ID = "SESSION_STATE")

See Also:

SessionAttr, getAttributes()

DOMAIN_NAME_ATTR_ID

public static final java.lang.String DOMAIN_NAME_ATTR_ID

Attribute ID describing the domain name of a Session.

(DOMAIN_NAME_ATTR_ID = "DOMAIN_NAME")

See Also:

SessionAttr, getAttributes()

SESSION_TYPE_ATTR_ID

public static final java.lang.String SESSION_TYPE_ATTR_ID

Attribute ID describing the type of a Session. It uniquely identifies sessions at a certain level (INITIAL_SESSION for all initial sessions, TREE and SERVER types under the NDS provider, and SERVER under the Bindery provider.

(SESSION_TYPE_ATTR_ID = "SESSION_TYPE")

See Also:

SessionAttr, getAttributes(), MANAGER_SESSION_TYPE, INITIAL_SESSION_TYPE

IS_REAL_ATTR_ID

public static final java.lang.String IS_REAL_ATTR_ID

Attribute ID describing the "realness" of a Session. The associated value is a Boolean. Real sessions have real endpoints (servers, trees, and so forth), and are those sessions whose domain name is non-deterministic.

(IS_REAL_ATTR_ID = "IS_REAL")

See Also:

SessionAttr, getAttributes()

UID_ATTR_ID

public static final java.lang.String UID_ATTR_ID

Attribute ID describing the unique ID of a Session.

(UID_ATTR_ID = "UID")

See Also:

SessionAttr, getAttributes()

SESSION_MANAGER_TYPE

public static final java.lang.String SESSION_MANAGER_TYPE

Deprecated. Use MANAGER_SESSION_TYPE

Attribute value returned for SESSION_TYPE_ATTR_ID for SessionManager Sessions.

(SESSION_MANAGER_TYPE = "SESSION_MANAGER")

See Also:

SessionAttr, getAttributes()

MANAGER_SESSION_TYPE

public static final java.lang.String MANAGER_SESSION_TYPE

Attribute value returned for SESSION_TYPE_ATTR_ID in SessionManager Sessions.

(MANAGER_SESSION_TYPE = "SESSION_MANAGER")

See Also:

SessionAttr, getAttributes(), SESSION_TYPE_ATTR_ID

INITIAL_SESSION_TYPE

public static final java.lang.String INITIAL_SESSION_TYPE

Attribute value returned for SESSION_TYPE_ATTR_ID in initial Sessions.

(INITIAL_SESSION_TYPE = "INITIAL_SESSION")

See Also:

SessionAttr, getAttributes(), SESSION_TYPE_ATTR_ID

Method Detail

close

public void close()
           throws SessionException,
                  java.rmi.RemoteException

Closes and invalidates this session and its children, removing all stored credentials. With the exception of SessionManager and InitialSessions, the session state will change to InvalidSessionState. This is a terminal state that cannot be changed back into another state. This effectively invalidates the session.

Throws:

SessionException - Top level exception thrown by Session objects or a subclass thereof.

getSession

public Session getSession(java.lang.String domainName)
                   throws SessionException,
                          java.rmi.RemoteException

Adds a child session to the parent based on the session from which this operation is called. The parent session can be a Session or SessionManager.

Parameters:

domainName - The domain name of the session to add. The domain name depends on the provider.

Returns:

Session The child session added.

Throws:

SessionException - Top level exception thrown by Session objects or a subclass thereof.

See Also:

getSession(java.lang.String SessionEnv), getSessionTop(java.lang.String), Xplat.LOOKUP_DOMAIN, Xplat.DOMAIN_ADDRESS

getSession

public Session getSession(java.lang.String domainName,
                          SessionEnv environment)
                   throws SessionException,
                          java.rmi.RemoteException

Adds a child session to the parent based on the session from which this operation is called. It uses environment to control behavior when applicable.

Parameters:

domainName - The domain name of the session to add. The domain name depends on the provider.

environment - The environment passed-in to control the the creation behavior of this session.

Returns:

Session The child session added.

Throws:

SessionException - Top level exception thrown by Session objects or a subclass thereof.

See Also:

getSession(java.lang.String), getSessionTop(java.lang.String), SessionEnv

getSessionTop

public Session getSessionTop(java.lang.String domainName)
                      throws SessionException,
                             java.rmi.RemoteException

Creates a session with no consideration of the session from which this operation was called.

Parameters:

domainName - The domain name of the session to add.

Returns:

Session The session created.

Throws:

SessionException - Top level exception thrown by Session objects or a subclass thereof.

See Also:

getSession(java.lang.String)

getSessionTop

public Session getSessionTop(java.lang.String domainName,
                             SessionEnv environment)
                      throws SessionException,
                             java.rmi.RemoteException

Creates a session with no consideration of the session from which this operation was called. It uses environment to control behavior when applicable.

Parameters:

domainName - The domain name of the session to add.

environment - The environment passed to control the creation behavior of this session.

Throws:

SessionException - Top level exception thrown by Session objects or a subclass thereof.

See Also:

getSession(java.lang.String), SessionEnv

getAttributes

public SessionAttrs getAttributes()
                           throws SessionException,
                                  java.rmi.RemoteException

Returns a selected default subset of all attributes for this session. Operational attributes will not be returned with this method unless the FORCE_OPERATIONAL_ATTRIBUTES variable value is set to TRUE. You should be aware that session attribute IDs are provider specific.

Returns:

SessionAttrs The attributes of this session.

Throws:

SessionException - Top level exception thrown by Session objects or a subclass thereof.

See Also:

getAttributes(java.lang.String[]), Xplat.FORCE_OPERATIONAL_ATTRIBUTES

getAttributes

public SessionAttrs getAttributes(java.lang.String[] attrIds)
                           throws SessionException,
                                  java.rmi.RemoteException

Returns the attributes for this session listed in the attrIds[] parameter. All attributes, including operational attributes, specified in the parameter will be returned. You should be aware that session attribute IDs are provider specific.

Parameters:

attrIds - An array of session attribute IDs.

Returns:

SessionAttrs The attributes of this Session that match the passed in IDs.

Throws:

SessionException - Top level exception thrown by Session objects or a subclass thereof.

See Also:

getAttributes(), Authenticatable, Bindery, NDS, Xplat

getEnvironment

public SessionEnv getEnvironment()
                          throws SessionException,
                                 java.rmi.RemoteException

Returns the environment for this session.

Returns:

SessionEnv The environment for this session.

Throws:

SessionException - Top level exception thrown by Session objects or a subclass thereof.

SessionException - Top level exception thrown by Session objects or a subclass thereof.

See Also:

getEffectiveEnvironment(), setEnvironment(com.novell.service.session.SessionEnv), SessionEnv

getEffectiveEnvironment

public SessionEnv getEffectiveEnvironment()
                                   throws SessionException,
                                          java.rmi.RemoteException

Returns the environment affecting this session.

The effective environment includes the environment of all parent sessions above this session, in addition to this session's environment. SessionEnv entries in this session override duplicates in upper sessions.

Returns:

SessionEnv The environment affecting this session.

Throws:

SessionException - Top level exception thrown by Session objects or a subclass thereof.

See Also:

getEnvironment(), SessionEnv

setEnvironment

public SessionEnv setEnvironment(SessionEnv environment)
                          throws SessionException,
                                 java.rmi.RemoteException

Sets/replaces the environment for this session and returns the old environment. The environment may be empty or NULL.

Parameters:

environment - The environment passed-in to control the behavior ofthis Session.

Throws:

SessionException - Top level exception thrown by Session objects or a subclass thereof.

See Also:

getEnvironment(), SessionEnv

search

public SessionEnumerator search(SessionAttrs matchingSessionAttrSet)
                         throws SessionException,
                                java.rmi.RemoteException

Searches for sessions with matching attributes. All string attribute values specified in a SessionAttrs instance when calling search() should be case-exact.

Interesting sessions are typically those sessions other than initial sessions and the session manager (i.e. those sessions that can be added or closed and those that have IS_REAL_ATTR_ID = TRUE).

Parameters:

matchingSessionAttrSet - Attributes to match. An empty SessionAttrs will return all Sessions.

Returns:

SessionEnumerator The Session with matching attributes.

Throws:

SessionException - Top level exception thrown by Session objects or a subclass thereof.

getDomainName

public java.lang.String getDomainName()
                               throws SessionException,
                                      java.rmi.RemoteException

Returns the domain name of this session.

Returns:

String Containing the domain name of this session.

Throws:

SessionException - Top level exception thrown by Session objects.

getChildren

public SessionEnumerator getChildren()
                              throws SessionException,
                                     java.rmi.RemoteException

Returns an enumeration of child sessions of this session.

Returns:

SessionEnumerator An enumeration of child sessions.

Throws:

SessionException - Top level exception thrown by Session objects.

getParent

public Session getParent()
                  throws java.rmi.RemoteException

Returns this session's parent session, or NULL if its parent Session doesn't exist.

invalidate

public void invalidate()
                throws SessionException,
                       java.rmi.RemoteException

Remove the passed-in Session from its children, if possible without actually closing the Session. Any references to the Session become invalid.

Note: Because a user of the session may still have a reference to it, they may still attempt to call a method on that Session. Upon execution of invalidate(), the session's state is changed to invalid and most subsequent method calls on that session will throw InvalidSessionException.

Parameters:

childSession - The child Session to invalidate.

Throws:

SessionException - Top level exception thrown by Session objects or a subclass thereof.

validateLinks

public void validateLinks()
                   throws SessionException,
                          java.rmi.RemoteException

Validate the children of this session.

A session implementation may sit on top of an existing client that has other entry points besides through a single JVM. This operation allows a user of the session to make sure data in the session is up-to-date.

Throws:

SessionException - Top level exception thrown by Session objects or a subclass thereof.

getService

public SessionService getService(java.lang.String serviceKey)
                          throws SessionException,
                                 java.rmi.RemoteException

Returns a service extension for this session. Typically, sessions are only used for gaining access to a set of services. Those services are made available via the SessionService returned by this method.

Parameters:

serviceKey - The key defined by the provider for accessing a particular service.

Returns:

SessionService The service extensions for this session.

Throws:

SessionException - Top level exception thrown by Session objects or a subclass thereof.

getUID

public java.rmi.server.UID getUID()
                           throws SessionException,
                                  java.rmi.RemoteException

Return the unique ID for this session.

Returns:

The unique ID for this session.

Throws:

SessionException - Top level exception thrown by Session objects or a subclass thereof.

hasParent

public boolean hasParent()
                  throws java.rmi.RemoteException

Determines if this session has a parent.

Returns:

A boolean set to TRUE if this session has a parent, otherwise set to FALSE.

hasChildren

public boolean hasChildren()
                    throws java.rmi.RemoteException

Determines if this session has children.

Returns:

A boolean set to TRUE if this session has children, otherwise set to FALSE.

findSession

public Session findSession(java.lang.String domainName)
                    throws SessionException,
                           java.rmi.RemoteException

Returns the first session found with a domain name matching the passed-in domaine parameter value.

Returns:

The Session with a matching domain name.

Throws:

SessionException - Top level exception thrown by Session objects or a subclass thereof.

findSessionTop

public Session findSessionTop(java.lang.String domainName)
                       throws SessionException,
                              java.rmi.RemoteException

Returns the first session found with a matching domain name, starting at the session manager.

Returns:

The first session found with a matching domain name.

Throws:

SessionException - Top level exception thrown by Session objects or a subclass thereof.

isValid

public boolean isValid()
                throws java.rmi.RemoteException

Determines if this session is in a valid state.

Returns:

A boolean set to TRUE if this session is valid, otherwise set to FALSE.