Provided by: afnix_2.8.1-2_amd64 bug

NAME

       csm - standard cloud session management service

STANDARD CLOUD SESSION MANAGEMENT SERVICE

       The  Standard  Cloud  Session  Managementservice  is an original implementation of various
       objects dedicated to the  management  of  events  eventually  associated  with  a  session
       controller.  In  its  classical way, the objects can be used to manage an agenda, schedule
       events and perform associated actions. In a more elaborated way, a session  group  can  be
       used to manage different group of objects bound to one or several users or groups.

       General concepts
       The  afnix-csmprovides  the  support for manipulating cloud session data. Information data
       are generally personal information that are used to manage time and constraints or  global
       session  information  bound  to  one  or  several  users.  In the time domain, the session
       management is related to the concept of time slot and agenda.

       Slot
       The concept of slot is central in the csmservice. A slot is  a  combination  of  time  and
       duration.  A slot is allocated by an appointer to indicate the next available slot. For an
       agenda, the concept of slot can be derived to describe an appointment.

       Appointer
       An appointeris a slot generator. The appointer can be designed  to  respond  automatically
       with  respect  to a certain number of rules. Common rules found in an appointer are closed
       days like week-end and time allocation period.

       Assistant
       An assistantis a combination of csm object like appointers. An assistant can be  used  for
       example, to manage several appointers.

       Appointer operations
       The  Appointerclass  is  designed  to allocate slots with respect to a certain duration or
       from a certain time with a duration. The appointer operates with rules which describe  the
       operating  calendar  and  daily  schedule.  such  rules  are  designed  to mimic real-life
       situations like week-end blocked days or Christmas vacation day.

       Slot allocation
       A slot is allocated with the get-slotmethod. This method is  common  to  the  Appointerand
       Assistantclasses.

       # allocate a 1 hour slot
       const slot (appt:get-slot 3600)

       In  the example above, a 1 hour slot is allocated at the current appointer time. Note that
       the time and duration are always given in seconds. If  the  slot  needs  to  be  allocated
       starting at a certain time, the 2 arguments form can be used.

       # allocate a 1 hour slot starting at 2AM
       const slot (appt:get-slot 7200 3600)

       In  the presence of an Assistantobject the get-slotis the same but selects the appropriate
       appointer with the help of an internal index which rotated after each  call.  This  method
       permits an equal distribution for all appointers within an assistant.

       Appointer rules
       There  are  basically,  two types of appointer's rules. The first type of rule is used for
       blocking a day as a whole. The second type of rule is designed to describe  valid  periods
       of allocation time. The first type of rules is called the and rulessince all rules must be
       valid in order to allocate a slot at the requested time. The second type is a  called  the
       or rulessince only one rule needs to be valid in order to allocate a slot.

       # create a reference appointer
       const appt (afnix:csm:Appointer)
       # add a saturday and sunday blocked day rule
       appt:set-blocked-day 6
       appt:set-blocked-day 0
       # set the special days
       appt:set-special-day  1  1
       appt:set-special-day 12 25

       The  example  above  defines  an  appointer object. The first 2 rules defines Saturday and
       Sunday as blocked days. The other 2 rules, defines Jan 1st and Dec 25th as  special  days.
       No slot can be allocated in a blocked or special day.

       # set a valid block time between 8AM to 12AM
       const ambt (* 3600 8)
       const amet (* 3600 12)
       const pmbt (* 3600 14)
       # set a valid block time between 2PM to 6PM
       const pmet (* 3600 18)
       appt:set-valid-block-time ambt amet
       appt:set-valid-block-time pmbt pmet

       the  above  example  defines  two valid periods for allocating time. The first period runs
       from 8AM to 12AM and the second one runs from 2PM to 6PM.  Note  that  the  time  is  also
       expressed  in  second.  The  time  arguments  are  always rounded to the maximum number of
       seconds per day.

       Assistant operations
       An assistant object is build by adding object to it. In general,  a  reference  object  is
       created, and several of them are added to the assistant by cloning the reference object.

       Assistant integration
       Once an assistant object has been created, the object can be added by cloning.

       # create an assistant
       const name "Mr Smith"
       const info "The super assistant"
       const asst (afnix:csm:Assistant name info)
       # create a reference appointer
       const appt (afnix:csm:Appointer)
       # add 2 appointers by cloning
       asst:add-appointer (appt:clone)
       asst:add-appointer (appt:clone)

       In  the case of an Appointerobject, the appointer is cloned with all its rules attached to
       it. This method is particularly useful when an assistant needs to  be  setup  for  several
       person that shares the same calendar.

