Metacat

/**

 *  '$RCSfile$'

 *  Copyright: 2004 Regents of the University of California and the

 *             National Center for Ecological Analysis and Synthesis

 *

 *   '$Author: jones $'

 *     '$Date: 2004-04-06 20:51:21 -0700 (Tue, 06 Apr 2004) $'

 * '$Revision: 2110 $'

 *

 * This program is free software; you can redistribute it and/or modify

 * it under the terms of the GNU General Public License as published by

 * the Free Software Foundation; either version 2 of the License, or

 * (at your option) any later version.

 *

 * This program is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 * GNU General Public License for more details.

 *

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

 */

package edu.ucsb.nceas.metacat;

import java.sql.PreparedStatement;

import java.sql.SQLException;

import java.sql.Timestamp;

import java.util.Date;

/**

 * EventLog is used to intialize and store a log of events that occur in an

 * application. The events are registered with the logger as they occur, but

 * EventLog writes them to permenant storage when it is most convenient or

 * efficient. EventLog is a Singleton as there should always be only one object

 * for these logging events.

 * 

 * TODO: Logging to the database needn't be synchronous with the event.  

 * Instead, a separate thread can be launched that periodically sleeps and only

 * wakes periodically to see if metacat is idle.  The log event can be cached

 * and inserted later when the thread wakes and finds metacat idle.

 * 

 * TODO: Write a function that archives a part of the log table to an 

 * external text file so that the log table doesn't get to big.  This 

 * function should be able to be called manually or on a schedule. 

 * 

 * TODO: Write an access function that returns an XML report for a

 * specific subset of events.  Users should be able to query on

 * principal, docid/rev, date, event, and possibly other fields.

 * 

 * @author jones

 */

public class EventLog

{

    /**

     * The single instance of the event log that is always returned.

     */

    private static EventLog self = null;

    /**

     * A private constructor that initializes the class when getInstance() is

     * called.

     */

    private EventLog()

    {

    }

    /**

     * Return the single instance of the event log after initializing it if it

     * wasn't previously initialized.

     * 

     * @return the single EventLog instance

     */

    public static EventLog getInstance()

    {

        if (self == null) {

            self = new EventLog();

        }

        return self;

    }

    /**

     * Log an event of interest to the application. The information logged can

     * include basic identification information about the principal or computer

     * that initiated the event.

     * 

     * @param ipAddress the internet protocol address for the event

	 * @param principal the principal for the event (a username, etc)

	 * @param docid the identifier of the document to which the event applies

	 * @param event the string code for the event

     */

    public void log(String ipAddress, String principal, String docid,

			String event)

    {

        EventLogData logData = new EventLogData(ipAddress, principal, docid,

                event);

        insertLogEntry(logData);

    }

    /**

     * Insert a single log event record to the database.

     * 

     * @param logData the data to be logged when an event occurs

     */

    private void insertLogEntry(EventLogData logData)

    {

        String insertString = "insert into access_log"

                + "(ip_address, principal, docid, "

                + "event, date_logged) "

                + "values ("

                + "'" + logData.getIpAddress() + "', " 

                + "'" + logData.getPrincipal() + "', "

                + "'" + logData.getDocid() + "', "

                + "'" + logData.getEvent() + "', "

                + " ? " + ")"; 

        DBConnection dbConn = null;

        int serialNumber = -1;

        try {

            // Get a database connection from the pool

            dbConn = DBConnectionPool.getDBConnection("EventLog.writeLog");

            serialNumber = dbConn.getCheckOutSerialNumber();

            // Execute the insert statement

            PreparedStatement stmt = dbConn.prepareStatement(insertString);

            stmt.setTimestamp(1, new Timestamp(new Date().getTime()));

            stmt.executeUpdate();

            stmt.close();

        } catch (SQLException e) {

            MetaCatUtil.debugMessage("Error while logging event to database: " 

                    + e.getMessage(), 5);

        } finally {

            // Return database connection to the pool

            DBConnectionPool.returnDBConnection(dbConn, serialNumber);

        }

    }

    /**

     * Get a report of the log events that match a set of filters.  The

     * filter parameters can be omitted null; log records are subset based on

     * non-null filter parameters.

     * 

     * @param ipAddress the internet protocol address for the event

	 * @param principal the principal for the event (a username, etc)

	 * @param docid the identifier of the document to which the event applies

	 * @param event the string code for the event

	 * @param startDate the date on which the event was logged

	 * @param endDate the 

     */

    public void getReport(String ipAddress, String principal, String docid,

            String event, Timestamp dateLogged)

    {

    }

}