uk.org.ogsadai.sessions
Interface Session

All Known Subinterfaces:

InternalSession

All Known Implementing Classes:

SafeSession, TransientInternalSession, TransientSession

public interface Session

The interface through which a session participant can interact with a session.

Methods are defined to enable a session participant to query and update a collection of session attributes. Additional methods are defined for creating/accessing/removing session streams and accessing the session ID and session request status.

Author:

The OGSA-DAI Project Team

Method Summary

void	addExternalInput(java.lang.String name, Pipe input) Adds an external input session stream.
void	addExternalOutput(java.lang.String name, Pipe output) Adds an external output session stream.
boolean	containsAttribute(javax.xml.namespace.QName name) Indicates whether or not the session contains a session attribute with the specified name.
int	countAttributes() Returns the number of session attributes contained in the session.
SessionAttribute	getAttribute(javax.xml.namespace.QName name) Gets the session attribute for the given name or null if no such attribute exists.
java.util.Set	getAttributeNames() Returns a set of the names of the session attributes contained in the session.
java.lang.Object	getAttributeValue(javax.xml.namespace.QName name) Gets the actual value of the session attribute with the given name.
Pipe	getExternalInput(java.lang.String name) Gets the Pipe for the external input with the specified name allowing data to be written into the pipe or read from it.
Pipe	getExternalOutput(java.lang.String name) Gets the Pipe for the external output with the specified name allowing data to be written to it of read from it.
SessionID	getID() Returns the SessionID object identifying the session.
Properties	getProperties() Gets the set of data service resource properties that are available to this session.
ProcessingStatus	getRequestStatus() Gets the session request processing status.
boolean	hasExternalInput(java.lang.String name) Checks whether the context contains a Pipe for an external input with the specified name.
boolean	hasExternalOutput(java.lang.String name) Checks whether the context contains a Pipe for an external output with the specified name.
void	removeAttribute(javax.xml.namespace.QName name) Removes a named session attribute from the session unless it is a static session attribute.
void	removeExternalInput(java.lang.String name) Removes an external input session stream.
void	removeExternalOutput(java.lang.String name) Removes an external output session stream.
void	setAttribute(SessionAttribute attribute) Sets the specified session attribute, storing it in the session.

Method Detail

getID

public SessionID getID()

Returns the SessionID object identifying the session.

Returns:

SessionID

containsAttribute

public boolean containsAttribute(javax.xml.namespace.QName name)

Indicates whether or not the session contains a session attribute with the specified name.

Parameters:

name - The name of the session attribute as a QName.

Returns:

true if the session attribute exists, false otherwise.

Throws:

java.lang.IllegalArgumentException - if name is null.

countAttributes

public int countAttributes()

Returns the number of session attributes contained in the session.

Returns:

number of attributes.

getAttribute

public SessionAttribute getAttribute(javax.xml.namespace.QName name)

Gets the session attribute for the given name or null if no such attribute exists.

Parameters:

name - The name of the session attribute as a QName.

Returns:

name or null.

Throws:

java.lang.IllegalArgumentException - if name is null.

getAttributeNames

public java.util.Set getAttributeNames()

Returns a set of the names of the session attributes contained in the session.

Returns:

a set of QName objects.

getAttributeValue

public java.lang.Object getAttributeValue(javax.xml.namespace.QName name)

Gets the actual value of the session attribute with the given name.

Session attributes encapsulate a name-value pair, so this method is provided as a convenient way to access the session attribute value directly. It is equivalent to getSessionAttribute().getValue().

Parameters:

name - The name of the session attribute as a QName.

Returns:

the Object that is the session attribute value or null if the attribute does not exist (or the attribute value is actually null).

Throws:

java.lang.IllegalArgumentException - if name is null.

removeAttribute

public void removeAttribute(javax.xml.namespace.QName name)
                     throws StaticSessionAttrException

Removes a named session attribute from the session unless it is a static session attribute.

