CASL: Sessions API: Programming Guide
DocumentId:GradSof-CASL-Sessions-r-PG-08.07.2002-1.0.0

Introduction

Session service is element of infrastructure which provide automation of using design template "evictor" by programmer.

The main point of this template is:

• We must hold state of interaction with client in application server.
• Client application lifetime and interaction protocol are unexpected. (for instance, client state may be a reflection of users input or client may contain errors).
• We would like server to allocate resources for active clients and free resources of inactive clients.
• Client is 'forgotten', if it has not called server during some period SessionExpireTime.
• How client identify itself: will consider it able to receive some session identifier (SessionId), which is generated by server when client called to server at first. In future client communicates SessionId to server during executing any operation. It like a bus ticket bought on entrance by passenger, then passenger bring this ticket to ticket collector.
• In conclusion, what SessionService does: it gives API to create session variables and recovery session state by SessionId. When operation of recovery session state wasn't called during SessionExpiredTime then session service has the right to delete corresponding variables set generating exception during state recovery operation.

API

The theory now is clear. Now look at brief API description (Full API description you can find at API Guide ).

Service

namespace CASL
{
 
   class SessionService: public CASL::Service
   {
    public:

     struct SessionExpired: public CASL::Exception
     ..........

     struct InvalidSessionId: public CASL::Exception
     ..........

     struct TooManySessions: public CASL::Exception
     ..........

     struct UsernameMismatch: public CASL::Exception
     ..........

     /**
      * create Session 
      **/
     virtual SessionContextWrapper createSession(const char* username,
                                                 time_t nSecondsToExpire=0) = 0;
                                           

     /**
      * get SessionContext by id.
      * throw SessionExpiredException or InvalidSessionId
      **/
     virtual SessionContextWrapper getSessionContext(SessionIdType id, 
                                               const char* username) = 0;

     /**
      * end session.
      **/
     virtual void  releaseSession(SessionContextWrapper sessionContext) = 0;


     // Service stuff:

     ///
     bool  requireThread() { return true; }

   };


}

As you can see, this service provides API with 3 main methods:

• createSession - creates session for user with username name setting session inactivity period to SessionExpireTime
• getSessionContext - recovers session context by id, if session isn't destroyed.
• releaseSession - destroy session context for given id.

Now we have only to find out what SessionContext is and why it returns SessionContextWrapper.

Service context

Let's look at API description again

• Context
• SessionContext
• SessionContextWrapper

Or here:

namespace CASL
{

  typedef std::string  SessionIdType;

  class SessionContext : public Context
  {
  public:

    SessionIdType  getSessionId() const;

    const char*    getUsername() const;

    time_t         getExpireTime() const;

    bool  checkUsername(const char* username);

    void  touch() const;

    ValuesSlot&  getDefaultValuesSlot();

    ValuesSlot&  getValuesSlot(const char* name);
    ValuesSlot&  getValuesSlot(int index);

  private:
 
    ..............

  };

As you can see, SessionContext is simple common CASL-context (set of named slots), extended by additional attributes id, username - user name, which this session belongs to, expireTime and dedicated slot, where values are stored.

Now let's clear up why we return SessionContextWrapper instead of SessionContext.

Look at definitions again:

  class SessionContextWrapper
  {
   public:

    ......

    SessionContext* operator->();

    SessionContext& operator*();

    bool isNULL() const

    SessionContextWrapper(const SessionContextWrapper& x)

    SessionContextWrapper& operator=(const SessionContextWrapper& x)

  };


}

We can see, that SessionContextWrapper is simple ``weak pointer'' to SessionContext.

Why: imagine hypothetical situation : Let, we transmitted session context to another part of program, then session ended off and context is destroyed. Then if use direct pointer to destroy session context will lead to crash of program.

SessionContextWrapper simply checks during accessing context that corresponding session isn't destroyed , and if it is destroyed generates SessionExpired exception.

Example: context slot usage

You can find it in source code of CASL distributive .

Changes list

1. 09.07.2002 - created.