arlut.csd.ganymede
Class DBLog

java.lang.Object
  |
  +--arlut.csd.ganymede.DBLog

public class DBLog

extends java.lang.Object

This class manages recording events in the system log and generating reports from the system log based on specific criteria. The DBLog class is responsible for logging events to an on-disk file, for emailing notification of events to users, admins, and other interested parties, and for scanning through a Ganymede log file for events pertaining to a designated object invid.

Most of the methods in this class must be synchronized, both to keep the logfile itself orderly, and to allow the various log-processing methods in DBLogEvent to re-use the 'multibuffer' StringBuffer.

Field Summary

(package private) boolean	closed This variable tracks whether the log file has been closed, or whether it is open for append.
(package private) java.util.Date	currentTime We use this Date object to track the time of the last log event recorded.
(package private) static boolean	debug
(package private) arlut.csd.ganymede.GanymedeSession	gSession GanymedeSession reference to allow the log code to do searching of the database, etc.
(package private) java.lang.String	logFileName
(package private) java.io.FileOutputStream	logStream
(package private) java.io.PrintWriter	logWriter
(package private) Qsmtp.Qsmtp	mailer Our mail relay.
(package private) java.lang.String	mailFilename
(package private) java.io.FileOutputStream	mailLogStream
(package private) java.io.PrintWriter	mailLogWriter
(package private) arlut.csd.Util.SharedStringBuffer	multibuffer Reusable StringBuffer for transaction processing.
(package private) java.util.Hashtable	objEventCodes We keep a table of the system event codes to speed the logging process.
(package private) java.util.Date	objEventCodesTimeStamp This field keeps track of when we last updated the objEventCodes hash, so that we can check against the timestamp held in the Object Event DBObjectBase to see whether we need to refresh the objEventCodes hash.
(package private) java.lang.String	signature The signature to be appended to any outgoing mail
(package private) java.util.Hashtable	sysEventCodes We keep a table of the system event codes to speed the logging process.
(package private) java.util.Date	sysEventCodesTimeStamp This field keeps track of when we last updated the sysEventCodes hash, so that we can check against the timestamp held in the System Event DBObjectBase to see whether we need to refresh the sysEventCodes hash.

Constructor Summary

DBLog(java.lang.String filename, java.lang.String mailFilename, arlut.csd.ganymede.GanymedeSession gSession)
Constructor for a Ganymede log object.

Method Summary

