(****
 *
 * Module CalendarDB defines the major database objects of the calendar system
 * as well as the objects that define the underlying calendar structure.  The
 * core object of the calendar system is the UserCalendar, which is modeled as
 * a collection of scheduled items.  The calendar structure of years, months,
 * weeks, and days is not directly modeled in the UserCalendar.  These
 * structures are computed views that are derived from the underlying scheduled
 * item collection.
 *
 *)

module CalendarDB;

  from Schedule import ScheduledItem, Date, Categories;
  from View import CustomLists, Filtering, WindowingMode;
  from Admin import UserDB, GroupDB, LocationDB, UserId;
  from File import FileSpace, File;
  from Edit import Clipboard, Selection, SelectionContext;
  from Options import Options, RegularUserOptions;
  export CalendarDB, UserWorkSpace, UserCalendar, RequiresSaving,
        PreviousState, CalendarSpecificSettings;

  object CalendarDB
    components: user_calendars:UserCalendars and user_db:UserDB and
        group_db:GroupDB and loc_db:LocationDB and options:Options and
        workspace:UserWorkSpace;
    description: (*
        The CalendarDB is the top-level object for the Calendar Tool.  The
        first component is the list of UserCalendars for all registered users.
        The next three components are the registered UserDB, the user GroupDB,
        and the LocationDB.  The Options component is the set of calendar
        options common by default for all users, both registered and
        non-registered.  The UserWorkSpace component is active calendars upon
        which the current user is working.
    *);
  end;

  object UserWorkSpace
    components: uid:UserId and calendars:UserCalendar* and
        num_unnamed:integer and 
        previous_state:PreviousState and clipboard:Clipboard and
        selection:Selection and context:SelectionContext;
    description: (*
        The UserWorkSpace contains the active calendars upon which the user
        working.  The first component is the UserId of the current user, which
        is used as necessary by operations that input the workspace to
        determine who the user is.  The UserCalendar* component is the list of
        active calendars; the list is maintained in the order visited by the
        user, with the first element being the most recently visited, and hence
        current, and the last element being the earliest visited.  The third
        integer component is the number of unnamed calendars, used by File->New
        to give unnamed calendars unique names.  The previous_state component
        is used to support one level of command undo.  The Clipboard is used
        with the Edit cut, copy, and paste operations.
    *);
  end;

  object PreviousState
    components: ScheduledItem*;
    description: (*
        PreviousState is the snapshot of scheduled items before the most
        recently performed scheduling operation used by EditUndo.  The
        Schedule, Change, and Delete operations save the previous state to
        support Undo.
    *);
  end PreviousState;

  object UserCalendars
    components: UserCalendarFileName*;
    description: (*
        UserCalendars is the list of public calendars for all registered users.
        The list consists of calendar file names, not calendars themselves.  In
        this way, the list of user calendars is modeled as a distributed
        collection of user calendar files, not as a centralized database of
        calendars.  This allows users to retain autonomous control of their own
        individual calendars.
    *);
  end UserCalendars;

  object UserCalendarFileName is string
    description: (*
        A UserCalendarFileName is the unique path to a user calendar file.  The
        specific syntax of such a path is implementation-platform-specific.  In
        general, a file path is a sequence of file directory names, ending in a
        file name.
    *);
  end UserCalendarFileName;

  (* NOTE: We may need to separate a UserCalendar into a local and remote
  versions, with only the latter having ther UID, the reason being that
  locally, a calendar shouldn't have an ID, in case the user hooks it up to
  more than one host.  19jul94 Update: Well, we may not even need the ID to be
  n a comoonent of a UserCalendar, since whenever we're connected a host, we
  have a host table entry that tells us the user's ID.  I'm pretty sure this
  will work, and it will be confirmed when we get to the pre/post conds that
  require us to access the user ID.  I would think that all we have to do to
  make it work is to pass in whatever object houses the connection table,
  presumably the workspace, to whatever ops need to know the user ID. *)
  object UserCalendar
    components: items:ScheduledItem* and settings:CalendarSpecificSettings and
        uid:UserId and name:CalendarName and file:File and 
        selected_date:Date and requires_saving:RequiresSaving;
    description: (*
        FIX this to agree with (updated) components
        A UserCalendar has a list of scheduled items and the calendar-specific
        information for categories, custom lists, filters, options, and
        windowing mode.  Calendar bookkeepting components are the ID of the
        user who owns the calendar, the file it's stored on, the currently
        selected date, and a flag indicating if the calendar requires saving.
    *);
  end UserCalendar;

  object UserName is string
    description: (* The name of a registered user. *);
  end Username;

  object CalendarName is string
    description: (* The name of a user calendar. *);
  end CalendarName;

  object RequiresSaving is boolean
    description: (*
        True if a calendar requires saving, which is the case if one or more
        successful edit operations has been performed on the calendar since the
        most recent save.  The calendar edit operations are Schedule, Change,
        and Delete.
    *);
  end RequiresSaving;

  object Settings
    components: CalendarSpecificSettings and SessionWideSettings;
    description: (*
        The stuff stored in a settings file.  Need to figure out if we want to
        cache a copy of this in the user (or tool-wide (if there is such a
        thing)) workspace or just always get it from the file.  It would seem
        from the requirments that it does always come from the file, so
        defining a cached version in the model may be crossing the boudary into
        imple.
    *);
  end Settings;

  object CalendarSpecificSettings
    components: Categories and CustomLists and FilterSettings and CustomFilters
       and WindowsState and WindowingMode and options:RegularUserOptions;
    description: (*

    *);
  end CalendarSpecificSettings;

  object SessionWideSettings
    components: OpenCalendarNames and HostConnectionTable;
    description: (*
       
    *);
  end SessionWideSettings;

  (* TBD: *)
  obj FilterSettings;
  obj CustomFilters;
  obj WindowsState;
  obj OpenCalendarNames;
  obj HostConnectionTable;

end CalendarDB;