evolution/help/white-papers/calendar/calendar.sgml

<!doctype article PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
<!entity Evolution "<application>Evolution</application>">
<!entity CUA "<acronym>CUA</acronym>">
<!entity PCS "<acronym>PCS</acronym>">
<!entity Bonobo "<application>Bonobo</application>">
<!entity CORBA "<acronym>CORBA</acronym>">
<!entity GTK "<acronym>GTK+</acronym>">
]>

<article class="whitepaper" id="calendar">

  <artheader>
    <title>&Evolution; Calendaring Framework</title>

    <authorgroup>
      <author>
	<firstname>Federico</firstname>
	<surname>Mena Quintero</surname>
	<affiliation>
	  <address>
	    <email>federico@helixcode.com</email>
	  </address>
	</affiliation>
      </author>
    </authorgroup>

    <copyright>
      <year>2000</year>
      <holder>Helix Code, Inc.</holder>
    </copyright>

    <abstract>
      <para>
	The &Evolution; groupware suite provides a framework for
	developing calendaring applications, as well as a graphical
	calendar client and a personal calendar server.  This white
	paper describes the architecture of the &Evolution;
	calendaring framework.
      </para>
    </abstract>
  </artheader>

  <!-- Introduction -->

  <sect1 id="introduction">
    <title>Introduction</title>

    <para>
      Calendaring is an important part of a groupware suite.  A
      calendaring framework will allow a user to keep a personal
      calendar and have several applications use it.  Such
      applications could be a graphical calendar client that the user
      employs to schedule appointments and keep track of his time, a
      <productname>Palm Pilot</productname> synchronization client, or
      a simple alarm or reminder utility.  A comprehensive calendaring
      framework will also allow multiple users to schedule
      appointments between each other; for example, a project director
      may want to schedule a weekly meeting with the rest of the
      project members, or a person who owns a large house may want to
      schedule a big party with his friends.  The attendees will then
      want to reply with messages such as, &ldquo;I will
      attend&rdquo;, or &ldquo;I will attend only if the proposed time
      is changed&rdquo;.
    </para>

    <para>
      The &Evolution; groupware suite provides a framework for
      developing calendaring applications, as well as a graphical
      calendar client or calendar user agent (&CUA;) and a personal
      calendar server (&PCS;).
    </para>

    <para>
      The following sections explain the basic calendaring framework,
      the functions of the calendar user agent and the personal
      calendar server, and the relationship between the two.
    </para>
  </sect1>

  <!-- Personal Calendar Server -->

  <sect1 id="pcs">
    <title>Personal Calendar Server</title>

    <para>
      The personal calendar server (&PCS;) provides centralized
      management and storage of a user's personal calendar.  Multiple
      clients can connect to the &PCS; simultaneously to query and
      modify the user's calendar in a synchronized fashion.  The main
      features of the &PCS; are as follows:
    </para>

    <formalpara>
      <title>Storage</title>

      <para>
	The &PCS; is responsible for loading and saving calendars.
	Centralizing the loading and saving functionality allows
	multiple clients to use the same calendar at the same time
	without having to worry about each other.
      </para>
    </formalpara>

    <formalpara>
      <title>Basic Queries</title>

      <para>
	The &PCS; provides functions to do basic queries on a
	calendar, for example, a client can ask the server for a list
	of all the appointments in the calendar, or for all the data
	for a specific appointment.
      </para>
    </formalpara>

    <formalpara>
      <title>Recurrence and Alarm Queries</title>

      <para>
	Clients can ask the &PCS; for a list of the appointments that
	occur within a specified time range; for example a graphical
	client that has a per-week view could ask the &PCS; for all
	the appointments that occur in a particular week.  This
	includes multiple occurrences of a single recurring event; for
	example, the object for &ldquo;a 1-hour meeting that occurs on
	every Tuesday and Thursday&rdquo; is represented inside the
	&PCS; as a single event with a recurrence rule.  Similarly,
	clients can ask the &PCS; for a list of events that have
	alarms that trigger within a specified time range.
      </para>
    </formalpara>

    <formalpara>
      <title>Notification of Changes</title>

      <para>
	This is the most important function of the &PCS;, as it allows
	multiple calendar clients to maintain a unified view of the
	calendar between the server and themselves.  When a client
	asks the &PCS; to modify or remove an event, the &PCS;
	notifies all the clients that are connected to it about the
	change.  The policy is that &ldquo;the server is always
	right&rdquo;; clients can act as dumb views onto the
	calendar's data and they will be notified by the &PCS; when
	something changes.
      </para>
    </formalpara>
  </sect1>

  <!-- Calenar User Agent -->

  <sect1 id="cua">
    <title>Calendar User Agent</title>

    <para>
      A calendar user agent (&CUA;) is a program that lets a user
      manipulate a calendar.  &Evolution; provides an attractive,
      graphical calendar client that communicates with the &Evolution;
      personal calendar server.
    </para>

    <para>
      The &Evolution; calendar client just provides a view onto the
      data that is stored and managed by the personal calendar server.
      The calendar client does not perform direct manipulations on a
      calendar's data; instead it offloads those requests to the
      calendar server, which takes care of making the appropriate
      modifications in the calendar and then notifies all the clients
      about the changes.
    </para>
  </sect1>

  <!-- Calendar Client Library -->

  <sect1 id="client-lib">
    <title>Calendar Client Library</title>

    <para>
      Communication between the personal calendar server and calendar
      clients is defined by a set of &Bonobo; &CORBA; interfaces.
      Clients can be written by implementing the client-side
      <classname>Listener</classname> interface, which defines the
      notification callbacks that the PCS uses to inform clients about
      changes to the calendar.
    </para>

    <para>
      As a convenience for &GTK; programmers, &Evolution; also
      includes a library which provides a
      <classname>CalClient</classname> class which can be used for
      communication with the personal calendar server.  Objects of
      this class automatically contact the PCS when they are created.
      <classname>CalClient</classname> provides functions to request
      changes in the calendar, and it also emits signals when it gets
      notification about changes from the PCS.  This makes it easy and
      convenient to write calendar clients for &Evolution; using
      &GTK;.
    </para>

    <para>
      The implementation of the <classname>CalClient</classname> class
      simply wraps the &Evolution; &CORBA; interfaces for calendaring
      with a familiar-looking &GTK; object.  Calls to the
      <classname>Listener</classname> interface get translated to
      signal emissions from the <classname>CalClient</classname>, thus
      shielding programmers from the details of the &CORBA;
      interfaces.
    </para>
  </sect1>
</article>