(****
 *
 * Module Admin defines the objects and operations related to maintaining the
 * user, group, room, and global options databases of the Calendar Tool.
 *
 *)
module Admin;

  object UserDB is
    components: UserRecord*;
    description: (*
        UserDB is the repository of registered user information.
    *);
  end UserDB;

  object UserRecord is
    components: Name and Id and EmailAddress and PhoneNumber;
    description: (*
        A UserRecord is the information stored about a registered user of the
        Calendar Tool.  The Name component is the user's real-world name.  The
        Id is the unique identifier by which the user is known to the Calendar
        Tool.  The EmailAddress is the electronic mail address used by the
        Calendar Tool to contact the user when necessary.  The PhoneNumber is
        for information purposes; it is not used by the Calendar Tool for
        contacting the user.
    *);
  end UserRecord;

  object Name is string;
  object Id is string;
  object EmailAddress is string;
  object PhoneNumber is Area and Number;
  object Area is integer;
  object Number is integer;

  operation AddUser is
    inputs: UserDB, UserRecord;
    outputs: UserDB;
    description: (*
        Add the given UserRecord to the given UserDB.  The Id of the given user
        record must not be the same as a user record already in the UserDB.
        The Id component is required and must be eight characters or less.  The
        email address is required.  The phone number is optional; if given, the
        area code and number must be 3 and 7 digits respectively.
    *);
  end AddUser;

  operation FindUser is
    inputs: UserDB, Id;
    outputs: UserRecord;
    description: (*
        Find a user by unique id.
    *);
  end FindUser;

  operation FindUser is
    inputs: UserDB, Name;
    outputs: UserRecord*;
    description: (*
        Find a user or users by real-world name.  If more than one is found,
        the output list is sorted by id.
    *);
  end FindUser;

  operation FindUser is
    inputs: UserDB, Id, Name;
    outputs: UserRecord;
    description: (*
        Find a user by both name and id.  This overload of FindUser is
        presumably used infrequently.  Its utility is to confirm that a
        particular user name and id are paired as assumed.
    *);
  end FindUser;

  operation ChangeUser is
    inputs: UserDB, GroupDB, old_ur:UserRecord, new_ur:UserRecord;
    outputs:  UserDB, GroupDB;
    description: (*
        Change the given old UserRecord to the given new record.  The old and
        new records must not be the same.  The old record must already be in
        the input db.  The new record must meet the same conditions as for the
        input to the AddUser operation.  Typically the user runs the FindUser
        operation prior to Change to locate an existing record to be changed.

        If the user record id is changed, then change all occurrences of the
        old id in the group db to the new id.
    *);
  end ChangeUser;

  operation DeleteUser is
    inputs: UserDB, GroupDB, UserRecord;
    outputs: UserDB, GroupDB, LeaderlessGroupsWarning;
    description: (*
        Delete the given user record from the given UserDB.  The given record
        must already be in the input db.  Typically the user runs the FindUser
        operation prior to Delete to locate an existing record to delete.

        In addition, delete the user from all groups of which the user is a
        member.  If the deleted user is the only leader of a one more groups,
        output a warning indicating that those groups have become leaderless.
    *);
  end DeleteUser;

  object LeaderlessGroupsWarning is
    components: Name*;
    description: (*
        LeaderlessGroupsWarning is an secondary output of the Change and
        DeleteUser operations, indicating the names of zero or more groups that
        have become leaderless as the result of a user having been deleted.
    *);
  end LeaderlessGroupsWarning;

  object GroupDB is
    components: GroupRecord*;
    description: (*
        UserDB is the repository of user group information.
    *);
  end GroupDB;

  object GroupRecord is
    components: Name and Leaders and Members;
    description: (*
        A GroupRecord is the information stored about a user group.  The Name
        component is a unique group name of any length.  Leaders is a list of
        zero or more users designated as group leader.  Members is the list of
        group members, including the leaders.  Both lists consist of user id's.
        Normally a group is required to have at least one leader.  The only
        case that a group becomes leaderless is when its leader is deleted as a
        registered user.
    *);
  end GroupRecord;

  object Leaders is Id*;
  object Members is Id*;

  operation AddGroup is
    inputs: GroupDB, UserDB, GroupRecord;
    outputs: GroupDB;
    description: (*
        Add the given GroupRecord to the given GroupDB.  The name of the given
        group must not be the same as a group already in the GroupDB.  All
        group members must be registered users.  The leader(s) of the group
        must be members of it.
    *);
  end AddGroup;

  operation FindGroup is
    inputs: GroupDB, Name;
    outputs: GroupRecord;
    description: (*
        Find a group by unique name.
    *);
  end FindGroup;

  operation ChangeGroup is
    inputs: GroupDB, UserDB, old_gr:GroupRecord, new_gr:GroupRecord;
    outputs: GroupDB;
    description: (*
        Change the given old GroupRecord to the given new record.  The old and
        new records must not be the same.  The old record must already be in
        the input db.  The new record must meet the same conditions as for the
        input to the AddGroup operation.  Typically the user runs the FindGroup
        operation prior to Change to locate an existing record to be changed.
    *);
  end ChangeGroup;

  operation DeleteGroup is
    inputs: GroupDB, GroupRecord;
    outputs: GroupDB;
    description: (*
        Delete the given group record from the given GroupDB.  The given record
        must already be in the input db.  Typically the user runs the FindGroup
        operation prior to Delete to locate an existing record to delete.
    *);
  end DeleteGroup;


  (*
   * RoomDB and global options TBD.
   *)

end Admin;