next_inactive up previous


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:

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:

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

Service context

Let's look at API description again

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.


next_inactive up previous
GradSoft