private java.util.Vector	appendMailOut(arlut.csd.ganymede.DBLogEvent event, java.util.Hashtable map, arlut.csd.ganymede.DBSession session, arlut.csd.ganymede.systemEventType transactionType) This method takes a DBLogEvent object, scans it to determine what mailing lists should be notified of the event in the context of a transaction, and adds a description of the passed in event to each MailOut object held in map.
private java.util.Vector	appendObjectMail(arlut.csd.ganymede.DBLogEvent event, java.util.Hashtable objectOuts, java.lang.String transdescrip, arlut.csd.ganymede.DBSession transSession) This sends out the 'auxiliary' type specific log information mail to designated users, using the object event objects in the Ganymede database.
private void	calculateMailTargets(arlut.csd.ganymede.DBLogEvent event, arlut.csd.ganymede.DBSession session, arlut.csd.ganymede.systemEventType eventType)
private void	calculateMailTargets(arlut.csd.ganymede.DBLogEvent event, arlut.csd.ganymede.DBSession session, arlut.csd.ganymede.systemEventType eventType, boolean mailToObjects, boolean mailToOwners) This method generates a list of additional email addresses that notification for this event should be sent to, based on the event's type and the ownership of objects referenced by this event.
java.util.Vector	calculateOwnerAddresses(java.util.Vector objects, boolean mailToObjects, boolean mailToOwners) This method takes a vector of Invid's representing objects touched during a transaction, and returns a Vector of email addresses that should be notified of operations affecting the objects in the <objects> list.
static java.util.Vector	calculateOwnerAddresses(java.util.Vector objects, boolean mailToObjects, boolean mailToOwners, arlut.csd.ganymede.DBSession session) This method takes a vector of Invid's representing objects touched during a transaction, and returns a Vector of email addresses that should be notified of operations affecting the objects in the <objects> list.
static java.util.Vector	calculateOwnerAddresses(java.util.Vector objects, arlut.csd.ganymede.DBSession session) This method takes a vector of Invid's representing objects touched during a transaction, and returns a Vector of email addresses that should be notified of operations affecting the objects in the <objects> list.
(package private) void	close() This method closes out the log file.
private void	loadSignature() This method gets the signature file loaded.
void	logSystemEvent(arlut.csd.ganymede.DBLogEvent event) This method is used to log an event such as server shutdown/restart, user log-in, persona change, etc.
void	logTransaction(java.util.Vector logEvents, java.lang.String adminName, arlut.csd.ganymede.Invid admin, arlut.csd.ganymede.DBEditSet transaction) This method is used to log all events associated with a transaction.
void	mailNotify(java.lang.String title, java.lang.String description, arlut.csd.ganymede.DBLogEvent event, boolean mailToObjects, boolean mailToOwners, arlut.csd.ganymede.DBSession session) This method is used to handle an email notification event, where the mail title should reflect detailed information about the event, and extra descriptive information is to be sent out.
void	mailNotify(java.lang.String title, java.lang.String description, arlut.csd.ganymede.DBLogEvent event, boolean mailToOwners, arlut.csd.ganymede.DBSession session) This method is used to handle an email notification event, where the mail title should reflect detailed information about the event, and extra descriptive information is to be sent out.
java.lang.StringBuffer	retrieveHistory(arlut.csd.ganymede.Invid invid, java.util.Date sinceTime, boolean keyOnAdmin, boolean fullTransactions) This method is used to scan the log file for log events that match invid and that have occurred since sinceTime.
void	sendMail(java.util.Vector recipients, java.lang.String title, java.lang.String description, boolean mailToObjects, boolean mailToOwners, java.util.Vector invids) This method sends out a generic mail message that will not be logged.
private void	sendObjectMail(java.lang.String returnAddr, java.lang.String adminName, java.util.Hashtable objectOuts)
private java.util.Vector	sendSysEventMail(arlut.csd.ganymede.DBLogEvent event, java.lang.String transdescrip) This sends out system event mail to the appropriate users, based on the system event record's flags.
private void	updateObjEventCodeHash() Private helper method to (re)initialize our local hash of object event codes.
private void	updateSysEventCodeHash() Private helper method to (re)initialize our local hash of system event codes.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

debug

static final boolean debug

See Also:

Constant Field Values

logFileName

java.lang.String logFileName

logStream

java.io.FileOutputStream logStream

logWriter

java.io.PrintWriter logWriter

mailFilename

java.lang.String mailFilename

mailLogStream

java.io.FileOutputStream mailLogStream

mailLogWriter

java.io.PrintWriter mailLogWriter

signature

java.lang.String signature

The signature to be appended to any outgoing mail

currentTime

java.util.Date currentTime

We use this Date object to track the time of the last log event recorded.

closed

boolean closed

This variable tracks whether the log file has been closed, or whether it is open for append. If true, the log file may not be written to.

sysEventCodes

java.util.Hashtable sysEventCodes

We keep a table of the system event codes to speed the logging process. This hash maps system event classTokens to instances of systemEventType.

See Also:

systemEventType

sysEventCodesTimeStamp

java.util.Date sysEventCodesTimeStamp

This field keeps track of when we last updated the sysEventCodes hash, so that we can check against the timestamp held in the System Event DBObjectBase to see whether we need to refresh the sysEventCodes hash.

objEventCodes

java.util.Hashtable objEventCodes

We keep a table of the system event codes to speed the logging process. This hash maps object event classTokens to instances of objectEventType.

See Also:

objectEventType

objEventCodesTimeStamp

java.util.Date objEventCodesTimeStamp

This field keeps track of when we last updated the objEventCodes hash, so that we can check against the timestamp held in the Object Event DBObjectBase to see whether we need to refresh the objEventCodes hash.

mailer

Qsmtp.Qsmtp mailer

Our mail relay.

multibuffer

arlut.csd.Util.SharedStringBuffer multibuffer

Reusable StringBuffer for transaction processing.

