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

<!-- ====================================================================== -->
<!-- = csmwm.xml                                                          = -->
<!-- = standard csm service - writer 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                            = -->
<!-- ====================================================================== -->

<chapter service="csm" number="1">
  <title>Standard Cloud Session Management Service</title>
  
  <p>
    The <em>Standard Cloud Session Management</em> service 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.
  </p>

  <!-- general concepts -->
  <section>
    <title>General concepts</title>

    <p>
      The <code>afnix-csm</code> provides 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.
    </p>

    <!-- slot -->
    <subsect>
      <title>Slot</title>
      
      <p>
	The concept of slot is central in the <em>csm</em> service. A
	slot is a combination of time and duration. A slot is allocated
	by an appointer to indicate the next available <em>slot</em>. 
	For an agenda, the concept of slot can be derived to describe an
	appointment.
      </p>
    </subsect>

    <!-- appointer -->
    <subsect>
      <title>Appointer</title>
      
      <p>
	An <em>appointer</em> is 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.
      </p>
    </subsect>

    <!-- assistant -->
    <subsect>
      <title>Assistant</title>
      
      <p>
	An <em>assistant</em> is a combination of csm object like
	appointers. An assistant can be used for example, to manage
	several appointers.
      </p>
    </subsect>
  </section>

  <!-- appointers operations -->
  <section>
    <title>Appointer operations</title>

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

    <!-- slot allocation -->
    <subsect>
      <title>Slot allocation</title>
      
      <p>
	A slot is allocated with the <code>get-slot</code> method. This
	method is common to the <code>Appointer</code> and
	<code>Assistant</code> classes.
      </p>

      <example>
	# allocate a 1 hour slot
	const slot (appt:get-slot 3600)
      </example>

      <p>
	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.
      </p>

      <example>
	# allocate a 1 hour slot starting at 2AM
	const slot (appt:get-slot 7200 3600)
      </example>
      
      <p>
	In the presence of an <code>Assistant</code> object the
	<code>get-slot</code> is 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.
      </p>
    </subsect>

    <!-- appointer rules -->
    <subsect>
      <title>Appointer rules</title>

      <p>
	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 <em>and rules</em>
	since all rules must be valid in order to allocate a slot at the
	requested time. The second type is a called the <em>or
	rules</em> since only one rule needs to be valid in order to
	allocate a slot.
      </p>

      <example>
	# 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
      </example>
      
      <p>
	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.
      </p>

      <example>
	# 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
      </example>

      <p>
	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.
      </p>
    </subsect>
  </section>

  <!-- assistant operations -->
  <section>
    <title>Assistant operations</title>

    <p>
      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.
    </p>

    <subsect>
      <title>Assistant integration</title>

      <p>
	Once an assistant object has been created, the object can be
	added by cloning.
      </p>

      <example>
	# 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)
      </example>

      <p>
	In the case of an <code>Appointer</code> object, 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.
      </p>
    </subsect>
  </section>
</chapter>
