Class ECDB

java.lang.Object
org.bzdev.ecdb.ECDB
All Implemented Interfaces:
AutoCloseable

public class ECDB extends Object implements AutoCloseable
Event-Calendar Database Session.

The ECDB class provides an API for initializing and manipulating a relational database representing an event calendar. In addition to methods that select, insert, update, or delete table entries, ECDB can generate RFC 5545 calendar appointments and send them via email.

Calendar appointments include the starting date, starting time, ending date, and ending time for an event, whether there is some activity before an event and when that starts, and two optional alarms, with the times set on a per-user basis. The class will also send messages with or without calendar appointments to users to either an email address or to the user's MMS service. Each calendar appointment is tagged with fields that allow a previously sent calendar appointment to be updated. Please see the ECDB description for a more detailed overview of this class.

  • Constructor Details

    • ECDB

      public ECDB() throws IOException, org.bzdev.ecdb.ECDBException
      Constructor.
      Throws:
      IOException
      org.bzdev.ecdb.ECDBException
    • ECDB

      public ECDB(File file) throws IOException, org.bzdev.ecdb.ECDBException
      Constructor given a configuration file.
      Parameters:
      file - the configuration file
      Throws:
      IOException - if an IO error occured
      org.bzdev.ecdb.ECDBException - for an ECDB-specific error
    • ECDB

      public ECDB(Properties properties) throws IOException, org.bzdev.ecdb.ECDBException
      Constructor given configuration properties.
      Parameters:
      properties - the properties
      Throws:
      IOException - if an IO error occured
      org.bzdev.ecdb.ECDBException - for an ECDB-specific error
  • Method Details

    • getCellEmailAddrTimeout

      public long getCellEmailAddrTimeout()
      Get the timeout for email addresses assocated with a cell phone number.
      Returns:
      the timeout in units of days
    • getConnection

      public Connection getConnection() throws SQLException
      Get a database connection.
      Returns:
      a connection
      Throws:
      SQLException - if an SQL error occurred
    • isClosed

      public boolean isClosed()
      Determine if this session has been closed.
      Returns:
      true if the session has been closed; false otherwise
    • close

      public void close() throws SQLException
      Close this ECDB session.
      Specified by:
      close in interface AutoCloseable
      Throws:
      SQLException - if an SQL error occurred
    • getFullEmailAddress

      public String getFullEmailAddress(Connection conn, int userID, boolean useEmail) throws SQLException
      Get the full email address for a user. A full email address consists of the user's name followed by an email address delimited by '<' and '>'.
      Parameters:
      conn - the database connection
      userID - the recipient's user ID
      useEmail - true if the recipient's email address will be used; false if the MMS email address for the recipient's cell phone is used.
      Returns:
      the full email address
      Throws:
      SQLException - if an SQL error occurred
    • createDB

      public void createDB() throws IOException, SQLException
      Create a database. This method uses information in the configuration file to create a database's tables and, when possible, the database itself.
      Throws:
      IOException - if an IO error occurred
      SQLException - if an SQL error occurred
    • allowRoles

      public void allowRoles() throws IOException, SQLException
      Configure a database to allow roles specified in the configuration file.
      Throws:
      IOException - if an IO error occurred
      SQLException - if an SQL error occurred
    • createTables

      public void createTables() throws IOException, SQLException
      Create a database's ECDB tables.
      Throws:
      IOException - if an IO error occurred
      SQLException - if an SQL error occurred
    • addCarrier

      public void addCarrier(Connection conn, String carrier) throws SQLException
      Add a cellphone carrier.
      Parameters:
      conn - the database connection
      carrier - the carrier's name
      Throws:
      SQLException - if an SQL error occurred
    • addCarrier

      public void addCarrier(Connection conn, String[] carriers) throws SQLException
      Add cellphone carriers.
      Parameters:
      conn - the database connection
      carriers - an array containing the carrier's name
      Throws:
      SQLException - if an SQL error occurred
    • deleteCarrier

      public void deleteCarrier(Connection conn, int carrierID) throws SQLException
      Delete a carrier by ID.
      Parameters:
      conn - the database connection
      carrierID - the carrier's ID
      Throws:
      SQLException - if an SQL error occurred
    • deleteCarrier

      public void deleteCarrier(Connection conn, String carrier) throws SQLException
      Delete a carrier by name.
      Parameters:
      conn - the database connection
      carrier - the carrier's name
      Throws:
      SQLException - if an SQL error occurred
    • deleteCarrier

      public void deleteCarrier(Connection conn, String[] carriers) throws SQLException
      Delete carriers by name.
      Parameters:
      conn - the database connection
      carriers - an array containing the names of the carriers to delete
      Throws:
      SQLException - if an SQL error occurred
    • deleteCarrier

      public void deleteCarrier(Connection conn, int[] carrierIDs) throws SQLException
      Delete carriers by ID.
      Parameters:
      conn - the database connection
      carrierIDs - an array containing the IDs of the carriers to delete
      Throws:
      SQLException - if an SQL error occurred
    • listCarrierLabeledIDs

      public ECDB.CarrierLabeledID[] listCarrierLabeledIDs(Connection conn) throws SQLException
      List all carriers by name and ID.
      Parameters:
      conn - the database connection
      Returns:
      an array, each element of which specifies a carrier ID and the corresponding name
      Throws:
      SQLException - if an SQL error occurred
    • listCarriers

      public Vector<Vector<Object>> listCarriers(Connection conn, String[] patterns, boolean full) throws SQLException
      List carriers given name-matching patterns. The vector returned represents a table.
      Parameters:
      conn - the database connection
      patterns - the search patterns
      full - true if if the table rows contains a carrier ID followed by a ECDB.CarrierLabeledID; false if the table contains only a carrier ID in each row
      Returns:
      a table.
      Throws:
      SQLException - if an SQL error occurred
    • listCarriers

      public Vector<Vector<Object>> listCarriers(Connection conn, int[] ids, boolean full) throws SQLException
      List carriers given their IDs. The vector returned represents a table, each row ofwhich contains a carrier ID followed optionally by a string. Each carrier ID is an integer and each carrier name is a string.
      Parameters:
      conn - the database connection
      ids - an array of carrier IDs.
      full - true if if the table rows contains a carrier ID followed by the carrier name; false if the table contains only a carrier ID in each row
      Returns:
      a table.
      Throws:
      SQLException - if an SQL error occurred
    • setCarrier

      public void setCarrier(Connection conn, int carrierID, String carrierName) throws IllegalArgumentException, SQLException
      Set the name of a carrier.
      Parameters:
      conn - the database connection
      carrierID - a carrierID
      carrierName - the new carrier name
      Throws:
      IllegalArgumentException - if an argument is not allowed
      SQLException - if an SQL error occurred
    • setCarrier

      public void setCarrier(Connection conn, int carrierID, String carrierName, boolean commit) throws IllegalArgumentException, SQLException
      Set the name of a carrier, with control over database commits.
      Parameters:
      conn - the database connection
      carrierID - a carrierID
      carrierName - the new carrier name
      commit - true if the new changes should be committed; false otherwise
      Throws:
      IllegalArgumentException
      SQLException
    • getCarrierDomain

      public String getCarrierDomain(Connection conn, String countryPrefix, int carrierID) throws SQLException
      List a carrier map. The return value represents a table, each row of which contains a country prefix, a carrierID or a carrier labeled-ID, and an email domain of a gateway to the MMS service.
      Parameters:
      conn - the database connection
      countryPrefix - the country prefix or code
      carrierID - the carrier ID
      Returns:
      the email domain used for MMS messages sent via email; null if there is none
      Throws:
      SQLException - if an SQL error occurred
    • setCarrierMapping

      public void setCarrierMapping(Connection conn, String countryPrefix, int carrierID, String domain) throws SQLException, IllegalArgumentException
      Set the carrier mapping.
      Parameters:
      conn - the database connection
      countryPrefix - the country prefix or code
      carrierID - the carrier ID
      domain - the domain name for the email gateway used to forward an email to a carrier's MMS service
      Throws:
      IllegalArgumentException - if an argument is not allowed
      SQLException - if an SQL error occurred
    • setCarrierMapping

      public void setCarrierMapping(Connection conn, String countryPrefix, int carrierID, String domain, boolean commit) throws SQLException, IllegalArgumentException
      Set the carrier mapping.
      Parameters:
      conn - the database connection
      countryPrefix - the country prefix or code
      carrierID - the carrier ID
      domain - the domain name for the email gateway used to forward an email to a carrier's MMS service
      commit - true if the new changes should be committed; false otherwise
      Throws:
      IllegalArgumentException - if an argument is not allowed
      SQLException - if an SQL error occurred
    • addUserInfo

      public void addUserInfo(Connection conn, String firstName, String lastName, boolean lastNameFirst, String title, String emailAddr, String countryPrefix, String cellNumber, int carrierID) throws SQLException
      Add a new user.
      Parameters:
      conn - the database connection
      firstName - the user's first name
      lastName - the user's last name
      title - the user's title; null if there is none
      lastNameFirst - true if the first name follows the last name when printed; false if the last name follows the first name
      emailAddr - the user's email address
      countryPrefix - the user's country prefix (1 for the U.S.)
      cellNumber - the user's cell phone number
      carrierID - the ID for the user's cell phone carrier
      Throws:
      SQLException - if an SQL error occurred
    • addUserInfo

      public void addUserInfo(Connection conn, String firstName, String lastName, boolean lastNameFirst, String title, String emailAddr, String countryPrefix, String cellNumber, int carrierID, boolean commit) throws SQLException
      Add a new user, indicating if the new table entry should be committed.
      Parameters:
      conn - the database connection
      firstName - the user's first name
      lastName - the user's last name
      title - the user's title; null if there is none
      lastNameFirst - true if the first name follows the last name when printed; false if the last name follows the first name
      emailAddr - the user's email address
      countryPrefix - the user's country prefix (1 for the U.S.)
      cellNumber - the user's cell phone number
      carrierID - the ID for the user's cell phone carrier
      commit - true if the new changes should be committed; false otherwise
      Throws:
      SQLException - if an SQL error occurred
    • deleteUserInfo

      public void deleteUserInfo(Connection conn, int userID) throws SQLException
      Delete user data.
      Parameters:
      conn - the database connection
      userID - the user ID
      Throws:
      SQLException - if an SQL error occurred
    • deleteUserInfo

      public void deleteUserInfo(Connection conn, String pattern) throws SQLException
      Delete user data. Each deletion must be confirmed.
      Parameters:
      conn - the database connection
      pattern - a pattern used to find users to delete
      Throws:
      SQLException - if an SQL error occurred
    • deleteUserInfo

      public void deleteUserInfo(Connection conn, String pattern, boolean force) throws SQLException
      Delete user data optionally asking for confirmation.
      Parameters:
      conn - the database connection
      pattern - a pattern used to find users to delete
      force - true if all matching users should be deleted; false if each deletion must be confirmed
      Throws:
      SQLException - if an SQL error occurred
    • deleteUserInfo

      public void deleteUserInfo(Connection conn, int[] userIDs) throws SQLException
      Delete user data based on user IDs.
      Parameters:
      conn - the database connection
      userIDs - the user IDs for the users that are to be deleted
      Throws:
      SQLException - if an SQL error occurred
    • getUserLabeledID

      public ECDB.UserLabeledID getUserLabeledID(Connection conn, int userID) throws IllegalArgumentException, SQLException
      Get a user labeled ID for a specified user
      Parameters:
      conn - the database connection
      userID - the user ID
      Throws:
      IllegalArgumentException - if an argument is not allowed
      SQLException - if an SQL error occurred
    • listUserLabeledIDs

      public ECDB.UserLabeledID[] listUserLabeledIDs(Connection conn, String pattern) throws SQLException
      list the user labeled IDs for a specified pattern
      Parameters:
      conn - the database connection
      pattern - the pattern
      Throws:
      SQLException - if an SQL error occurred
    • listUserInfo

      public Vector<Vector<Object>> listUserInfo(Connection conn, String pattern, boolean full) throws SQLException
      List users matching a pattern. A full row lists the user ID, first name, last name, last-name first flag, title, email address, country prefix, cell-phone number, carrier, and status.
      Parameters:
      conn - the database connection
      pattern - the pattern
      full - true if a row contains all of the the publicly accessible columns; false if a rows contains only a user ID
      Throws:
      SQLException - if an SQL error occurred
    • listUserInfo

      public Vector<Vector<Object>> listUserInfo(Connection conn, String[] patterns, boolean full) throws SQLException
      List users matching a pattern. A full row lists the user ID, first name, last name, last-name first flag, title, email address, country prefix, cell-phone number, carrier, and status.
      Parameters:
      conn - the database connection
      patterns - the patterns
      full - true if a row contains all of the the publicly accessible columns; false if a rows contains only a user ID
      Throws:
      SQLException
    • getUserKeyMap

      public TemplateProcessor.KeyMap getUserKeyMap(Connection conn, int userID) throws IllegalArgumentException, SQLException
      Get a user's keymap. Keymaps are used by template processors. the keymap's keys are firstName, lastName, noFirstName, lastName, noLastName, lastNameFirst, firstNameLast, title, and noTitle
      Parameters:
      conn - the database connection
      userID - the user's user id
      Returns:
      the user's key map
      Throws:
      IllegalArgumentException - if an argument is not allowed
      SQLException - if an SQL error occurred
      See Also:
    • listUserInfo

      public Vector<Vector<Object>> listUserInfo(Connection conn, int[] ids, boolean full) throws SQLException
      List users matching a list of user Ids. A full row lists the user ID, first name, last name, last-name first flag, title, email address, country prefix, cell-phone number, carrier, and status.
      Parameters:
      conn - the database connection
      ids - the user IDs
      full - true if a row contains all of the the publicly accessible columns; false if a rows contains only a user ID
      Throws:
      SQLException - if an SQL error occurred
    • getUserCellphoneEmail

      public String getUserCellphoneEmail(Connection conn, int userID, boolean full) throws IllegalArgumentException, SQLException
      Get the email address for a user's MMS gateway.
      Parameters:
      conn - the database connection
      userID - the userID
      full - true if the email address includes the user's name with the email address in angle brackets false if the email address alone is returned
      Returns:
      the email address
      Throws:
      IllegalArgumentException - if an argument is not allowed
      SQLException - if an SQL error occurred
    • setUserInfo

      public void setUserInfo(Connection conn, int userID, String firstName, String lastName, Boolean lastNameFirst, String title, String emailAddr, String countryPrefix, String cellNumber, int carrierID, String status) throws SQLException
      Set the table entry for a user.
      Parameters:
      conn - the database connection
      userID - the userID
      firstName - the user's first name; null if ignored
      lastName - the user's last name; null if ignored
      lastNameFirst - true if the user's last name is followed by the user's first name; false if the user's first name is followed by theuser's last name; null if ignored
      title - the user's title; null if ignored
      emailAddr - the user's email address; null if ignored
      countryPrefix - the country prefix for the user's cell-phone number; null if ignored
      cellNumber - the user's cell-phone number; null if ignored
      carrierID - the carrierID for the user's cell-phone carrier; -1 if ignored
      status - the user's status - ACTIVE, NOTACTIVE, CANCELLED; null if ignored
      Throws:
      SQLException - if an SQL error occurred
    • setUserInfo

      public void setUserInfo(Connection conn, int userID, String firstName, String lastName, Boolean lastNameFirst, String title, String emailAddr, String countryPrefix, String cellNumber, int carrierID, String status, boolean commit) throws SQLException
      Set the table entry for a user, indicating if the table change should be committed.
      Parameters:
      conn - the database connection
      userID - the userID
      firstName - the user's first name; null if ignored
      lastName - the user's last name; null if ignored
      lastNameFirst - true if the user's last name is followed by the user's first name; false if the user's first name is followed by theuser's last name; null if ignored
      title - the user's title; null if ignored
      emailAddr - the user's email address; null if ignored
      countryPrefix - the country prefix for the user's cell-phone number; null if ignored
      cellNumber - the user's cell-phone number; null if ignored
      carrierID - the carrierID for the user's cell-phone carrier; -1 if ignored
      status - the user's status - ACTIVE, NOTACTIVE, CANCELLED; null if ignored
      commit - true if the new changes should be committed; false otherwise
      Throws:
      SQLException - if an SQL error occurred
    • addOwner

      public void addOwner(Connection conn, String label, String summary, String idomain) throws SQLException
      Add a new owner to the owner table.
      Parameters:
      conn - the database connection
      label - a short string naming the owner
      summary - a description of the owner
      idomain - the internet domain name associated with the owner
      Throws:
      SQLException - if an SQL error occurred
    • addOwner

      public void addOwner(Connection conn, String label, String summary, String idomain, boolean commit) throws SQLException
      Add a new owner to the owner table, indicating if database changes should be committed.
      Parameters:
      conn - the database connection
      label - a short string naming the owner
      summary - a description of the owner
      idomain - the internet domain name associated with the owner
      commit - true if the new changes should be committed; false otherwise
      Throws:
      SQLException
    • deleteOwner

      public void deleteOwner(Connection conn, int ownerID) throws SQLException
      Delete an entry from the owner table.
      Parameters:
      conn - the database connection
      ownerID - the owner ID for the entry
      Throws:
      SQLException - if an SQL error occurred
    • deleteOwner

      public void deleteOwner(Connection conn, String pattern) throws SQLException
      Delete an entry from the owner table given a search pattern.
      Parameters:
      conn - the database connection
      pattern - a search pattern for the owner
      Throws:
      SQLException - if an SQL error occurred
    • deleteOwner

      public void deleteOwner(Connection conn, String pattern, boolean force) throws SQLException
      Delete an entry from the owner table given a search pattern, indicating if the deletion is interactive.
      Parameters:
      conn - the database connection
      pattern - a search pattern for the owner
      force - true if all matching users should be deleted; false if each deletion must be confirmed
      Throws:
      SQLException - if an SQL error occurred
    • deleteOwner

      public void deleteOwner(Connection conn, int[] ownerIDs) throws SQLException
      Delete an entry from the owner table a list of owner IDs.
      Parameters:
      conn - the database connection
      ownerIDs - the owner IDs for the entries
      Throws:
      SQLException - if an SQL error occurred
    • listOwnerLabels

      public Object[] listOwnerLabels(Connection conn) throws SQLException
      Throws:
      SQLException
    • listOwnerLabeledIDs

      public ECDB.OwnerLabeledID[] listOwnerLabeledIDs(Connection conn) throws SQLException
      Throws:
      SQLException
    • listOwners

      public Vector<Vector<Object>> listOwners(Connection conn, String[] patterns, boolean full) throws SQLException
      List owners matching a series of patterns When the argument full has the value true, each row contains an owner ID, followed by a label, followed by a summary, followed by an Internet domain name.
      Parameters:
      conn - the database connection
      patterns - a list of patterns
      full - true if a row contains all of the the publicly accessible columns; false if a rows contains only an owner ID
      Throws:
      SQLException - if an SQL error occurred
    • listOwners

      public Vector<Vector<Object>> listOwners(Connection conn, int[] ids, boolean full) throws SQLException
      List owners matching each in series of owner IDs. When the argument full has the value true, each row contains an owner ID, followed by a label, followed by a summary, followed by an Internet domain name.
      Parameters:
      conn - the database connection
      ids - a list of owner IDs
      full - true if a row contains all of the the publicly accessible columns; false if a rows contains only an owner ID
      Throws:
      SQLException - if an SQL error occurred
    • setOwner

      public void setOwner(Connection conn, int ownerID, String label, String summary, String idomain) throws SQLException
      Set fields in the owner table.
      Parameters:
      conn - the database connection
      ownerID - the owner ID for the fields to set
      label - the label; null if ignored
      summary - the summary; null if ignored
      idomain - the internet domain name; null if ignored
      Throws:
      SQLException - if an SQL error occurred
    • setOwner

      public void setOwner(Connection conn, int ownerID, String label, String summary, String idomain, boolean commit) throws SQLException
      Set fields in the owner table, indicating if changes should be committed.
      Parameters:
      conn - the database connection
      ownerID - the owner ID for the fields to set
      label - the label; null if ignored
      summary - the summary; null if ignored
      idomain - the internet domain name; null if ignored
      commit - true if the new changes should be committed; false otherwise
      Throws:
      SQLException - if an SQL error occurred
    • addLocation

      public void addLocation(Connection conn, String label, String location) throws SQLException
      Add an entry to the location table.
      Parameters:
      conn - the database connection
      label - the label
      location - a description of the location
      Throws:
      SQLException - if an SQL error occurred
    • addLocation

      public void addLocation(Connection conn, String label, String location, boolean commit) throws SQLException
      Add an entry to the location table, indicating if the database change should be committed.
      Parameters:
      conn - the database connection
      label - the label
      location - a description of the location
      commit - true if the new changes should be committed; false otherwise
      Throws:
      SQLException - if an SQL error occurred
    • deleteLocation

      public void deleteLocation(Connection conn, int locationID) throws SQLException
      Delete a row from the location table
      Parameters:
      conn - the database connection
      locationID - the location ID
      Throws:
      SQLException - if an SQL error occurred
    • deleteLocation

      public void deleteLocation(Connection conn, String pattern) throws SQLException
      Delete rows from the location table given a pattern.
      Parameters:
      conn - the database connection
      pattern - a search pattern
      Throws:
      SQLException - if an SQL error occurred
    • deleteLocation

      public void deleteLocation(Connection conn, String pattern, boolean force) throws SQLException
      Delete a row from the location table given a pattern and indicating if the deletion is interactive.
      Parameters:
      conn - the database connection
      pattern - a search pattern
      force - true if all entries that match the pattern should be automatically deleted; false if the deletion is interactive
      Throws:
      SQLException - if an SQL error occurred
    • deleteLocation

      public void deleteLocation(Connection conn, int[] locationIDs) throws SQLException
      Delete rows from the location table given a list of location IDs
      Parameters:
      conn - the database connection
      locationIDs - the IDs of the locations to be deleted
      Throws:
      SQLException - if an SQL error occurred
    • listLocationLabels

      public Object[] listLocationLabels(Connection conn) throws SQLException
      List the location labels in the location table This method is intended for building combo boxes and similar GUI components. The initial entry indicates that all locations should be selected.
      Parameters:
      conn - the database connection
      Returns:
      the location labels, prefaced with the "[ All ]"
      Throws:
      SQLException - if an SQL error occurred
    • listLocationLabeledIDs

      public ECDB.LocationLabeledID[] listLocationLabeledIDs(Connection conn) throws SQLException
      List the location labeled IDs for all locations in the location table.
      Parameters:
      conn - the database connection
      Returns:
      the location labeled IDs
      Throws:
      SQLException - if an SQL error occurred
    • listLocationLabeledIDs

      public ECDB.LocationLabeledID[] listLocationLabeledIDs(Connection conn, boolean all) throws SQLException
      List the location labeled IDs for all locations in the location table, specifying whether an 'all' entry should appear first. The 'all' labeled ID is an ID whose label is "[ All ]" and whose location id is -1, which is used as a signal that all IDs are wanted.
      Parameters:
      conn - the database connection
      all - true if an 'all' labeled ID should appear first; false if this ID never appears
      Returns:
      the location labeled IDs
      Throws:
      SQLException
    • listLocations

      public Vector<Vector<Object>> listLocations(Connection conn, String[] patterns, boolean full) throws SQLException
      List rows from the location table matching a pattern. For the full listing, each row contains the location ID, followed by the label, followed by the location.
      Parameters:
      conn - the database connection
      patterns - patterns, one of which should match a labels
      full - true if a row contains all of the the publicly accessible columns; false if a rows contains only a location ID
      Throws:
      SQLException - if an SQL error occurred
    • listLocations

      public Vector<Vector<Object>> listLocations(Connection conn, int[] ids, boolean full) throws SQLException
      List rows from the location table matching specified ids. For the full listing, each row contains the location ID, followed by the label, followed by the location.
      Parameters:
      conn - the database connection
      ids - the location IDs to match
      full - true if a row contains all of the the publicly accessible columns; false if a rows contains only a location ID
      Returns:
      a table whose rows are described above
      Throws:
      SQLException - if an SQL error occurred
    • setLocation

      public void setLocation(Connection conn, int locationID, String label, String location) throws SQLException
      Set fields in the location table.
      Parameters:
      conn - the database connection
      locationID - the location ID of the fields to set
      label - the label; null if this field is not changed
      location - the location description; null if this field is not changed
      Throws:
      SQLException - if an SQL error occurred
    • setLocation

      public void setLocation(Connection conn, int locationID, String label, String location, boolean commit) throws SQLException
      Set fields in the location table, indicating if the database changes should be committed.
      Parameters:
      conn - the database connection
      locationID - the location ID of the fields to set
      label - the label; null if this field is not changed
      location - the location description; null if this field is not changed
      Throws:
      SQLException - if an SQL error occurred
    • addFirstAlarm

      public void addFirstAlarm(Connection conn, int userID, int ownerID, int locationID, Time eventTime, boolean weekday, Time alarmTime, boolean forEmail, boolean forPhone) throws SQLException, IllegalArgumentException
      Add a row to the first-alarm table.
      Parameters:
      conn - the database connection
      userID - the ID of the user to which the new row applies
      ownerID - the ID of the owner to which the new row applies
      locationID - the ID of the location to which the new row applies
      eventTime - a possible time for an event
      weekday - true if eventTime refers to a weekday; false for a weekend
      alarmTime - the corresponding time for an alarm
      forEmail - true if the alarm applies calendar appointments that will be sent to the user's email address; false if no message is to be sent
      forPhone - true if the alarm applies calendar appointments that will be sent to the user's cell phone; false if no message is to be sent
      Throws:
      IllegalArgumentException - if an argument is not allowed
      SQLException - if an SQL error occurred
    • addFirstAlarm

      public void addFirstAlarm(Connection conn, int userID, int ownerID, int locationID, Time eventTime, boolean weekday, Time alarmTime, boolean forEmail, boolean forPhone, boolean commit) throws SQLException, IllegalArgumentException
      Add a row to the first-alarm table, indicating if the database changes should be committed.
      Parameters:
      conn - the database connection
      userID - the ID of the user to which the new row applies
      ownerID - the ID of the owner to which the new row applies
      locationID - the ID of the location to which the new row applies
      eventTime - a possible time for an event
      weekday - true if eventTime refers to a weekday; false for a weekend
      alarmTime - the corresponding time for an alarm
      forEmail - true if the alarm applies calendar appointments that will be sent to the user's email address; false if no message is to be sent
      forPhone - true if the alarm applies calendar appointments that will be sent to the user's cell phone; false if no message is to be sent
      commit - true if the new changes should be committed; false otherwise
      Throws:
      IllegalArgumentException - if an argument is not allowed
      SQLException - if an SQL error occurred
    • deleteFirstAlarm

      public void deleteFirstAlarm(Connection conn, int userID, int ownerID, int locationID, Time eventTime, boolean weekday) throws SQLException, IllegalArgumentException
      Delete a row from the first-alarm table.
      Parameters:
      conn - the database connection
      userID - the ID of the user to which the new row applies
      ownerID - the ID of the owner to which the new row applies
      locationID - the ID of the location to which the new row applies
      eventTime - a possible time for an event
      weekday - true if eventTime refers to a weekday; false for a weekend
      Throws:
      IllegalArgumentException - if an argument is not allowed
      SQLException - if an SQL error occurred
    • deleteFirstAlarms

      public void deleteFirstAlarms(Connection conn, int userID, int ownerID, int locationID, Time eventTime, Boolean weekday, boolean force) throws SQLException, IllegalArgumentException
      Delete rows from the first-alarm table. The rows deleted are those that match the criteria set by the userID, ownerID, locationID, eventTime, and weekday arguments.
      Parameters:
      conn - the database connection
      userID - the ID of the user to which the new row applies; -1 to match all user IDs
      ownerID - the ID of the owner to which the new row applies; -1 to match all owner IDs
      locationID - the ID of the location to which the new row applies; to match all locations
      eventTime - a possible time for an event; null for any time
      weekday - true if eventTime refers to a weekday; false for a weekend; null if not considered; null null for either possibility
      force - true if all entries that match the pattern should be automatically deleted; false if the deletion is interactive
      Throws:
      IllegalArgumentException - if an argument is not allowed
      SQLException - if an SQL error occurred
    • getOwnerLabeledID

      public ECDB.OwnerLabeledID getOwnerLabeledID(Connection conn, int ownerID)
      Get the owner labeled ID for an owner table entry
      Parameters:
      conn - the database connection
      ownerID - the ownerID
      Returns:
      the matching owner labeled ID; null if there is no match
    • getLocationLabeledID

      public ECDB.LocationLabeledID getLocationLabeledID(Connection conn, int locationID)
      Get the location labeled ID for an owner table entry
      Parameters:
      conn - the database connection
      locationID - the location ID
      Returns:
      the matching location labeled ID; null if there is no match
    • listFirstAlarms

      public Vector<Vector<Object>> listFirstAlarms(Connection conn, int userID, int ownerID, int locationID, Time eventTime, Boolean weekday, boolean full) throws SQLException
      List rows from the first alarm table. The full listing for a row includes the userID, followed by the location ID, followed by the event time, followed by the weekday flag, followed by the alarm time, followed by the 'for email' flag, followed by the 'for phone' flag.
      Parameters:
      conn - the database connection
      userID - the userID
      ownerID - the owner ID; -1 for any owner
      locationID - the location ID; -1 for any location
      eventTime - the time of the event; null for any time
      weekday - true if the event occurs on a weekday; false for a weekend; null for either
      full - true if a row contains all of the the publicly accessible columns; false if a rows contains only a location ID
      Throws:
      SQLException - if an SQL error occurred
    • setFirstAlarm

      public void setFirstAlarm(Connection conn, int userID, int ownerID, int locationID, Time eventTime, boolean weekday, Time alarmTime, Boolean forEmail, Boolean forPhone) throws SQLException
      Set fields in a row from the first alarm table. The fields that can be set are the ones for the alarmTime, forEmail, and forPhone arguments.
      Parameters:
      conn - the database connection
      userID - the userID
      ownerID - the owner ID
      locationID - the location ID
      eventTime - the time of the event
      weekday - true if the event occurs on a weekday; false for a weekend
      alarmTime - the alarm time; null to ignore
      forEmail - the 'for email' flag; null to ignore
      forPhone - the 'for phone' flag; null to ignore
      Throws:
      SQLException - if an SQL error occurred
    • setFirstAlarm

      public void setFirstAlarm(Connection conn, int userID, int ownerID, int locationID, Time eventTime, boolean weekday, Time alarmTime, Boolean forEmail, Boolean forPhone, boolean commit) throws SQLException
      Set fields in a row from the first alarm table, indicating if the database changes should be committed. The fields that can be set are the ones for the alarmTime, forEmail, and forPhone arguments.
      Parameters:
      conn - the database connection
      userID - the userID
      ownerID - the owner ID
      locationID - the location ID
      eventTime - the time of the event
      weekday - true if the event occurs on a weekday; false for a weekend
      alarmTime - the alarm time; null to ignore
      forEmail - the 'for email' flag; null to ignore
      forPhone - the 'for phone' flag; null to ignore
      commit - true if the new changes should be committed; false otherwise
      Throws:
      SQLException - if an SQL error occurred
    • addSecondAlarm

      public void addSecondAlarm(Connection conn, int userID, int ownerID, int locationID, int offset, boolean forEmail, boolean forPhone) throws SQLException, IllegalArgumentException
      Add a row to the second-alarm table.
      Parameters:
      conn - the database connection
      userID - the userID
      ownerID - the owner ID
      locationID - the location ID
      offset - the number of minutes before the event for this alarm
      forEmail - the 'for email' flag
      forPhone - the 'for phone' flag
      Throws:
      SQLException - if an SQL error occurred
      IllegalArgumentException - if an argument is not allowed
    • addSecondAlarm

      public void addSecondAlarm(Connection conn, int userID, int ownerID, int locationID, int offset, boolean forEmail, boolean forPhone, boolean commit) throws SQLException, IllegalArgumentException
      Add a row to the second-alarm table, indicating if the database changes should be committed.
      Parameters:
      conn - the database connection
      userID - the userID
      ownerID - the owner ID
      locationID - the location ID
      offset - the number of minutes before the event for this alarm
      forEmail - the 'for email' flag
      forPhone - the 'for phone' flag
      commit - true if the new changes should be committed; false otherwise
      Throws:
      SQLException - if an SQL error occurred
      IllegalArgumentException - if an argument is not allowed
    • deleteSecondAlarm

      public void deleteSecondAlarm(Connection conn, int userID, int ownerID, int locationID) throws SQLException, IllegalArgumentException
      Delete a row from the second alarm table.
      Parameters:
      conn - the database connection
      userID - the userID
      ownerID - the owner ID
      locationID - the location ID
      Throws:
      SQLException - if an SQL error occurred
      IllegalArgumentException - if an argument is not allowed
    • deleteSecondAlarms

      public void deleteSecondAlarms(Connection conn, int userID, int ownerID, int locationID, boolean force) throws SQLException, IllegalArgumentException
      Delete rows from the second alarm table.
      Parameters:
      conn - the database connection
      userID - the userID
      ownerID - the owner ID; -1 for any owner
      locationID - the location ID; -1 for any location
      force - true if all entries that match the pattern should be automatically deleted; false if the deletion is interactive
      Throws:
      SQLException - if an SQL error occurred
      IllegalArgumentException - if an argument is not allowed
    • listSecondAlarms

      public Vector<Vector<Object>> listSecondAlarms(Connection conn, int userID, int ownerID, int locationID, boolean full) throws SQLException
      List matching rows from the second-alarm table. Each row contains the userID, the ownerID, the locationID, the offset, the 'forEmail' flag, and the 'forPhone' flag in that order.
      Parameters:
      conn - the database connection
      userID - the userID
      ownerID - the owner ID; -1 for any owner
      locationID - the location ID; -1 for any location
      full - true if the userID, ownerID, and locationID are represented by labeled IDs; false if they are represented by their integer values
      Throws:
      SQLException - if an SQL error occurred
    • setSecondAlarm

      public void setSecondAlarm(Connection conn, int userID, int ownerID, int locationID, int offset, Boolean forEmail, Boolean forPhone) throws SQLException
      Set fields in the second-alarm table.
      Parameters:
      conn - the database connection
      userID - the userID
      ownerID - the owner ID; -1 for any owner
      locationID - the location ID; -1 for any location
      offset - the difference in minutes between the event and the alarm; -1 for no change
      forEmail - true if this alarm appears in a calendar sent to an email address; false if it does not; null indicates no change
      forPhone - true if this alarm appears in a calendar sent to a cell phone; false if it does not; null indicates no change
      Throws:
      SQLException - if an SQL error occurred
    • setSecondAlarm

      public void setSecondAlarm(Connection conn, int userID, int ownerID, int locationID, int offset, Boolean forEmail, Boolean forPhone, boolean commit) throws SQLException
      Set fields in the second-alarm table, indicating if the changes should be committed to a database.
      Parameters:
      conn - the database connection
      userID - the userID
      ownerID - the owner ID; -1 for any owner
      locationID - the location ID; -1 for any location
      offset - the difference in minutes between the event and the alarm; -1 for no change
      forEmail - true if this alarm appears in a calendar sent to an email address; false if it does not; null indicates no change
      forPhone - true if this alarm appears in a calendar sent to a cell phone; false if it does not; null indicates no change
      commit - true if the new changes should be committed; false otherwise
      Throws:
      SQLException - if an SQL error occurred
    • addPreEventDefault

      public void addPreEventDefault(Connection conn, int userID, int ownerID, boolean peDefault) throws SQLException, IllegalArgumentException
      Add a rew to the pre-event default table.
      Parameters:
      conn - the database connection
      userID - the userID
      ownerID - the owner ID; -1 for any owner
      peDefault - true if the user normally attends pre-events for the owner; false otherwise
      Throws:
      SQLException - if an SQL error occurred
      IllegalArgumentException - if an argument is not allowed
    • addPreEventDefault

      public void addPreEventDefault(Connection conn, int userID, int ownerID, boolean peDefault, boolean commit) throws SQLException, IllegalArgumentException
      Add a rew to the pre-event default table, indicating if database changes should be committed.
      Parameters:
      conn - the database connection
      userID - the userID
      ownerID - the owner ID
      peDefault - true if the user normally attends pre-events for the owner; false otherwise
      commit - true if the new changes should be committed; false otherwise
      Throws:
      SQLException - if an SQL error occurred
      IllegalArgumentException - if an argument is not allowed
    • deletePreEventDefault

      public void deletePreEventDefault(Connection conn, int userID, int ownerID) throws SQLException, IllegalArgumentException
      Delete a row from the pre-event default table.
      Parameters:
      conn - the database connection
      userID - the userID
      ownerID - the owner ID
      Throws:
      SQLException - if an SQL error occurred
      IllegalArgumentException - if an argument is not allowed
    • deletePreEventDefaults

      public void deletePreEventDefaults(Connection conn, int userID, int ownerID, boolean force) throws SQLException, IllegalArgumentException
      Delete rows from the pre-event default table, indicating if the deletions are interactive.
      Parameters:
      conn - the database connection
      userID - the userID
      ownerID - the owner ID; -1 for all owners
      force - true if all entries that match the pattern should be automatically deleted; false if the deletion is interactive
      Throws:
      SQLException - if an SQL error occurred
      IllegalArgumentException - if an argument is not allowed
    • listPreEventDefaults

      public Vector<Vector<Object>> listPreEventDefaults(Connection conn, int userID, int ownerID, boolean full) throws SQLException
      List rows from the pre-event default table. Each row consists of a user ID, followed by an owner ID, followed by a boolean value indicating fi the pre-event default is true or false.
      Parameters:
      conn - the database connection
      userID - the userID
      ownerID - the owner ID; -1 for all owners
      full - true if the userID, ownerID, and locationID are represented by labeled IDs; false if they are represented by their integer values
      Throws:
      SQLException - if an SQL error occurred
    • setPreEventDefault

      public void setPreEventDefault(Connection conn, int userID, int ownerID, boolean peDefault) throws SQLException
      Set the pre-event default field in a row in the pre-event default table. Each row consists of a user ID, followed by an owner ID, followed by a boolean value indicating fi the pre-event default is true or false.
      Parameters:
      conn - the database connection
      userID - the userID
      ownerID - the owner ID;
      peDefault - true if the user normally attends pre-events for the owner; false otherwise
      Throws:
      SQLException - if an SQL error occurred
    • setPreEventDefault

      public void setPreEventDefault(Connection conn, int userID, int ownerID, boolean peDefault, boolean commit) throws SQLException
      Set the pre-event default field in a row in the pre-event default table, indicating if data base changes should be committed. Each row consists of a user ID, followed by an owner ID, followed by a boolean value indicating fi the pre-event default is true or false.
      Parameters:
      conn - the database connection
      userID - the userID
      ownerID - the owner ID;
      peDefault - true if the user normally attends pre-events for the owner; false otherwise
      commit - true if the new changes should be committed; false otherwise
      Throws:
      SQLException - if an SQL error occurred
    • getPreEventDefault

      public boolean getPreEventDefault(Connection conn, int userID, int ownerID) throws SQLException, IllegalArgumentException
      Throws:
      SQLException
      IllegalArgumentException
    • addEvent

      public void addEvent(Connection conn, int ownerID, String label, String description) throws SQLException, IllegalArgumentException
      Add a row to the event table.
      Parameters:
      conn - the database connection
      ownerID - the owner ID
      label - the event's label
      description - the event's description
      Throws:
      SQLException - if an SQL error occurred
      IllegalArgumentException - if an argument is not allowed
    • addEvent

      public void addEvent(Connection conn, int ownerID, String label, String description, boolean commit) throws SQLException, IllegalArgumentException
      Add a row to the event table, indicating if database changes should be committed.
      Parameters:
      conn - the database connection
      ownerID - the owner ID
      label - the event's label
      description - the event's description
      commit - true if the new changes should be committed; false otherwise
      Throws:
      SQLException - if an SQL error occurred
      IllegalArgumentException - if an argument is not allowed
    • deleteEvent

      public void deleteEvent(Connection conn, int eventID) throws SQLException
      Delete a row from the event table.
      Parameters:
      conn - the database connection
      eventID - the event ID for the row
      Throws:
      SQLException - if an SQL error occurred
    • deleteEvent

      public void deleteEvent(Connection conn, String pattern) throws SQLException
      Delete rows whose labels match a patter from the event table.
      Parameters:
      conn - the database connection
      pattern - a pattern for the event's label
      Throws:
      SQLException - if an SQL error occurred
    • deleteEvent

      public void deleteEvent(Connection conn, String pattern, boolean force) throws SQLException
      Delete rows whose labels match a patter from the event table, indicating if the deletion is interactive or if all matching rows are to be deleted.
      Parameters:
      conn - the database connection
      pattern - a pattern for the event's label
      force - true if all entries that match the pattern should be automatically deleted; false if the deletion is interactive
      Throws:
      SQLException - if an SQL error occurred
    • deleteEvent

      public void deleteEvent(Connection conn, int[] eventIDs) throws SQLException
      Delete rows from the event table.
      Parameters:
      conn - the database connection
      eventIDs - the event IDs that the rows will match
      Throws:
      SQLException - if an SQL error occurred
    • listEventLabels

      public Object[] listEventLabels(Connection conn, int ownerID) throws SQLException
      List the labels for rows in the event table with specified owners
      Parameters:
      conn - the database connection
      ownerID - the owner ID; -1 for all owners
      Returns:
      an array whose contents are string containing labels, after an initial element equal to "[ All ]"
      Throws:
      SQLException - if an SQL error occurred
    • listEventLabeledIDs

      public ECDB.EventLabeledID[] listEventLabeledIDs(Connection conn, int ownerID) throws SQLException
      List the event labeled IDs for rows in the event table with specified owners
      Parameters:
      conn - the database connection
      ownerID - the owner ID; -1 for all owners
      Returns:
      an array provides the matching event labeled IDs
      Throws:
      SQLException - if an SQL error occurred
    • listEventsForOwner

      public Vector<Vector<Object>> listEventsForOwner(Connection conn, int ownerID, boolean full) throws SQLException
      List the rows in the event table matching specified owner IDs. Each row's entries are in the following order: the event ID, followed by an owner-labeled ID, followed by a label, followed by a description.
      Parameters:
      conn - the database connection
      ownerID - the owner ID; -1 for all owners
      full - true if full rows are returned; false if each row contains only an event ID
      Returns:
      the table rows matching the specified owners
      Throws:
      SQLException - if an SQL error occurred
    • listEvents

      public Vector<Vector<Object>> listEvents(Connection conn, String[] patterns, boolean full) throws SQLException
      List the rows in the event table matching patterns. Each row's entries are in the following order: the event ID, followed by an owner-labeled ID, followed by a label, followed by a description.
      Parameters:
      conn - the database connection
      patterns - patterns used to match an owner's label
      full - true if full rows are returned; false if each row contains only an event ID
      Returns:
      the table rows matching the specified patterms
      Throws:
      SQLException - if an SQL error occurred
    • listEvents

      public Vector<Vector<Object>> listEvents(Connection conn, int[] ids, boolean full) throws SQLException
      List the rows in the event table matching event IDs. Each row's entries are in the following order: the event ID, followed by an owner-labeled ID, followed by a label, followed by a description.
      Parameters:
      conn - the database connection
      ids - the event IDs to match
      full - true if full rows are returned; false if each row contains only an event ID
      Returns:
      the table rows matching the specified event IDs
      Throws:
      SQLException - if an SQL error occurred
    • setEvent

      public void setEvent(Connection conn, int eventID, int ownerID, String label, String description) throws SQLException
      Set an event table field.
      Parameters:
      conn - the database connection
      eventID - the event ID
      ownerID - the new owner ID; -1 to ignore
      label - the new label; null to ignore
      description - the new description; null to ignore
      Throws:
      SQLException - if an SQL error occurred
    • setEvent

      public void setEvent(Connection conn, int eventID, int ownerID, String label, String description, boolean commit) throws SQLException
      Set an event table field, indicating if database changes should be committed.
      Parameters:
      conn - the database connection
      eventID - the event ID
      ownerID - the new owner ID; -1 to ignore
      label - the new label; null to ignore
      description - the new description; null to ignore
      commit - true if the new changes should be committed; false otherwise
      Throws:
      SQLException - if an SQL error occurred
    • addEventInstance

      public void addEventInstance(Connection conn, int eventID, int locationID, String preEventType, int preEventOffset, Date startDate, Time startTime, Date endDate, Time endTime, String status) throws SQLException, IllegalArgumentException
      Add a row to the event-instance table.
      Parameters:
      conn - the database connection
      eventID - the event ID
      locationID - the location ID
      preEventType - a short description of what a pre-event is; null if there is no pre-event
      preEventOffset - the pre-event's offset in minutes from the event itself; 0 or negative if there is no pre-event
      startDate - the starting date for this event instance
      startTime - the starting time for this event instance
      endDate - the ending data for this event instance
      endTime - the ending time for this event instance
      status - TENTATIVE, CONFIRMED, CANCELLED or null if a status is not explicitly supplied
      Throws:
      IllegalArgumentException - if an argument is not allowed
      SQLException - if an SQL error occurred
    • addEventInstance

      public void addEventInstance(Connection conn, int eventID, int locationID, String preEventType, int preEventOffset, Date startDate, Time startTime, Date endDate, Time endTime, String status, boolean commit) throws SQLException, IllegalArgumentException
      Add a row to the event-instance table, indicating if database changes should be committed.
      Parameters:
      conn - the database connection
      eventID - the event ID
      locationID - the location ID
      preEventType - a short description of what a pre-event is; null if there is no pre-event
      preEventOffset - the pre-event's offset in minutes from the event itself; 0 or negative if there is no pre-event
      startDate - the starting date for this event instance
      startTime - the starting time for this event instance
      endDate - the ending data for this event instance
      endTime - the ending time for this event instance
      status - TENTATIVE, CONFIRMED, CANCELLED or null if a status is not explicitly supplied
      commit - true if the new changes should be committed; false otherwise
      Throws:
      IllegalArgumentException - if an argument is not allowed
      SQLException - if an SQL error occurred
    • deleteEventInstance

      public boolean deleteEventInstance(Connection conn, int instanceID) throws SQLException
      Delete a row from the event-instance table.
      Parameters:
      conn - the database connection
      instanceID - the event-instance ID for the row to delete
      Throws:
      SQLException - if an SQL error occurred
    • deleteCancelledEventInstances

      public void deleteCancelledEventInstances(Connection conn) throws SQLException
      Delete all rows from the event-instance table whose state is "CANCELLED".
      Parameters:
      conn - the database connection
      Throws:
      SQLException - if an SQL error occurred
    • deleteEventInstances

      public int deleteEventInstances(Connection conn, int[] instanceIDs) throws SQLException
      Delete rows from the event-instance table.
      Parameters:
      conn - the database connection
      instanceIDs - the event-instance IDs for the rows to delete
      Throws:
      SQLException - if an SQL error occurred
    • listInstanceLabeledIDs

      public ECDB.InstanceLabeledID[] listInstanceLabeledIDs(Connection conn, int ownerID, int eventID, int locationID) throws SQLException
      List instance labeled IDs for the event-instance table. Normally either the ownerID or the eventID (or both) will be -1: an eventID matches only a single ownerID, so providing both is redundant.
      Parameters:
      conn - the database connection
      ownerID - an owner ID; -1 for any owner
      eventID - an event; -1 for any event
      locationID - an location ID; -1 for any location
      Returns:
      an array of instance labeled IDs
      Throws:
      SQLException - if an SQL error occurred
    • listInstanceLabeledIDs

      public ECDB.InstanceLabeledID[] listInstanceLabeledIDs(Connection conn, int ownerID, int eventID, int locationID, boolean all) throws SQLException
      List instance labeled IDs for the event-instance table, optionally starting with an element matching all event instances. Normally either the ownerID or the eventID (or both) will be -1: an eventID matches only a single ownerID, so providing both is redundant. An instance labeled ID that represents all event instances has an ID equal to -1 and a label with some appropraite text ("[ All Instances ]").
      Parameters:
      conn - the database connection
      ownerID - an owner ID; -1 for any owner
      eventID - an event; -1 for any event
      locationID - an location ID; -1 for any location
      all - true if the first instance indicates all instances; false otherwise
      Returns:
      an array of instance labeled IDs
      Throws:
      SQLException - if an SQL error occurred
    • listEventInstances

      public Vector<Vector<Object>> listEventInstances(Connection conn, int ownerID, int eventID, int locationID, boolean full) throws SQLException
      List rows from the event-instance table. Each row of the table contains the following publiclly readable fields: an instance ID, an event labeled ID, a location labeled ID, a pre-event type, a pre-event offset, a start data, a start time, and end date, and end time, and a status field
      Parameters:
      conn - the database connection
      ownerID - an owner ID; -1 for any owner
      eventID - an event; -1 for any event
      locationID - an location ID; -1 for any location
      full - true if all publicly readable fields are include; false if a row contains only the instance ID field
      Returns:
      a vector of rows
      Throws:
      SQLException - if an SQL error occurred
    • listEventInstances

      public Vector<Vector<Object>> listEventInstances(Connection conn, int ownerID, int locationID, Date startDate, Time startTime, String status, boolean full) throws SQLException
      List rows from the event-instance table matching additional criteria. Each row of the table contains the following publiclly readable fields: an instance ID, an event labeled ID, a location labeled ID, a pre-event type, a pre-event offset, a start data, a start time, and end date, and end time, and a status field
      Parameters:
      conn - the database connection
      ownerID - an owner ID; -1 for any owner
      locationID - an location ID; -1 for any location
      startDate - the start date for an event instance; null for any
      startTime - the start time for an event instance; null for any
      full - true if all publicly readable fields are include; false if a row contains only the instance ID field
      Returns:
      a vector of rows
      Throws:
      SQLException - if an SQL error occurred
    • listEventInstances

      public Vector<Vector<Object>> listEventInstances(Connection conn, int[] ids, boolean full) throws SQLException
      List rows from the event-instance table for a series of instance IDs. Each row of the table contains the following publiclly readable fields: an instance ID, an event labeled ID, a location labeled ID, a pre-event type, a pre-event offset, a start data, a start time, and end date, and end time, and a status field
      Parameters:
      conn - the database connection
      ids - the instance IDs of the rows to include
      full - true if all publicly readable fields are include; false if a row contains only the instance ID field
      Returns:
      a vector of rows
      Throws:
      SQLException - if an SQL error occurred
    • listEventInstance

      public Vector<Vector<Object>> listEventInstance(Connection conn, int instanceID, boolean full) throws SQLException, IllegalArgumentException
      List rows from the event-instance table for a series of instance IDs. Each row of the table contains the following publiclly readable fields: an instance ID, an event labeled ID, a location labeled ID, a pre-event type, a pre-event offset, a start data, a start time, and end date, and end time, and a status field
      Parameters:
      conn - the database connection
      instanceID - the instance ID the row to include.
      full - true if all publicly readable fields are include; false if a row contains only the instance ID field
      Returns:
      a vector of rows
      Throws:
      IllegalArgumentException - if an argument is not allowed
      SQLException - if an SQL error occurred
    • setEventInstance

      public void setEventInstance(Connection conn, int instanceID, int eventID, int locationID, String preEventType, int preEventOffset, Date startDate, Time startTime, Date endDate, Time endTime, String status) throws SQLException, IllegalArgumentException
      Set fields in a row of the event table.
      Parameters:
      conn - the database connection
      instanceID - an instance ID for the row to modified
      eventID - an event; -1 if ignored
      locationID - an location ID; -1 if ignored
      preEventType - a descriptive type for a pre-event; null if ignored
      preEventOffset - the pre-event offset in minutes; -1 if ignored
      startDate - the start date for an event instance; null if ignored
      startTime - the start time for an event instance; null if ignored
      endDate - the end date for an event instance; null if ignored
      endTime - the end time for an event instance; null if ignored
      Throws:
      SQLException - if an SQL error occurred
      IllegalArgumentException - if an argument is not allowed
    • setEventInstance

      public void setEventInstance(Connection conn, int instanceID, int eventID, int locationID, String preEventType, int preEventOffset, Date startDate, Time startTime, Date endDate, Time endTime, String status, boolean commit) throws SQLException, IllegalArgumentException
      Set fields in a row of the event table, indicating if database changes should be committed.
      Parameters:
      conn - the database connection
      instanceID - an instance ID for the row to modified
      eventID - an event; -1 if ignored
      locationID - an location ID; -1 if ignored
      preEventType - a descriptive type for a pre-event; null if ignored
      preEventOffset - the pre-event offset in minutes; -1 if ignored
      startDate - the start date for an event instance; null if ignored
      startTime - the start time for an event instance; null if ignored
      endDate - the end date for an event instance; null if ignored
      endTime - the end time for an event instance; null if ignored
      commit - true if the new changes should be committed; false otherwise
      Throws:
      SQLException - if an SQL error occurred
      IllegalArgumentException - if an argument is not allowed
    • addSeries

      public void addSeries(Connection conn, int ownerID, String label) throws SQLException, IllegalArgumentException
      Add a series to the series table.
      Parameters:
      conn - the database connection
      ownerID - an owner ID; -1 for any owner
      label - a short string naming the series
      Throws:
      SQLException - if an SQL error occurred
      IllegalArgumentException - if an argument is not allowed
    • addSeries

      public void addSeries(Connection conn, int ownerID, String label, boolean commit) throws SQLException, IllegalArgumentException
      Add a series to the series table, indicating if database changes should be committed.
      Parameters:
      conn - the database connection
      ownerID - an owner ID; -1 for any owner
      label - a short string naming the series
      commit - true if the new changes should be committed; false otherwise
      Throws:
      SQLException - if an SQL error occurred
      IllegalArgumentException - if an argument is not allowed
    • deleteSeries

      public void deleteSeries(Connection conn, int seriesID) throws SQLException
      Delete a series from the series table.
      Parameters:
      conn - the database connection
      seriesID - the series ID
      Throws:
      SQLException - if an SQL error occurred
    • deleteSeries

      public void deleteSeries(Connection conn, int ownerID, String pattern) throws SQLException
      Delete a series from the series table. If there are multiple matches, the deletion will be interactive.
      Parameters:
      conn - the database connection
      ownerID - an ownerID used to search for a series
      pattern - a pattern used to match the label for the series
      Throws:
      SQLException - if an SQL error occurred
    • deleteSeries

      public void deleteSeries(Connection conn, int ownerID, String pattern, boolean force) throws SQLException
      Delete a series from the series table, indicating if the deletions are interactive.
      Parameters:
      conn - the database connection
      ownerID - an ownerID used to search for a series; -1 for any
      pattern - a pattern used to match the label for the series; null for any label
      force - true if all entries that match the pattern should be automatically deleted; false if the deletion is interactive
      Throws:
      SQLException - if an SQL error occurred
    • deleteSeries

      public void deleteSeries(Connection conn, int[] ownerIDs) throws SQLException
      Delete a series from the series table.
      Parameters:
      conn - the database connection
      ownerIDs - a list of owner IDs for those series that should be deleted
      Throws:
      SQLException - if an SQL error occurred
    • listSeriesLabels

      public Object[] listSeriesLabels(Connection conn, int ownerID, boolean all) throws SQLException
      List the labels for a series.
      Parameters:
      conn - the database connection
      ownerID - the ownerID for the series that should be listed; -1 for any owner
      all - true if there is an entry for all series matching the specified owner (or all owners); false if there is no entry for all series
      Throws:
      SQLException - if an SQL error occurred
    • listSeriesLabeledIDs

      public ECDB.SeriesLabeledID[] listSeriesLabeledIDs(Connection conn, int ownerID) throws SQLException
      List the series label IDs for a series.
      Parameters:
      conn - the database connection
      ownerID - the ownerID for the series that should be listed; -1 for any owner
      Throws:
      SQLException - if an SQL error occurred
    • listSeries

      public Vector<Vector<Object>> listSeries(Connection conn, int ownerID, String pattern, boolean full) throws SQLException
      List rows from the series table. A row may contain the following fields: a series ID, followed by an owner ID, followed by a label.
      Parameters:
      conn - the database connection
      ownerID - the ownerID for the series that should be listed; -1 for any owner
      pattern - a pattern used to match the label for the series; null for any label
      full - true if all publicly readable fields are include; false if a row contains only the instance ID field
      Returns:
      selected rows from the series table
      Throws:
      SQLException - if an SQL error occurred
    • getSeriesLabeledID

      public ECDB.SeriesLabeledID getSeriesLabeledID(Connection conn, int seriesID, boolean withOwner) throws SQLException
      Get the series labeled ID for an entry in the series table.
      Parameters:
      conn - the database connection
      seriesID - the series ID
      withOwner - true if the owner label should be inlcuded in the labeled ID; false if just the series label should be included
      Returns:
      a series labeled ID for the specified series ID
      Throws:
      SQLException - if an SQL error occurred
    • listSeries

      public Vector<Vector<Object>> listSeries(Connection conn, int[] ids, boolean full) throws SQLException
      List rows in the series table that match specific series IDs.
      Parameters:
      conn - the database connection
      ids - the series IDs for the series to list
      full - true if all publicly readable fields are include; false if a row contains only the instance ID field
      Returns:
      a series labeled ID for the specified series ID
      Throws:
      SQLException - if an SQL error occurred
    • listSeries

      public Vector<Vector<Object>> listSeries(Connection conn, int seriesID, boolean full) throws SQLException
      List rows in the series table that match a specific series ID, or optionally all series IDs.
      Parameters:
      conn - the database connection
      seriesID - the series ID; -1 for all series IDs
      full - true if all publicly readable fields are include; false if a row contains only the instance ID field
      Returns:
      rows that match the specified series IDs
      Throws:
      SQLException - if an SQL error occurred
    • findSeries

      public int findSeries(Connection conn, int ownerID, String pattern) throws SQLException, IllegalArgumentException
      Find a series ID given an owner ID and a pattern used to match labels.
      Parameters:
      conn - the database connection
      ownerID - the ownerID for the series that should be listed; -1 if ignored
      pattern - a pattern used to match labels
      Returns:
      the series ID; -1 if there was not a match
      Throws:
      IllegalArgumentException - if an argument is not allowed
      SQLException - if an SQL error occurred
    • setSeries

      public void setSeries(Connection conn, int seriesID, int ownerID, String label) throws SQLException
      Set fields for a row in the series table.
      Parameters:
      conn - the database connection
      seriesID - the series ID for the row
      ownerID - the new ownerID; -1 if ignored
      label - the new label; null if ignored
      Throws:
      SQLException - if an SQL error occurred
    • setSeries

      public void setSeries(Connection conn, int seriesID, int ownerID, String label, boolean commit) throws SQLException
      Set fields for a row in the series table, optionally committing database changes.
      Parameters:
      conn - the database connection
      seriesID - the series ID for the row
      ownerID - the new ownerID; -1 if ignored
      label - the new label; null if ignored
      commit - true if the new changes should be committed; false otherwise
      Throws:
      SQLException - if an SQL error occurred
    • addSeriesInstance

      public void addSeriesInstance(Connection conn, int seriesID, int instanceID) throws SQLException, IllegalArgumentException
      Add a row to the series-instance table.
      Parameters:
      conn - the database connection
      seriesID - the series ID for the new row
      instanceID - the instanceID for the new row
      Throws:
      IllegalArgumentException - if an argument is not allowed
      SQLException - if an SQL error occurred
    • addSeriesInstance

      public void addSeriesInstance(Connection conn, int seriesID, int instanceID, boolean commit) throws SQLException, IllegalArgumentException
      Add a row to the series-instance table, indicating if database changes should be committed..
      Parameters:
      conn - the database connection
      seriesID - the series ID for the new row
      instanceID - the instanceID for the new row
      commit - true if the new changes should be committed; false otherwise
      Throws:
      IllegalArgumentException - if an argument is not allowed
      SQLException - if an SQL error occurred
    • deleteSeriesInstance

      public void deleteSeriesInstance(Connection conn, int seriesID, int instanceID) throws SQLException
      Delete rows from the series-instance table.
      Parameters:
      conn - the database connection
      seriesID - the series ID for the row; -1 for any
      instanceID - the instanceID for the row; -1 for any
      Throws:
      SQLException - if an SQL error occurred
    • deleteSeriesInstance

      public void deleteSeriesInstance(Connection conn, int seriesID, int instanceID, boolean force) throws SQLException
      Delete rows from the series-instance table, indicating if multiple deletions should be done interactively.
      Parameters:
      conn - the database connection
      seriesID - the series ID for the row; -1 for any
      instanceID - the instanceID for the row; -1 for any
      force - true if all entries that match the pattern should be automatically deleted; false if the deletion is interactive
      Throws:
      SQLException - if an SQL error occurred
    • listSeriesInstance

      public Vector<Vector<Object>> listSeriesInstance(Connection conn, int seriesID, int instanceID, boolean full) throws SQLException
      List rows from the series-instance table. Each row in the table contains a series ID followed by am instance ID.
      Parameters:
      conn - the database connection
      seriesID - the series ID for a row; -1 if ignored
      instanceID - the instanceID for a row; -1 if ignored
      full - true if the IDs are returned as labeled ids; false if returned as integers
      Returns:
      a table of rows
      Throws:
      SQLException - if an SQL error occurred
    • listSeriesInstanceByOwner

      public Vector<Vector<Object>> listSeriesInstanceByOwner(Connection conn, int seriesID, int ownerID, boolean full) throws SQLException
      List rows from the series-instance table by owner. Each row in the table contains a series ID followed by am instance ID.
      Parameters:
      conn - the database connection
      seriesID - the series ID for a row; -1 if ignored
      ownerID - the owner id for a row; -1 if ignored
      full - true if the IDs are returned as labeled ids; false if returned as integers
      Returns:
      a table of rows
      Throws:
      SQLException - if an SQL error occurred
    • addAttendee

      public void addAttendee(Connection conn, int userID, int instanceID, boolean attendingPreEvent, int seriesID) throws SQLException, IllegalArgumentException
      Add a row to the attendee table.
      Parameters:
      conn - the database connection
      userID - the userID for the new row
      instanceID - the instance ID for the new
      attendingPreEvent - true if the user will attend any pre-event for the instance; false otherwise
      seriesID - the ID; -1 if there is none for the new row
      Throws:
      IllegalArgumentException - if an argument is not allowed
      SQLException - if an SQL error occurred
    • addAttendee

      public void addAttendee(Connection conn, int userID, int instanceID, boolean attendingPreEvent, int seriesID, boolean commit) throws SQLException, IllegalArgumentException
      Add a row to the attendee table, indicating if database changes should be commmitted.
      Parameters:
      conn - the database connection
      userID - the userID for the new row
      instanceID - the instance ID for the new
      attendingPreEvent - true if the user will attend any pre-event for the instance; false otherwise
      seriesID - the ID; -1 if there is none for the new row
      commit - true if the new changes should be committed; false otherwise
      Throws:
      IllegalArgumentException - if an argument is not allowed
      SQLException - if an SQL error occurred
    • deleteAttendee

      public void deleteAttendee(Connection conn, int userID, int instanceID, String attendeeState, int seriesID, boolean force) throws SQLException
      Delete one or more rows from the attendee table.
      Parameters:
      conn - the database connection
      userID - the userID for a row; -1 for any
      instanceID - the instance ID for a row; -1 for any
      attendeeState - the state of an attendee (ACTIVE, CANCELLING, or CANCELLED) with null implying CANCELLED.
      seriesID - the ID; -1 for any
      force - true if all entries that match should be automatically deleted; false if the deletion is interactive when more than one rows were selected
      Throws:
      IllegalArgumentException - if an argument is not allowed
      SQLException - if an SQL error occurred
    • listAttendees

      public Vector<Vector<Object>> listAttendees(Connection conn, int userID, int instanceID, int seriesID, String attendeeState, boolean full) throws SQLException
      List attendees The fields listed are in the following order: userID, instanceID, attendeeState, attendingPreEvent, and seriesID
      Parameters:
      conn - the database connection
      userID - the userID for a row; -1 for any
      instanceID - the instance ID for a row; -1 for any
      seriesID - the ID; -1 for any
      attendeeState - the state of an attendee (ACTIVE, CANCELLING, or CANCELLED) with null implying CANCELLED.
      full - true if integer values are represented as labeled ids and the attendeeState as an enum; false if the values are integers and strings .
      Throws:
      SQLException - if an SQL error occurred
    • setAttendee

      public void setAttendee(Connection conn, int userID, int instanceID, String attendeeState, int seriesID) throws SQLException, IllegalArgumentException
      Set fields in a row of the attendee table.
      Parameters:
      conn - the database connection
      userID - the userID for a row
      instanceID - the instance ID for a row
      seriesID - the new series ID; -1 to ignore
      attendeeState - the new state of an attendee (ACTIVE, CANCELLING, or CANCELLED); null to ignore.
      Throws:
      IllegalArgumentException - if an argument is not allowed
      SQLException - if an SQL error occurred
    • setAttendee

      public void setAttendee(Connection conn, int userID, int instanceID, String attendeeState, int seriesID, boolean commit) throws SQLException, IllegalArgumentException
      Set fields in a row of the attendee table. This method can change the attendeeState or the seriesID fields.
      Parameters:
      conn - the database connection
      userID - the userID for a row
      instanceID - the instance ID for a row
      seriesID - the new series ID; -1 to ignore
      attendeeState - the new state of an attendee (ACTIVE, CANCELLING, or CANCELLED); null to ignore.
      commit - true if the new changes should be committed; false otherwise
      Throws:
      IllegalArgumentException - if an argument is not allowed
      SQLException - if an SQL error occurred
    • getInstanceCount

      public int getInstanceCount(Connection conn, int ownerID, int eventID, int locationID, int instanceID) throws SQLException
      Count the number of rows in the attendee with an instance id that matches an event instance with a specified location and event ID, where the corresponding event has a specified owner.
      Parameters:
      conn - the database connection
      ownerID - an owner ID; -1 for any owner
      eventID - an event; -1 for any event
      locationID - an location ID; -1 for any location
      instanceID - an instance ID; -1 for any instance
      Returns:
      the number of rows in the attendee with an instance id that matches and event instance with a specified location ane event ID, where the corresponding event has a specified owner
      Throws:
      SQLException - if an SQL error occurred
    • getNonAttendees

      public Vector<ECDB.UserCalendars> getNonAttendees(Connection conn, int ownerID, int eventID, int locationID, int instanceID, boolean forEmail) throws SQLException
      Get a list of UserCalendar objects, each associated with a distinct user ID for users not attending a specified set of event instances. The userCalendar objects returned do not contain calendars.
      Parameters:
      conn - the database connection
      ownerID - an owner ID; -1 for any owner
      eventID - an event; -1 for any event
      locationID - an location ID; -1 for any location
      instanceID - an instance ID; -1 for any instance
      forEmail - true for calendars associated with email; false for text messages
      Returns:
      the UserCalendar objects
      Throws:
      SQLException - if an SQL error occurred
    • getCalendars

      public Vector<ECDB.UserCalendars> getCalendars(Connection conn, int userID, int ownerID, int eventID, boolean calendarForEmail) throws SQLException
      Get a list of UserCalendar objects, each associated with a distinct user ID for users attending a specified set of event instances. The corresponding calendars are included inthe UserCalendar objects.
      Parameters:
      conn - the database connection
      userID - the userID; -1 for any user
      ownerID - an owner ID; -1 for any owner
      eventID - an event; -1 for any event
      calendarForEmail - true for calendars associated with email; false for text messages
      Returns:
      the UserCalendar objects
      Throws:
      SQLException - if an SQL error occurred
    • applySeries

      public void applySeries(Connection conn, int userID, int seriesID) throws SQLException, IllegalArgumentException
      Apply a series to a user
      Parameters:
      conn - the database connection
      userID - the userID
      seriesID - the series ID
      Throws:
      SQLException - if an SQL error occurred
      IllegalArgumentException - if an argument is not allowed
    • applySeries

      public void applySeries(Connection conn, int userID, int seriesID, boolean commit) throws SQLException, IllegalArgumentException
      Apply a series to a user, indicating if database changes should be committed.
      Parameters:
      conn - the database connection
      userID - the userID
      seriesID - the series ID
      commit - true if the new changes should be committed; false otherwise
      Throws:
      SQLException - if an SQL error occurred
      IllegalArgumentException - if an argument is not allowed
    • getHeadingVector

      public static Vector<String> getHeadingVector(ECDB.Table table, boolean full)
    • getHeading

      public static String[] getHeading(ECDB.Table table, boolean full)
    • copyToClipboard

      public static void copyToClipboard(Vector<byte[]> calendars, boolean headless) throws IOException
      Copy a series of calendars to the window-system's clipboard.
      Parameters:
      calendars - the calendars
      headless - true if ECDB is being run from the command line and will not open any windows, even if a window system is present
      Throws:
      IOException - if an IO error occurred
    • saveToDirectory

      public static void saveToDirectory(File dir, Vector<byte[]> calendars) throws IOException
      Copy a series of calendars to a directory.
      Parameters:
      dir - the directory
      calendars - the calendars
      Throws:
      IOException - if an IO error occurred
    • setSubject

      public void setSubject(String subject)
      Set the subject for a message (email or MMS via a gateway).
      Parameters:
      subject - the subject line
    • getSubject

      public String getSubject()
      Get the current subject line.
      Returns:
      the subject line
    • setMediaType

      public void setMediaType(String mediaType)
      Set the media type for a message (email or MMS via a gateway).
      Parameters:
      mediaType - the media type (e.g., text/html)
    • getMediaType

      public String getMediaType()
      Get the media type for a message.
      Returns:
      the media type (e.g., text/html)
    • setAltMediaType

      public void setAltMediaType(String mediaType)
      Set the alternative media type for a message (email or MMS via a gateway).
      Parameters:
      mediaType - the media type (e.g., text/plain)
    • getAltMediaType

      public String getAltMediaType()
      Get the alternative media type for a message.
      Returns:
      the media type (e.g., text/plain)
    • setTemplateURL

      public void setTemplateURL(URL templateURL)
      Set the URL for the message template.
      Parameters:
      templateURL - the url
    • getTemplateURL

      public URL getTemplateURL()
      Get the URL for the message template.
      Returns:
      the url
    • setAltTemplateURL

      public void setAltTemplateURL(URL templateURL)
      Set the URL for the alternative message template.
      Parameters:
      templateURL - the url
    • getAltTemplateURL

      public URL getAltTemplateURL()
      Get the URL for the alternative message template.
      Returns:
      the url
    • getPreflight

      public boolean getPreflight()
      Get the preflight mode.
      Returns:
      true if the messages should be previewed before being sent; false otherwise
    • setPreflight

      public void setPreflight(boolean value)
      Set the preflight mode.
      Parameters:
      value - true if the messages should be previewed before being sent; false otherwise
    • sendViaEmail

      public static boolean sendViaEmail(ECDB ecdb, Connection conn, Vector<ECDB.UserCalendars> vector, boolean suppressCalendars, JFrame frame, boolean preflight) throws Exception, SQLException
      Send a calendar appointment or message via email, either to an email address. For MMS, the recipient address is that for a gateway.
      Parameters:
      ecdb - the instance of ECDB to use.
      conn - a database connection obtained from ecdb
      vector - a vector of UserCalendar objects, each containing calendars and data needed to identify recipients and format messages
      suppressCalendars - true if calendars should not be attached to a message; false otherwise
      frame - a JFrame on which any dialog boxes should be centered; null if there are none
      preflight - true if the user should be shown a representation of the messages in a web browser (e.g., to verify that the messages are formated or created as desired); false otherwise
      Throws:
      SQLException - if an SQL error occurred
      Exception - an error occurred
    • dryrunForSend

      public static void dryrunForSend(ECDB ecdb, Connection conn, PrintWriter out, Vector<ECDB.UserCalendars> vector, boolean forEmail, boolean suppressCalendars) throws IOException, SQLException
      Send a calendar appointment or message via email, either to an email address. For MMS, the recipient address is that for a gateway.
      Parameters:
      ecdb - the instance of ECDB to use.
      conn - a database connection obtained from ecdb
      out - the print stream on which the message will be displayed
      vector - a vector of UserCalendar objects, each containing calendars and data needed to identify recipients and format messages
      forEmail - true if the message should be formatted as an email messages; false if it should be formatted as an MMS message
      suppressCalendars - true if calendars should not be attached to a message; false otherwise
      Throws:
      SQLException - if an SQL error occurred
      IOException - an IO error occurred
    • main

      public static void main(String[] argv)
      Main program for ECDB when used as an application instead of purely as part of a class library.