Static session attributes are identified by the false return value of their isChangable method. If the named session attribute does not exist then no action is taken.

Parameters:

name - The QName of the session attribute to remove.

Throws:

StaticSessionAttrException - If name identifies a static session attribute.

java.lang.IllegalArgumentException - if name is null.

setAttribute

public void setAttribute(SessionAttribute attribute)
                  throws StaticSessionAttrException

Sets the specified session attribute, storing it in the session.

If an attribute with the same name already exists, then the existing attribute is overwritten, unless it is a static session attribute. Static session attributes cannot be overwritten.

Parameters:

attribute - The SessionAttribute to store in the session.

Throws:

StaticSessionAttrException - If name identifies a static session attribute.

java.lang.IllegalArgumentException - if attribute is null.

getProperties

public Properties getProperties()

Gets the set of data service resource properties that are available to this session.

Session participants, such as activities, may query, add and remove properties from this at runtime.

Returns:

a Properties object

getRequestStatus

public ProcessingStatus getRequestStatus()

Gets the session request processing status.

This is the status of the current request that is processing in the session.

Returns:

the observable ProcessingStatus.

hasExternalInput

public boolean hasExternalInput(java.lang.String name)

Checks whether the context contains a Pipe for an external input with the specified name.

Parameters:

name - The name of the external input.

Returns:

true if the input exists, false otherwise.

Throws:

java.lang.IllegalArgumentException - if name is null.

hasExternalOutput

public boolean hasExternalOutput(java.lang.String name)

Checks whether the context contains a Pipe for an external output with the specified name.

Parameters:

name - The name of the external output.

Returns:

true if the output exists, false otherwise.

Throws:

java.lang.IllegalArgumentException - if name is null.

getExternalOutput

public Pipe getExternalOutput(java.lang.String name)

Gets the Pipe for the external output with the specified name allowing data to be written to it of read from it.

Parameters:

name - The name of the external output.

Returns:

A Pipe from which data can be read or null if there is no output with the specified name.

Throws:

java.lang.IllegalArgumentException - if name is null.

getExternalInput

public Pipe getExternalInput(java.lang.String name)

Gets the Pipe for the external input with the specified name allowing data to be written into the pipe or read from it.

Parameters:

name - The name of the external input.

Returns:

A Pipe to which data can be written or null if there is no input with the specified name.

Throws:

java.lang.IllegalArgumentException - if name is null.

addExternalInput

public void addExternalInput(java.lang.String name,
                             Pipe input)
                      throws SessionStreamDuplicateException

Adds an external input session stream.

This is a Pipe that can receive input data from an external agent and be read from by an activity or session participant.

Parameters:

name - The name of the session stream.

input - The pipe for the data.

Throws:

SessionStreamDuplicateException - if an external input session stream with the same name has already been added to the session.

java.lang.IllegalArgumentException - if name or input are null.

addExternalOutput

public void addExternalOutput(java.lang.String name,
                              Pipe output)
                       throws SessionStreamDuplicateException

Adds an external output session stream.

This is a Pipe that can receive input data from an activity or session participant. This data can then be read by an external agent.

Parameters:

name - The name of the session stream.

output - The pipe for the data.

Throws:

SessionStreamDuplicateException - if an external output session stream with the same name has already been added to the session.

java.lang.IllegalArgumentException - if name or output are null.

removeExternalInput

public void removeExternalInput(java.lang.String name)

Removes an external input session stream.

After this method has returned the session stream will no longer be available to external agents.

Parameters:

name - The name of the session stream. If no stream exists with this name then no action is taken.

Throws:

java.lang.IllegalArgumentException - if name is null.

removeExternalOutput

public void removeExternalOutput(java.lang.String name)

Removes an external output session stream.

After this method has returned the session stream will no longer be available to external agents.

Parameters:

name - The name of the session stream. If no stream exists with this name then no action is taken.

Throws:

java.lang.IllegalArgumentException - if name is null.