  <chapter id="calendar-architecture">
    <title>Architecture of the Calendar</title>

    <para>
      This chapter gives an overview of the &Evolution; Calendar
      architecture.  It describes the model/view split of the calendar
      into a personal calendar server, or &PCS;, and the GUI clients
      that appear inside the &Evolution; Shell.
    </para>

    <!-- Model/View Separation -->

    <sect1 id="calendar-model-view">
      <title>Model/View Separation</title>

      <para>
	Like other base components in &Evolution;, the calendar
	separates the data model from the views or clients.  This is
	done so that multiple clients can access the same calendar
	data in an orderly fashion and without clashes.  For example,
	the user may be running a graphical calendar client.  If he
	then wants to synchronize his calendar with a handheld device,
	then the corresponding synchronization program (e.g. a conduit
	for the <application>gnome-pilot</application> package) will
	also need to access the calendar storage.  It is important
	that both the GUI client and the synchronization program keep
	a consistent view of the calendar at all times, otherwise one
	of them will be left in an inconsistent state if the
	calendar's data changes unexpectedly.
      </para>

      <para>
	&Evolution; puts the calendar storage in a daemon called the
	&Wombat; and completely separates it from clients who wants to
	access calendar data.  This part of the &Wombat; is called the
	personal calendar server, or &PCS;.  Clients must contact the
	&PCS; and ask it to open an existing calendar or create a new
	one.  When a calendar component object (e.g. an appointment or
	to-do item) changes in the &PCS; it will notify all the
	clients that are using the component's parent calendar.
      </para>
    </sect1>

    <!-- Personal Calendar Server -->

    <sect1>
      <title>Personal Calendar Server</title>

      <para>
	The personal calendar server, or &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>
	  Looking for the events that recur or have alarm triggers in
	  a specific period of time involves scanning all the
	  appointments in a calendar.  To keep clients from having to
	  load whole calendars at once, the &PCS; can do these
	  computations and send the results to clients.
	</para>
      </formalpara>

      <formalpara>
	<title>Modification Log</title>

	<para>
	  To allow multiple handheld devices to be synchronized
	  against a calendar, the &PCS; keeps a log of all the
	  modifications that are done to the calendar.  When an
	  appointment is updated or removed, the &PCS; logs this
	  action in the modification log.  Synchronization conduit
	  programs can then use this information to do their work.
	</para>
      </formalpara>
    </sect1>

    <!-- Data Views -->

    <sect1>
      <title>Data Views</title>

      <para>
	&Evolution; provides a graphical calendar client inside the
	shell that is just a view onto the data stored in the personal
	calendar server.  You can launch as many views of a calendar
	as you like and they will all receive notification from the
	&PCS; when changes occur.  The views are then responsible for
	updating their respective displays.
      </para>

      <para>
	Even within a single calendar view in the &Evolution; shell
	there can be multiple clients of a single calendar.  For
	example, in the day view of the &Evolution; calendar there are
	three widgets that act as three different clients of the
	&PCS;:  the multi-day view, the busy days calendar, and the
	task list.
      </para>
    </sect1>

    <!-- Non-graphical Clients -->

    <sect1>
      <title>Non-graphical Clients</title>

      <para>
	Clients of the personal calendar server can be non-graphical,
	that is, they do not have to provide views of the data to the
	user.  Examples of such clients are the synchronization
	conduit programs for handheld devices.  These usually run with
	no user interface as a result of being invoked by a daemon
	that watches the connection to a handheld device.  For
	example, the calendar synchronization conduit in &Evolution;
	gets run when the <application>gpilotd</application> daemon
	from the <application>gnome-pilot</application> package
	detects that the HotSync button has been pressed on a Palm
	Pilot device.
      </para>

      <para>
	Such clients simply take advantage of the centralized storage
	in the &PCS; without presenting any graphical display of the
	data; they just act as middlemen between the &PCS; and other
	applications.
      </para>
    </sect1>
  </chapter>

<!--
Local variables:
mode: sgml
sgml-parent-document: ("../evolution-devel-guide.sgml" "book" "part" "")
End:
-->
