/**
   * Add the event to the end of queue.
   *
   * @param event The event to add to the queue.
   * @exception FrameworkException Thrown on errors.
   */
  public void add(Event event) throws FrameworkException {
    Debug.log(Debug.MSG_STATUS, "QUEUE OPERATION: Adding event to database queue ...");

    Connection dbConn = null;

    PreparedStatement ps = null;

    long startTime = -1;

    if (Debug.isLevelEnabled(Debug.BENCHMARK)) startTime = System.currentTimeMillis();

    try {
      event.id = PersistentSequence.getNextSequenceValue(SEQUENCE_NAME);

      dbConn = DBConnectionPool.getInstance().acquireConnection();

      event.arrivalTime = new java.sql.Timestamp(System.currentTimeMillis());

      if (Debug.isLevelEnabled(Debug.DB_DATA))
        Debug.log(Debug.DB_DATA, "\n" + LINE + "\nExecuting SQL:\n" + INSERT_EVENT_SQL);

      if (Debug.isLevelEnabled(Debug.DB_DATA))
        Debug.log(Debug.DB_DATA, "Event being inserted into database:\n" + event.describe());

      if (Debug.isLevelEnabled(Debug.MSG_DATA))
        Debug.log(Debug.MSG_DATA, "Event contents:\n" + event.message);

      ps = dbConn.prepareStatement(INSERT_EVENT_SQL);

      ps.setString(1, event.channelName);
      ps.setInt(2, event.id);

      DBLOBUtils.setCLOB(ps, 3, event.message);

      ps.setTimestamp(4, event.arrivalTime);

      int numRows = ps.executeUpdate();

      if (numRows != 1) {
        String errMsg =
            "Execution of SQL statement ["
                + INSERT_EVENT_SQL
                + "] affected ["
                + numRows
                + "] rows.";

        Debug.error(errMsg);

        throw new FrameworkException(errMsg);
      }

      DBConnectionPool.getInstance().commit(dbConn);

      if (Debug.isLevelEnabled(Debug.DB_DATA))
        Debug.log(Debug.DB_DATA, "Successfully committed SQL operation.\n" + LINE);

      // NOTE: We don't add the item just inserted into the database into the in-memory
      // queue, as we want it loaded by the separate dequeueing thread.
    } catch (SQLException sqle) {
      throw new DatabaseException(
          "ERROR: Could not execute SQL statement:\n" + DBInterface.getSQLErrorMessage(sqle));
    } catch (Exception e) {
      throw new DatabaseException("ERROR: Could not execute SQL statement:\n" + e.toString());
    } finally {
      releaseDatabaseResources(dbConn, ps);

      if (Debug.isLevelEnabled(Debug.BENCHMARK) && (startTime > 0)) {
        long stopTime = System.currentTimeMillis();

        Debug.log(
            Debug.BENCHMARK,
            "ELAPSED TIME ["
                + (stopTime - startTime)
                + "] msec:  "
                + "SQL: Time to insert event into PersistentEvent database table.");
      }
    }
  }
  /**
   * Load any available events from the database up to the configured maximum.
   *
   * @param criteria An event containing the event-selection criteria.
   * @return The next available event on the queue.
   * @exception FrameworkException Thrown on errors.
   */
  private void loadFromDatabase(Event criteria) throws FrameworkException {
    Debug.log(Debug.MSG_STATUS, "QUEUE OPERATION: Loading events from database into queue ...");

    if (!StringUtils.hasValue(criteria.channelName)) {
      throw new FrameworkException(
          "ERROR: Event channel name is a required queue search criteria.");
    }

    Connection dbConn = null;

    PreparedStatement ps = null;

    long startTime = -1;

    if (Debug.isLevelEnabled(Debug.BENCHMARK)) startTime = System.currentTimeMillis();

    try {
      dbConn = DBConnectionPool.getInstance().acquireConnection();

      if (Debug.isLevelEnabled(Debug.DB_DATA))
        Debug.log(Debug.DB_DATA, "\n" + LINE + "\nExecuting SQL:\n" + QUERY_EVENT_SQL);

      if (Debug.isLevelEnabled(Debug.DB_DATA))
        Debug.log(
            Debug.DB_DATA, "Criteria used in query against database:\n" + criteria.describe());

      ps = dbConn.prepareStatement(QUERY_EVENT_SQL);

      ps.setString(1, criteria.channelName);

      ResultSet rs = ps.executeQuery();

      for (int counter = 0; (counter < maxDatabaseEventLoadSize) && rs.next(); counter++) {
        Event event = new Event();

        event.channelName = rs.getString(CHANNEL_NAME_COL);
        event.id = rs.getInt(ID_COL);

        event.message = DBLOBUtils.getCLOB(rs, MESSAGE_COL);

        if (Debug.isLevelEnabled(Debug.MSG_LIFECYCLE))
          Debug.log(Debug.MSG_LIFECYCLE, "Event contents:\n" + event.message);

        event.arrivalTime = rs.getTimestamp(ARRIVAL_TIME_COL);
        event.errorStatus = rs.getString(ERROR_STATUS_COL);
        event.errorCount = rs.getInt(ERROR_COUNT_COL);
        event.lastErrorMessage = rs.getString(LAST_ERROR_MESSAGE_COL);
        event.lastErrorTime = rs.getTimestamp(LAST_ERROR_TIME_COL);

        // Add item to in-memory buffer.
        if (Debug.isLevelEnabled(Debug.MSG_STATUS))
          Debug.log(
              Debug.MSG_STATUS,
              "Adding event [" + event.describe() + "] to in-memory queue buffer.");

        queue.add(event);

        if (Debug.isLevelEnabled(Debug.MSG_STATUS))
          Debug.log(Debug.MSG_STATUS, "In-memory queue buffer size [" + queue.size() + "].");
      }

      if (Debug.isLevelEnabled(Debug.DB_DATA)) Debug.log(Debug.DB_DATA, "\n" + LINE);
    } catch (SQLException sqle) {
      throw new DatabaseException(
          "ERROR: Could not execute SQL statement:\n" + DBInterface.getSQLErrorMessage(sqle));
    } catch (Exception e) {
      throw new DatabaseException("ERROR: Could not execute SQL statement:\n" + e.toString());
    } finally {
      releaseDatabaseResources(dbConn, ps);

      if (Debug.isLevelEnabled(Debug.BENCHMARK) && (startTime > 0)) {
        long stopTime = System.currentTimeMillis();

        Debug.log(
            Debug.BENCHMARK,
            "ELAPSED TIME ["
                + (stopTime - startTime)
                + "] msec:  "
                + "SQL: Time to load event(s) from PersistentEvent database table.");
      }
    }
  }