Session:

  Most libraries use session handles to distinguish scope
  (security, settings, lifetime) of objects etc.

  GAT used a Context object, which is a session handle 
  with attached information (security context, preferences) 
  and some methods (get 'self', init environment, current
  status, ...).

  Proposal: re-use what we have in GAT: falls back to the
  well known paradigm of a session session handle), plus
  give potential for a few more features (see above). For
  simplicity, the session has no methods for now.  They 
  will get added when schemes for preferences, security, 
  and status get defined.

+-------------------------------------------------------------+

Summary:
========

  The session provides the functionality of a session
  handle.  A session is created, and used as parameter 
  to ALL object instanciations.  Multiple contexts can
  co-exist.  A single session can be shared between threads.
  SAGA Objects created from other SAGA Objects inherit its
  session.  Only some objects do not need a session handle
  on creation time, and can hence be shared between
  sessions.  That includes:
   - Context
   - Utility  classes

  A Context (encapsulates security information) can be
  attached to a Session.  A SAGA implementation MAY allow 
  to attach more than one Context to a single Session.

+-------------------------------------------------------------+

Use Cases:
==========

  Not applicable here;  this is a general design decision.

+-------------------------------------------------------------+


API Summary:
============

API Summary:

  package SAGA version 0.1 {

    interface Session {
      addContext         (in  Context        context);
      getContext         (out array<Context> contexts);
    }
  }

+-------------------------------------------------------------+


API Detail:
===========

  interface Session:

    - addContext
      Purpose: attach a security context to a session handle
      Format:  addContext           (in Context context);
      Inputs:  context               Security Context to add
      Outputs: none
      Throws:  BadParameter:         context is invalid,
               IncorectState:        implementation cannot 
                                     handle any more contexts
      
    - getContexts
      Purpose: retrieve all contexts attached to a session 
      Format:  getContext           (out array<Context> 
                                                   contexts);
      Inputs:  none
      Outputs: contexts              list of contexts of this 
                                     session
      Throws:  nothing
      Note:    - a empty list is returned if no Context is 
                 attached, yet.
    
      
+-------------------------------------------------------------+


Examples:
=========

  Session session;
  File    file (session);

  File file2 = file.copy (location);
  
+-------------------------------------------------------------+