<?xml version="1.0" encoding="UTF-8"?>

<!-- ====================================================================== -->
<!-- = csmrm.xml                                                          = -->
<!-- = standard csm service - reference manual                             = -->
<!-- ====================================================================== -->
<!-- = This  program  is  free  software; you  can redistribute it and/or = -->
<!-- = modify it provided that this copyright notice is kept intact.      = -->
<!-- = This program is distributed in the hope that it will be useful but = -->
<!-- = without  any  warranty;  without  even  the  implied  warranty  of = -->
<!-- = merchantability or fitness for  a  particular purpose. In no event = -->
<!-- = shall  the  copyright  holder be liable for any  direct, indirect, = -->
<!-- = incidental  or special  damages arising  in any way out of the use = -->
<!-- = of this software.                                                  = -->
<!-- ====================================================================== -->
<!-- = copyright (c) 1999-2013 - amaury darsch                            = -->
<!-- ====================================================================== -->

<appendix service="csm" number="i">
  <title>Standard Cloud Session Management Reference</title>

  <!-- =================================================================== -->
  <!-- = slot object                                                     = -->
  <!-- =================================================================== -->

  <object nameset="afnix:csm">
    <name>Slot</name>

    <p>
      The <code>Slot</code> class 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.
    </p>

    <!-- predicate -->
    <pred>slot-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Object</name>
    </inherit>

    <!-- constructors -->
    <ctors>
      <ctor>
	<name>Slot</name>
	<args>none</args>
	<p>
	  The <code>Slot</code> constructor creates an empty slot
	  initialized at time 0 with duration 0.
	</p>
      </ctor>

      <ctor>
	<name>Slot</name>
	<args>Integer Integer</args>
	<p>
	  The <code>Slot</code> constructor creates a slot with a time and
	  duration. The first argument is the slot time. The second
	  argument is the slot duration.
	</p>
      </ctor>
    </ctors>

    <!-- methods -->
    <methods>
      <meth>
	<name>reset</name>
	<retn>none</retn>
	<args>none</args>
	<p>
	  The <code>reset</code> method reset the slot to time 0 with
	  duration 0.
	</p>
      </meth>

      <meth>
	<name>set-time</name>
	<retn>none</retn>
	<args>Integer</args>
	<p>
	  The <code>set-time</code> method sets the slot time.
	</p>
      </meth>

      <meth>
	<name>get-time</name>
	<retn>Integer</retn>
	<args>none</args>
	<p>
	  The <code>get-time</code> method returns the slot time.
	</p>
      </meth>

      <meth>
	<name>set-duration</name>
	<retn>none</retn>
	<args>Integer</args>
	<p>
	  The <code>set-duration</code> method sets the slot duration.
	</p>
      </meth>

      <meth>
	<name>get-duration</name>
	<retn>Integer</retn>
	<args>none</args>
	<p>
	  The <code>get-duration</code> method returns the slot duration.
	</p>
      </meth>

      <meth>
	<name>set-slot</name>
	<retn>none</retn>
	<args>Integer Integer</args>
	<p>
	  The <code>set-slot</code> method sets the slot time and duration
	  at once. The first argument is the slot time. The second
	  argument is the slot duration.
	</p>
      </meth>
    </methods>
  </object>

  <!-- =================================================================== -->
  <!-- = appointer object                                                = -->
  <!-- =================================================================== -->

  <object nameset="afnix:csm">
    <name>Appointer</name>

    <p>
      The <code>Appointer</code> class 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.
    </p>

    <!-- predicate -->
    <pred>appointer-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Object</name>
    </inherit>

    <!-- constructors -->
    <ctors>
      <ctor>
	<name>Appointer</name>
	<args>none</args>
	<p>
	  The <code>Appointer</code> constructor creates a default appointer
	  initialized at time 0. There is no rule installed by the constructor.
	</p>
      </ctor>

      <ctor>
	<name>Appointer</name>
	<args>Integer</args>
	<p>
	  The <code>Appointer</code> constructor 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.
	</p>
      </ctor>
    </ctors>

    <!-- methods -->
    <methods>
      <meth>
	<name>reset</name>
	<retn>none</retn>
	<args>none</args>
	<p>
	  The <code>reset</code> method reset the appointer slot number
	  and daily slot counter. The rules are not touched by this method.
	</p>
      </meth>

      <meth>
	<name>set-time</name>
	<retn>none</retn>
	<args>Integer</args>
	<p>
	  The <code>set-time</code> method set the appointer time. During
	  the next operation, the newly allocated slots have their time
	  starting at least at this time.
	</p>
      </meth>

      <meth>
	<name>get-time</name>
	<retn>Integer</retn>
	<args>none</args>
	<p>
	  The <code>get-time</code> method returns the current appointer time.
	</p>
      </meth>

      <meth>
	<name>set-date</name>
	<retn>none</retn>
	<args>Date</args>
	<p>
	  The <code>set-date</code> method set the appointer time
	  by converting the date argument to a time.
	</p>
      </meth>

      <meth>
	<name>get-date</name>
	<retn>Integer</retn>
	<args>none</args>
	<p>
	  The <code>get-date</code> method returns the current appointer date.
	</p>
      </meth>

      <meth>
	<name>get-slot</name>
	<retn>Slot</retn>
	<args>Integer|Integer Integer</args>
	<p>
	  The <code>get-slot</code> method 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.
	</p>
      </meth>

      <meth>
	<name>get-slot-number</name>
	<retn>Integer</retn>
	<args>none</args>
	<p>
	  The <code>get-slot-number</code> method returns the total number
	  of slots allocated by the appointer.
	</p>
      </meth>

      <meth>
	<name>set-blocked-day</name>
	<retn>none</retn>
	<args>Integer</args>
	<p>
	  The <code>set-blocked-day</code> method 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.
	</p>
      </meth>

      <meth>
	<name>set-special-day</name>
	<retn>none</retn>
	<args>Integer Integer</args>
	<p>
	  The <code>set-special-day</code> method 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.
	</p>
      </meth>

      <meth>
	<name>set-maximum-slots</name>
	<retn>none</retn>
	<args>Integer</args>
	<p>
	  The <code>set-maximum-slots</code> method sets a daily maximum
	  slots number. When the daily maximum slot number is reached, the
	  slot allocation proceed to the next day.
	</p>
      </meth>

      <meth>
	<name>set-valid-block-time</name>
	<retn>none</retn>
	<args>Integer Integer</args>
	<p>
	  The <code>set-valid-block-time</code> method 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.
	</p>
      </meth>
    </methods>
  </object>

  <!-- =================================================================== -->
  <!-- = appointer object                                                = -->
  <!-- =================================================================== -->

  <object nameset="afnix:csm">
    <name>Assistant</name>

    <p>
      The <code>Assistant</code> class 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
      <code>Appointer</code> objects and distribute slot for all of
      them.
    </p>

    <!-- predicate -->
    <pred>assistant-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Object</name>
    </inherit>

    <!-- constructors -->
    <ctors>
      <ctor>
	<name>Assistant</name>
	<args>none</args>
	<p>
	  The <code>Assistant</code> constructor creates a default assistant.
	</p>
      </ctor>

      <ctor>
	<name>Assistant</name>
	<args>String</args>
	<p>
	  The <code>Assistant</code> constructor creates a default
	  assistant by name.
	</p>
      </ctor>

      <ctor>
	<name>Assistant</name>
	<args>String String</args>
	<p>
	  The <code>Assistant</code> constructor creates a default
	  assistant by name and information. The first argument is the
	  assistant name. the second argument is the assistant information
	  string.
	</p>
      </ctor>
    </ctors>

    <!-- methods -->
    <methods>
      <meth>
	<name>reset</name>
	<retn>none</retn>
	<args>none</args>
	<p>
	  The <code>reset</code> method reset the assistant by. All
	  objects attached to the assistant are reset by this method.
	</p>
      </meth>

      <meth>
	<name>get-name</name>
	<retn>String</retn>
	<args>none</args>
	<p>
	  The <code>get-name</code> method returns the assistant name.
	</p>
      </meth>

      <meth>
	<name>get-info</name>
	<retn>String</retn>
	<args>none</args>
	<p>
	  The <code>get-info</code> method returns the assistant
	  information string.
	</p>
      </meth>

      <meth>
	<name>pushback</name>
	<retn>none</retn>
	<args>Slot</args>
	<p>
	  The <code>pushback</code> method 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.
	</p>
      </meth>

      <meth>
	<name>get-slot</name>
	<retn>Slot</retn>
	<args>Integer|Integer Integer</args>
	<p>
	  The <code>get-slot</code> method 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.
	</p>
      </meth>

      <meth>
	<name>add-appointer</name>
	<retn>none</retn>
	<args>Appointer</args>
	<p>
	  The <code>add-appointer</code> method adds an appointer object
	  to the assistant.
	</p>
      </meth>

      <meth>
	<name>get-appointer</name>
	<retn>Appointer</retn>
	<args>Integer</args>
	<p>
	  The <code>get-appointer</code> method returns an appointer object
	  by index. If the appointer object cannot be found, an exception
	  is raised.
	</p>
      </meth>

      <meth>
	<name>length-appointer</name>
	<retn>Integer</retn>
	<args>none</args>
	<p>
	  The <code>length-appointer</code> method returns the number of
	  appointers attached to the assistant.
	</p>
      </meth>

      <meth>
	<name>get-slot-number</name>
	<retn>Integer</retn>
	<args>none</args>
	<p>
	  The <code>get-slot-number</code> method 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.
	</p>
      </meth>

      <meth>
	<name>get-appointer-time</name>
	<retn>Integer</retn>
	<args>none</args>
	<p>
	  The <code>get-appointer-time</code> method 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.
	</p>
      </meth>
    </methods>
  </object>

  <!-- =================================================================== -->
  <!-- = session object                                                  = -->
  <!-- =================================================================== -->

  <object nameset="afnix:csm">
    <name>Session</name>

    <!-- synopsis -->
    <p>
      The <code>Session</code> class 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.
    </p>

    <!-- predicate -->
    <pred>session-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Serial</name>
    </inherit>

    <!-- constructors -->
    <ctors>
      <ctor>
	<name>Session</name>
	<args>String</args>
	<p>
	  The <code>Session</code> constructor creates a session by name.
	  The string argument is the session name.
	</p>
      </ctor>

      <ctor>
	<name>Session</name>
	<args>String String</args>
	<p>
	  The <code>Session</code> constructor creates a session with a name
	  and a user. The first argument is the session name. The second
	  argument is the user name.
	</p>
      </ctor>

      <ctor>
	<name>Session</name>
	<args>String String Integer</args>
	<p>
	  The <code>Session</code> constructor 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.
	</p>
      </ctor>
    </ctors>

    <!-- methods -->
    <methods>
      <meth>
	<name>expire-p</name>
	<retn>Boolean</retn>
	<args>none</args>
	<p>
	  The <code>expire-p</code> predicate returns true if the session
	  has expired.
	</p>
      </meth>

      <meth>
	<name>get-name</name>
	<retn>String</retn>
	<args>none</args>
	<p>
	  The <code>get-name</code> method returns the session name.
	</p>
      </meth>

      <meth>
	<name>set-user</name>
	<retn>none</retn>
	<args>String</args>
	<p>
	  The <code>set-user</code> method sets the session user name.
	</p>
      </meth>

      <meth>
	<name>get-session-rid</name>
	<retn>String</retn>
	<args>none</args>
	<p>
	  The <code>get-session-rid</code> method returns the session rid.
	</p>
      </meth>

      <meth>
	<name>set-session-rid</name>
	<retn>none</retn>
	<args>String</args>
	<p>
	  The <code>set-session-rid</code> method sets the session rid.
	</p>
      </meth>

      <meth>
	<name>get-user</name>
	<retn>String</retn>
	<args>none</args>
	<p>
	  The <code>get-user</code> method returns the session user name.
	</p>
      </meth>

      <meth>
	<name>set-hash-id</name>
	<retn>none</retn>
	<args>String</args>
	<p>
	  The <code>set-hash-id</code> method 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.
	</p>
      </meth>

      <meth>
	<name>get-hash-id</name>
	<retn>String</retn>
	<args>none</args>
	<p>
	  The <code>get-hash-id</code> method returns the session hash
	  identifier. 
	</p>
      </meth>

      <meth>
	<name>set-path</name>
	<retn>none</retn>
	<args>String</args>
	<p>
	  The <code>set-path</code> method sets the session path.
	</p>
      </meth>

      <meth>
	<name>get-path</name>
	<retn>String</retn>
	<args>none</args>
	<p>
	  The <code>get-path</code> method returns the session path.
	</p>
      </meth>

      <meth>
	<name>get-max-age</name>
	<retn>Integer</retn>
	<args>none</args>
	<p>
	  The <code>get-max-age</code> method returns the session
	  maximum age.
	</p>
      </meth>

      <meth>
	<name>set-max-age</name>
	<retn>none</retn>
	<args>Integer</args>
	<p>
	  The <code>set-max-age</code> method 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.
	</p>
      </meth>

      <meth>
	<name>get-remaining-time</name>
	<retn>Integer</retn>
	<args>none</args>
	<p>
	  The <code>get-remaining-time</code> method returns the remaining
	  valid session time.
	</p>
      </meth>

      <meth>
	<name>get-expire-time</name>
	<retn>Integer</retn>
	<args>none</args>
	<p>
	  The <code>get-expire-time</code> method returns the session
	  expiration time in seconds. The expiration time is an absolute
	  time.
	</p>
      </meth>

      <meth>
	<name>set-expire-time</name>
	<retn>none</retn>
	<args>Integer</args>
	<p>
	  The <code>set-expire-time</code> method sets the session
	  expiration time. The expiration time is an absolute time in seconds.
	</p>
      </meth>

      <meth>
	<name>get-creation-time</name>
	<retn>Integer</retn>
	<args>none</args>
	<p>
	  The <code>get-creation-time</code> method returns the session
	  creation time. The creation time is an absolute time in seconds.
	</p>
      </meth>

      <meth>
	<name>get-modification-time</name>
	<retn>Integer</retn>
	<args>none</args>
	<p>
	  The <code>get-modification-time</code> method returns the session
	  creation time. The modification time is an absolute time in seconds.
	</p>
      </meth>

      <meth>
	<name>get-cookie</name>
	<retn>Cookie</retn>
	<args>name</args>
	<p>
	  The <code>get-cookie</code> method bakes a session
	  cookie. The string argument is the cookie name those value
	  is the session hash id value.
	</p>
      </meth>
      <meth>
	<name>close</name>
	<retn>Cookie</retn>
	<args>name</args>
	<p>
	  The <code>close</code> method 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.
	</p>
      </meth>
    </methods>
  </object>
</appendix>