gSession

arlut.csd.ganymede.GanymedeSession gSession

GanymedeSession reference to allow the log code to do searching of the database, etc.

Constructor Detail

DBLog

public DBLog(java.lang.String filename,
             java.lang.String mailFilename,
             arlut.csd.ganymede.GanymedeSession gSession)
      throws java.io.IOException

Constructor for a Ganymede log object.

Parameters:

filename - Filename for an on-disk log file. Must point to a valid file

mailFilename - Filename for an optional mail events log file. May be null or empty if no disk-logging of advisory email events is desired.

gSession - GanymedeSession reference used to allow DBLog code to do queries on the Ganymede database

Method Detail

close

void close()
     throws java.io.IOException

This method closes out the log file.

java.io.IOException

sendMail

public void sendMail(java.util.Vector recipients,
                     java.lang.String title,
                     java.lang.String description,
                     boolean mailToObjects,
                     boolean mailToOwners,
                     java.util.Vector invids)

This method sends out a generic mail message that will not be logged. If mailToObjects and/or mailToObjects are true, mail may be sent to email addresses associated with the objects in the invids Vector, in addition to the recipients list.

Parameters:

recipients - a Vector of email addresses to send this message to. May legally be null or empty, in which case mail will be sent to anyone needed according to the mailToObjects and mailToOwners parameters

title - The email subject for this message, will have the Ganymede.subjectPrefixProperty prepended to it.

description - The message itself

mailToObjects - If true, this event's mail will go to any email addresses associated with objects referenced by event.

mailToOwners - If true, this event's mail will go to the owners of any objects referenced by event.

invids - A vector of Invids to consult for possible mail targetting

mailNotify

public void mailNotify(java.lang.String title,
                       java.lang.String description,
                       arlut.csd.ganymede.DBLogEvent event,
                       boolean mailToOwners,
                       arlut.csd.ganymede.DBSession session)

This method is used to handle an email notification event, where the mail title should reflect detailed information about the event, and extra descriptive information is to be sent out.

mailNotify() will send the message to the owners of any objects referenced by event if mailToOwners is true.

description and/or title may be null, in which case the proper strings will be extracted from the event's database record

Parameters:

event - A single event to be logged, with its own timestamp.

mailToOwners - If true, this event's mail will go to the owners of any objects referenced by event.

mailNotify

public void mailNotify(java.lang.String title,
                       java.lang.String description,
                       arlut.csd.ganymede.DBLogEvent event,
                       boolean mailToObjects,
                       boolean mailToOwners,
                       arlut.csd.ganymede.DBSession session)

This method is used to handle an email notification event, where the mail title should reflect detailed information about the event, and extra descriptive information is to be sent out.

mailNotify() will send the message to the owners of any objects referenced by event if mailToOwners is true.

description and/or title may be null, in which case the proper strings will be extracted from the event's database record

Parameters:

event - A single event to be logged, with its own timestamp.

mailToObjects - If true, this event's mail will go to any email addresses associated with objects referenced by event.

mailToOwners - If true, this event's mail will go to the owners of any objects referenced by event.

logSystemEvent

public void logSystemEvent(arlut.csd.ganymede.DBLogEvent event)

This method is used to log an event such as server shutdown/restart, user log-in, persona change, etc. Basically any thing not associated with a transaction.

Parameters:

event - A single event to be logged, with its own timestamp.

logTransaction

public void logTransaction(java.util.Vector logEvents,
                           java.lang.String adminName,
                           arlut.csd.ganymede.Invid admin,
                           arlut.csd.ganymede.DBEditSet transaction)

This method is used to log all events associated with a transaction.

Parameters:

logEvents - a Vector of DBLogEvent objects.

retrieveHistory

public java.lang.StringBuffer retrieveHistory(arlut.csd.ganymede.Invid invid,
                                              java.util.Date sinceTime,
                                              boolean keyOnAdmin,
                                              boolean fullTransactions)

This method is used to scan the log file for log events that match invid and that have occurred since sinceTime.

Parameters:

invid - If not null, retrieveHistory() will only return events involving this object invid.

sinceTime - if not null, retrieveHistory() will only return events occuring on or after the time specified in this Date object.