STANDARD CLOUD SESSION MANAGEMENT REFERENCE

       Slot
       The  Slotclass  is  a  base class designed to handle a basic time slot event. The class is
       defined with a date and a duration. The slot class is primarily used to build an agenda.

       Predicate

              slot-p

       Inheritance

              Object

       Constructors

              Slot (none)
              The Slotconstructor creates an empty slot initialized at time 0 with duration 0.

              Slot (Integer Integer)
              The Slotconstructor creates a slot with a time and duration. The first argument  is
              the slot time. The second argument is the slot duration.

       Methods

              reset -> none (none)
              The resetmethod reset the slot to time 0 with duration 0.

              set-time -> none (Integer)
              The set-timemethod sets the slot time.

              get-time -> Integer (none)
              The get-timemethod returns the slot time.

              set-duration -> none (Integer)
              The set-durationmethod sets the slot duration.

              get-duration -> Integer (none)
              The get-durationmethod returns the slot duration.

              set-slot -> none (Integer Integer)
              The  set-slotmethod  sets the slot time and duration at once. The first argument is
              the slot time. The second argument is the slot duration.

       Appointer
       The Appointerclass is a class design to allocate time slot in a calendar in order to  fill
       an  agenda.  The  appointer  do  not  store  the  slot but rather acts as a generator. the
       appointer algorithm operates with rules that permits to allocate the next available  slot.
       The  basic  rules permits to define regular blocked days and special blocked days. Another
       rule permits to define an operating time period. Multiple  time  periods  are  allowed.  A
       maximum daily slots rule is also available.

       Predicate

              appointer-p

       Inheritance

              Object

       Constructors

              Appointer (none)
              The  Appointerconstructor  creates a default appointer initialized at time 0. There
              is no rule installed by the constructor.

              Appointer (Integer)
              The Appointerconstructor creates an appointer with an initial time. The time is set
              as  he  starting  time  to  allocate  slots.  There  is  no  rule  installed by the
              constructor.

       Methods

              reset -> none (none)
              The resetmethod reset the appointer slot number and daily slot counter.  The  rules
              are not touched by this method.

              set-time -> none (Integer)
              The  set-timemethod  set  the  appointer time. During the next operation, the newly
              allocated slots have their time starting at least at this time.

              get-time -> Integer (none)
              The get-timemethod returns the current appointer time.

              set-date -> none (Date)
              The set-datemethod set the appointer time by converting  the  date  argument  to  a
              time.

              get-date -> Integer (none)
              The get-datemethod returns the current appointer date.

              get-slot -> Slot (Integer|Integer Integer)
              The get-slotmethod returns a new slot allocated by the appointer. with one argument
              the argument is taken as the slot duration. With 2 arguments, the  first  arguments
              is  the  requested slot time and the second argument is the slot duration. The slot
              allocation algorithm operates  by  finding  the  appropriate  day  and  time  which
              satisfies  the  appointer  rules.  If the slot cannot be found within one week, the
              allocation is assumed to have failed.

              get-slot-number -> Integer (none)
              The get-slot-numbermethod returns the  total  number  of  slots  allocated  by  the
              appointer.

              set-blocked-day -> none (Integer)
              The set-blocked-daymethod sets a regular weekly block day. The method uses the week
              day index as its argument. Sunday has index 0 and Saturday has index 6. No slot  is
              allocated in a blocked day.

              set-special-day -> none (Integer Integer)
              The  set-special-daymethod  sets a special year day. The method uses the year month
              and the month day index as its arguments. The first  argument  is  the  year  month
              which  must  be in the range of 1 to 12. The second argument is the month day which
              must be in the range of 1 to 31. No slot is allocated in a special day.

              set-maximum-slots -> none (Integer)
              The set-maximum-slotsmethod sets a daily  maximum  slots  number.  When  the  daily
              maximum slot number is reached, the slot allocation proceed to the next day.

              set-valid-block-time -> none (Integer Integer)
              The  set-valid-block-timemethod  sets  a  valid block time in which the slot can be
              allocated. By default, a slot can be allocated anytime during the  day.  When  this
              rule  is  set,  at  least once, the slot is allocated in this block. Multiple valid
              block time can be defined. The first argument is the valid block time  lower  bound
              expressed  in  seconds from 12PM. The second argument is the valid block time upper
              bound. All time are expressed in seconds and rounded to a day second which is 84600
              seconds  in  24 hours. For example, a valid block time is from 8AM to 12AM. Another
              would be from 2PM to 6PM.

       Assistant
       The Assistantclass class is a generic class designed to hold  various  csm  component  and
       manage  them  like  an  assistant  will  do.  For  example,  the  class  can store several
       Appointerobjects and distribute slot for all of them.

       Predicate

              assistant-p

       Inheritance

              Object

       Constructors

              Assistant (none)
              The Assistantconstructor creates a default assistant.

              Assistant (String)
              The Assistantconstructor creates a default assistant by name.

              Assistant (String String)
              The Assistantconstructor creates a default assistant by name and  information.  The
              first  argument  is  the  assistant  name.  the  second  argument  is the assistant
              information string.

       Methods

              reset -> none (none)
              The resetmethod reset the assistant by. All objects attached to the  assistant  are
              reset by this method.

              get-name -> String (none)
              The get-namemethod returns the assistant name.

              get-info -> String (none)
              The get-infomethod returns the assistant information string.

              pushback -> none (Slot)
              The  pushbackmethod  pushbaks  a  slot in the appointer list. The assistant manages
              internally an index which is used to select the appointer where the slot is pushed-
              back.

              get-slot -> Slot (Integer|Integer Integer)
              The  get-slotmethod  returns  he  next  available slot from the appointer list. The
              assistant manages internally an index which is used to select  the  appointer  from
              which  the  slot  is  obtained.  With one argument, the method operates with a slot
              duration. with 2 arguments, the method operates by time and duration. The  time  is
              the  minimum time for which the slot is allocated. If the slot cannot be allocated,
              an exception is raised.

              add-appointer -> none (Appointer)
              The add-appointermethod adds an appointer object to the assistant.

              get-appointer -> Appointer (Integer)
              The get-appointermethod returns an appointer object  by  index.  If  the  appointer
              object cannot be found, an exception is raised.

              length-appointer -> Integer (none)
              The  length-appointermethod  returns  the  number  of  appointers  attached  to the
              assistant.

              get-slot-number -> Integer (none)
              The get-slot-numbermethod returns  the  total  number  of  slot  allocated  by  the
              assistant  at  the  time  of  the  call. The number is computed by summing all slot
              numbers for each appointers. attached to the assistant.

              get-appointer-time -> Integer (none)
              The get-appointer-timemethod returns the average appointer time  for  the  attached
              appointers. At the time of the call, each appointer has a time which corresponds to
              the next slot available time. The average time for all appointers is the result  of
              this method which corresponds to the average time of the next available slot.

       Session
       The  Sessionclass  that  defines  a session to be associated with a cloud transaction. The
       session object is designed to be persistent so that its data information can be  retrieved
       at  any  time.  A  session object has also the particularity to have a limited lifetime. A
       session object is created by name with an identifier. If a path is given, such  path  will
       be used as the session file name.

       Predicate

              session-p

       Inheritance

              Serial

       Constructors

              Session (String)
              The  Sessionconstructor  creates  a  session  by  name.  The string argument is the
              session name.

              Session (String String)
              The Sessionconstructor creates a session with a name and a user. The first argument
              is the session name. The second argument is the user name.

              Session (String String Integer)
              The Sessionconstructor creates a session with a name, a user and a maximum age. The
              first argument is the session name. The second argument is the session  user  name.
              The third argument is the session maximum age expressed in seconds.

       Methods

              expire-p -> Boolean (none)
              The expire-ppredicate returns true if the session has expired.

              get-name -> String (none)
              The get-namemethod returns the session name.

              set-user -> none (String)
              The set-usermethod sets the session user name.

              get-session-rid -> String (none)
              The get-session-ridmethod returns the session rid.

              set-session-rid -> none (String)
              The set-session-ridmethod sets the session rid.

              get-user -> String (none)
              The get-usermethod returns the session user name.

              set-hash-id -> none (String)
              The set-hash-idmethod sets the session hash identifier. The session hash id must be
              unique and secured enough so that the session name cannot be derived from it.

              get-hash-id -> String (none)
              The get-hash-idmethod returns the session hash identifier.

              set-path -> none (String)
              The set-pathmethod sets the session path.

              get-path -> String (none)
              The get-pathmethod returns the session path.

              get-max-age -> Integer (none)
              The get-max-agemethod returns the session maximum age.

              set-max-age -> none (Integer)
              The set-max-agemethod sets the session maximum age. The maximum age is  an  integer
              in  seconds  relative  to  the  current  time.  If the maximum age is set to 0, the
              session is closed.

              get-remaining-time -> Integer (none)
              The get-remaining-timemethod returns the remaining valid session time.

              get-expire-time -> Integer (none)
              The get-expire-timemethod returns the  session  expiration  time  in  seconds.  The
              expiration time is an absolute time.

              set-expire-time -> none (Integer)
              The  set-expire-timemethod sets the session expiration time. The expiration time is
              an absolute time in seconds.

              get-creation-time -> Integer (none)
              The get-creation-timemethod returns the session creation time. The creation time is
              an absolute time in seconds.

              get-modification-time -> Integer (none)
              The get-modification-timemethod returns the session creation time. The modification
              time is an absolute time in seconds.

              get-cookie -> Cookie (name)
              The get-cookiemethod bakes a session cookie. The string argument is the cookie name
              those value is the session hash id value.

              close -> Cookie (name)
              The  closemethod  close  a  session  by  reseting the session maximum age to 0. The
              method returns a cookie that can be used for closing the session on the peer  side.
              The string argument is the cookie name those value is the session hash id value.