keyOnAdmin - if true, rather than returning a string containing events that involved <invid>, retrieveHistory() will return a string containing events performed on behalf of the administrator with invid <invid>.

fullTransactions - if true, the buffer returned will include all events in any transactions that involve the given invid. if false, only those events in a transaction directly affecting the given invid will be returned.

Returns:

A human-readable multiline string containing a list of history events

sendSysEventMail

private java.util.Vector sendSysEventMail(arlut.csd.ganymede.DBLogEvent event,
                                          java.lang.String transdescrip)

This sends out system event mail to the appropriate users, based on the system event record's flags.

Returns:

vector of email addresses this event was sent to for system event notification

appendObjectMail

private java.util.Vector appendObjectMail(arlut.csd.ganymede.DBLogEvent event,
                                          java.util.Hashtable objectOuts,
                                          java.lang.String transdescrip,
                                          arlut.csd.ganymede.DBSession transSession)

This sends out the 'auxiliary' type specific log information mail to designated users, using the object event objects in the Ganymede database. This mail is sent for a distinct eventcode/object type pair, outside of the context of a transaction.

Returns:

vector of email addresses this event was sent to for system event notification

sendObjectMail

private void sendObjectMail(java.lang.String returnAddr,
                            java.lang.String adminName,
                            java.util.Hashtable objectOuts)

updateSysEventCodeHash

private void updateSysEventCodeHash()

Private helper method to (re)initialize our local hash of system event codes.

updateObjEventCodeHash

private void updateObjEventCodeHash()

Private helper method to (re)initialize our local hash of object event codes.

calculateMailTargets

private void calculateMailTargets(arlut.csd.ganymede.DBLogEvent event,
                                  arlut.csd.ganymede.DBSession session,
                                  arlut.csd.ganymede.systemEventType eventType)

calculateMailTargets

private void calculateMailTargets(arlut.csd.ganymede.DBLogEvent event,
                                  arlut.csd.ganymede.DBSession session,
                                  arlut.csd.ganymede.systemEventType eventType,
                                  boolean mailToObjects,
                                  boolean mailToOwners)

This method generates a list of additional email addresses that notification for this event should be sent to, based on the event's type and the ownership of objects referenced by this event.

Note that the email addresses added to this event's mail list will be in addition to any that were previously specified by the code that originally generated the log event.

appendMailOut

private java.util.Vector appendMailOut(arlut.csd.ganymede.DBLogEvent event,
                                       java.util.Hashtable map,
                                       arlut.csd.ganymede.DBSession session,
                                       arlut.csd.ganymede.systemEventType transactionType)

This method takes a DBLogEvent object, scans it to determine what mailing lists should be notified of the event in the context of a transaction, and adds a description of the passed in event to each MailOut object held in map.

That is, the map passed in maps each discrete recipient list to a running MailOut object which has the complete text that will be mailed to that recipient when the transaction's records are mailed out.

Returns:

vector of email addresses this event was sent to for system event notification

loadSignature

private void loadSignature()
                    throws java.io.IOException

This method gets the signature file loaded.

java.io.IOException

calculateOwnerAddresses

public java.util.Vector calculateOwnerAddresses(java.util.Vector objects,
                                                boolean mailToObjects,
                                                boolean mailToOwners)

This method takes a vector of Invid's representing objects touched during a transaction, and returns a Vector of email addresses that should be notified of operations affecting the objects in the <objects> list.

calculateOwnerAddresses

public static java.util.Vector calculateOwnerAddresses(java.util.Vector objects,
                                                       arlut.csd.ganymede.DBSession session)

This method takes a vector of Invid's representing objects touched during a transaction, and returns a Vector of email addresses that should be notified of operations affecting the objects in the <objects> list.

calculateOwnerAddresses

public static java.util.Vector calculateOwnerAddresses(java.util.Vector objects,
                                                       boolean mailToObjects,
                                                       boolean mailToOwners,
                                                       arlut.csd.ganymede.DBSession session)

This method takes a vector of Invid's representing objects touched during a transaction, and returns a Vector of email addresses that should be notified of operations affecting the objects in the <objects> list.