arlut.csd.ganymede.server

Class DBLog

java.lang.Object

arlut.csd.ganymede.server.DBLog

public final 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 to keep the logfile orderly.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DBLog.MailMode Enum used to specify whether the logging system should calculate additional addresses to send an event to.

Field Summary

Fields

Modifier and Type	Field and Description
private boolean	closed This variable tracks whether the log file has been closed, or whether it is open for append.
(package private) static boolean	debug
private GanymedeSession	gSession GanymedeSession reference to allow the log code to do searching of the database, etc.
private DBLogController	logController The log controller responsible for logging events to disk or to a database.
private DBLogController	mailController The log controller responsible for logging 'mailout' events to disk or to a database.
private Qsmtp	mailer Our mail relay.
private java.util.HashMap<java.lang.String,java.util.HashMap<java.lang.String,MailOut>>	objectOuts This instance variable is used to track all mail messages that we accumulate during the course of logging events for a transaction between startTransactionLog() and endTransactionLog(), by mapping objevent tags to HashMaps which in turn map email addresses to the MailOut objects that we are accumulating.
private java.util.Map<java.lang.String,objectEventType>	objEventCodes We keep a table of the system event codes to speed the logging process.
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.
private java.lang.String	signature The signature to be appended to any outgoing mail
private java.util.Map<java.lang.String,systemEventType>	sysEventCodes We keep a table of the system event codes to speed the logging process.
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.
private java.lang.String	transactionComment This instance variable is used to track the comment for a transaction log across a sequence of startTransactionLog(), streamLogEvent(), and endTransactionLog() calls.
private systemEventType	transactionControl This instance variable is used to track the transaction logging instruction in the Ganymede server's System Event DBStore, so that we don't have to keep looking it up during transaction processing.
private java.lang.String	transactionID This instance variable is used to track the transaction identifier across a sequence of startTransactionLog(), streamLogEvent(), and endTransactionLog() calls.
private java.util.HashMap<java.lang.String,MailOut>	transactionMailOuts This instance variable is used to track all mail messages that we accumulate during the course of logging events for a transaction between startTransactionLog() and endTransactionLog(), by mapping email address to MailOut objects, which hold the mail that we are composing for users who need to know about a full transaction's worth of email.
private java.util.Date	transactionTimeStamp This instance variable is used to track the timestamp for a transaction log across a sequence of startTransactionLog(), streamLogEvent(), and endTransactionLog() calls.
(package private) static TranslationService	ts TranslationService object for handling string localization in the Ganymede server.

Constructor Summary

Constructors

Constructor and Description
DBLog(DBLogController logController, DBLogController mailController, GanymedeSession gSession, boolean suppressEmail) Constructor for a Ganymede log object.

Method Summary

Methods

Modifier and Type	Method and Description
private java.util.List<java.lang.String>	appendMailOut(DBLogEvent event, java.util.HashMap<java.lang.String,MailOut> map, DBSession session, 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.List<java.lang.String>	appendObjectMail(DBLogEvent event, java.util.HashMap<java.lang.String,java.util.HashMap<java.lang.String,MailOut>> objectOuts, java.lang.String transdescrip, DBSession transSession) This creates and records a MailOut object for custom Object Event notifications if necessary for the DBLogEvent passed.
private void	calculateMailTargets(DBLogEvent event, DBSession session, systemEventType eventType, DBLog.MailMode mode) 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.Set<java.lang.String>	calculateOwnerAddresses(java.util.List<Invid> objects, DBLog.MailMode mode) This method takes a List of Invid's representing objects touched during a transaction, and returns a Set of email addresses that should be notified of operations affecting the objects in the <objects> list.
static java.util.Set<java.lang.String>	calculateOwnerAddresses(java.util.List<Invid> objects, DBLog.MailMode mode, DBSession session) This method takes a List of Invid's representing objects touched during a transaction, and returns a Set of email addresses that should be notified of operations affecting the objects in the <objects> list.
static java.util.Set<java.lang.String>	calculateOwnerAddresses(java.util.List<Invid> objects, DBSession session) This method takes a List of Invid's representing objects touched during a transaction, and returns a Set of email addresses that should be notified of operations affecting the objects in the <objects> list.
static java.util.Set<java.lang.String>	cleanupAddresses(java.util.Set<java.lang.String> addresses) Takes a Set of email addresses and returns a Set of the same addresses after cleaning.
void	cleanupTransaction() Emergency cleanup function called by DBEditSet.commit_logTransaction(java.util.Set) in the event of a problem during logging.
(package private) void	close() This method closes out the log file.
private static java.lang.String	describeLargeTransaction(MailOut mailOut, DBEditSet transaction) describeLargeTransaction provides a subject line with the types and count of objects created, modified, or deleted by transaction, but without the names of the objects that describeSmallTransaction provides.
private static java.lang.String	describeSmallTransaction(MailOut mailOut, DBEditSet transaction) describeSmallTransaction provides a subject line with the types and names of the objects created, modified, or deleted by transaction.
private static java.lang.String	describeTransaction(MailOut mailOut, DBEditSet transaction) Synthesize a descriptive subject for transaction summary email.
void	endTransactionLog(java.util.List<Invid> invids, java.lang.String adminName, Invid admin, DBEditSet transaction) This method should only be called after a startTransactionLog() call and any corresponding endTransactionLog() calls, made by DBEditSet.commit_logTransaction(java.util.Set).
private void	loadSignature() This method gets the signature file loaded.
void	logSystemEvent(DBLogEvent event) This method is used to log an event such as server shutdown/restart, user log-in, persona change, etc.
void	mailNotify(java.lang.String title, java.lang.String description, DBLogEvent event, DBLog.MailMode mode, 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(Invid invid, java.util.Date sinceTime, java.util.Date beforeTime, boolean keyOnAdmin, boolean fullTransactions, boolean getLoginEvents) This method is used to scan the log for log events that match invid and that have occurred since sinceTime.
void	sendMail(java.util.List<java.lang.String> recipients, java.lang.String title, java.lang.String description) This method sends out a generic mail message that will not be logged.
void	sendMail(java.util.List<java.lang.String> recipients, java.lang.String title, java.lang.String description, DBLog.MailMode mode, java.util.List<Invid> 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.lang.String returnAddrDesc, java.util.HashMap<java.lang.String,java.util.HashMap<java.lang.String,MailOut>> objectOuts, java.util.Date currentTime, DBEditSet transaction) Send out type-specific email notifications to email addresses that have signed up for per-object-type mail notifications.
private java.util.List<java.lang.String>	sendSysEventMail(DBLogEvent event, java.lang.String transdescrip) This sends out system ("global") event mail to the appropriate users, based on the system event record's flags.
void	startTransactionLog(java.util.List<Invid> invids, java.lang.String adminName, Invid admin, java.lang.String comment, DBEditSet transaction) This method is used to start logging events for a transaction.
void	streamEvent(DBLogEvent event, DBEditSet transaction) This method should only be called after a startTransactionLog() call and before the corresponding endTransactionLog() call, made by DBEditSet.commit_logTransaction(java.util.Set).
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

ts

static final TranslationService ts

TranslationService object for handling string localization in the Ganymede server.

logController

private DBLogController logController

The log controller responsible for logging events to disk or to a database.

mailController

private DBLogController mailController

The log controller responsible for logging 'mailout' events to disk or to a database.

signature

private java.lang.String signature

The signature to be appended to any outgoing mail

closed

private 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

private java.util.Map<java.lang.String,systemEventType> 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

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.

objEventCodes

private java.util.Map<java.lang.String,objectEventType> 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

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.

mailer

private Qsmtp mailer

Our mail relay.

gSession

private GanymedeSession gSession

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

transactionID

private java.lang.String transactionID

This instance variable is used to track the transaction identifier across a sequence of startTransactionLog(), streamLogEvent(), and endTransactionLog() calls.

transactionTimeStamp

private java.util.Date transactionTimeStamp

This instance variable is used to track the timestamp for a transaction log across a sequence of startTransactionLog(), streamLogEvent(), and endTransactionLog() calls.

transactionComment

private java.lang.String transactionComment

This instance variable is used to track the comment for a transaction log across a sequence of startTransactionLog(), streamLogEvent(), and endTransactionLog() calls.

transactionMailOuts

private java.util.HashMap<java.lang.String,MailOut> transactionMailOuts

This instance variable is used to track all mail messages that we accumulate during the course of logging events for a transaction between startTransactionLog() and endTransactionLog(), by mapping email address to MailOut objects, which hold the mail that we are composing for users who need to know about a full transaction's worth of email.

objectOuts

private java.util.HashMap<java.lang.String,java.util.HashMap<java.lang.String,MailOut>> objectOuts

This instance variable is used to track all mail messages that we accumulate during the course of logging events for a transaction between startTransactionLog() and endTransactionLog(), by mapping objevent tags to HashMaps which in turn map email addresses to the MailOut objects that we are accumulating.

Note that this only works because we serialize log commit.

transactionControl

private systemEventType transactionControl

This instance variable is used to track the transaction logging instruction in the Ganymede server's System Event DBStore, so that we don't have to keep looking it up during transaction processing.

Constructor Detail

DBLog

public DBLog(DBLogController logController,
     DBLogController mailController,
     GanymedeSession gSession,
     boolean suppressEmail)
      throws java.io.IOException

Constructor for a Ganymede log object.

Parameters:

logController -

mailController -

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

suppressEmail - A boolean that indicates whether we should switch off the sending of emails

Throws:

java.io.IOException

Method Detail

close

void close()
     throws java.io.IOException

This method closes out the log file.

Throws:

java.io.IOException

sendMail

public void sendMail(java.util.List<java.lang.String> recipients,
            java.lang.String title,
            java.lang.String description)

This method sends out a generic mail message that will not be logged.

Parameters:

recipients - a List of email addresses to send this message to. Should never be null or empty.

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

description - The message itself

sendMail

public void sendMail(java.util.List<java.lang.String> recipients,
            java.lang.String title,
            java.lang.String description,
            DBLog.MailMode mode,
            java.util.List<Invid> invids)

This method sends out a generic mail message that will not be logged. According to the mode enum value, mail may be sent to email addresses associated with the objects in the invids List, in addition to the recipients list.

Parameters:

recipients - a List 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 mode parameter.

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

description - The message itself

mode - Enum value controlling whether and how to send email to parties connected to the objects referenced by the contents of invids.

invids - A List of Invids to consult for possible mail targeting

mailNotify

public void mailNotify(java.lang.String title,
              java.lang.String description,
              DBLogEvent event,
              DBLog.MailMode mode,
              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 mode so specifies.

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

Parameters:

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

description - The message itself

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

mode - Enum value controlling whether and how to send email to parties connected to the objects referenced by this transaction.

session - The DBSession used to reference this transaction.

logSystemEvent

public void logSystemEvent(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.

startTransactionLog

public void startTransactionLog(java.util.List<Invid> invids,
                       java.lang.String adminName,
                       Invid admin,
                       java.lang.String comment,
                       DBEditSet transaction)

This method is used to start logging events for a transaction. It is called from DBEditSet.commit_logTransaction(java.util.Set), which is responsible for sequencing this call with calls to streamLogEvent() and endTransactionLog().

DBEditSet.commit_logTransaction() is responsible for synchronizing on Ganymede.log, and thereby excluding all other synchronized log calls from being initiated during a transaction's commit.

Parameters:

invids - a List of Invid objects modified by this transaction

adminName - Human readable string identifying the admin responsible for this transaction

admin - Invid representing the user or admin responsible for this transaction

comment - If not null, a comment to attach to logging and email generated in response to this transaction.

transaction - The DBEditSet representing the transaction to be logged

streamEvent

public void streamEvent(DBLogEvent event,
               DBEditSet transaction)

This method should only be called after a startTransactionLog() call and before the corresponding endTransactionLog() call, made by DBEditSet.commit_logTransaction(java.util.Set).

DBEditSet.commit_logTransaction() is responsible for synchronizing on Ganymede.log, and thereby excluding all other synchronized log calls from being initiated during a transaction's commit.

endTransactionLog

public void endTransactionLog(java.util.List<Invid> invids,
                     java.lang.String adminName,
                     Invid admin,
                     DBEditSet transaction)

This method should only be called after a startTransactionLog() call and any corresponding endTransactionLog() calls, made by DBEditSet.commit_logTransaction(java.util.Set).

DBEditSet.commit_logTransaction() is responsible for synchronizing on Ganymede.log, and thereby excluding all other synchronized log calls from being initiated during a transaction's commit, when calling this function

Parameters:

invids - a List of Invid objects modified by this transaction

adminName - Human readable string identifying the admin responsible for this transaction

admin - Invid representing the user or admin responsible for this transaction

transaction - The DBEditSet representing the transaction to be logged

cleanupTransaction

public void cleanupTransaction()

Emergency cleanup function called by DBEditSet.commit_logTransaction(java.util.Set) in the event of a problem during logging.

retrieveHistory

public java.lang.StringBuffer retrieveHistory(Invid invid,
                                     java.util.Date sinceTime,
                                     java.util.Date beforeTime,
                                     boolean keyOnAdmin,
                                     boolean fullTransactions,
                                     boolean getLoginEvents)

This method is used to scan the log 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.

beforeTime - if not null, retrieveHistory() will only return events occurring on or before 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.

getLoginEvents - if true, this method will return only login and logout events. if false, this method will return no login and logout events.

Returns:

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

sendSysEventMail

private java.util.List<java.lang.String> sendSysEventMail(DBLogEvent event,
                                                java.lang.String transdescrip)

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

Returns:

List of email addresses this event was sent to for system event notification. All email addresses in this List will have been normalized with the contents of the ganymede.defaultdomain property, if set.

appendObjectMail

private java.util.List<java.lang.String> appendObjectMail(DBLogEvent event,
                                                java.util.HashMap<java.lang.String,java.util.HashMap<java.lang.String,MailOut>> objectOuts,
                                                java.lang.String transdescrip,
                                                DBSession transSession)

This creates and records a MailOut object for custom Object Event notifications if necessary for the DBLogEvent passed. The MailOut object created, if any, will cause mail to be sent to any email addresses signed up for Object Event notification in the Ganymede database.

Returns:

List of email addresses this event will be sent to for object event notification.

sendObjectMail

private void sendObjectMail(java.lang.String returnAddr,
                  java.lang.String adminName,
                  java.lang.String returnAddrDesc,
                  java.util.HashMap<java.lang.String,java.util.HashMap<java.lang.String,MailOut>> objectOuts,
                  java.util.Date currentTime,
                  DBEditSet transaction)

Send out type-specific email notifications to email addresses that have signed up for per-object-type mail notifications.

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(DBLogEvent event,
                        DBSession session,
                        systemEventType eventType,
                        DBLog.MailMode mode)

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.List<java.lang.String> appendMailOut(DBLogEvent event,
                                             java.util.HashMap<java.lang.String,MailOut> map,
                                             DBSession session,
                                             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:

List 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.

Throws:

java.io.IOException

calculateOwnerAddresses

public java.util.Set<java.lang.String> calculateOwnerAddresses(java.util.List<Invid> objects,
                                                      DBLog.MailMode mode)

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

calculateOwnerAddresses

public static java.util.Set<java.lang.String> calculateOwnerAddresses(java.util.List<Invid> objects,
                                                      DBSession session)

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

calculateOwnerAddresses

public static java.util.Set<java.lang.String> calculateOwnerAddresses(java.util.List<Invid> objects,
                                                      DBLog.MailMode mode,
                                                      DBSession session)

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

cleanupAddresses

public static java.util.Set<java.lang.String> cleanupAddresses(java.util.Set<java.lang.String> addresses)

Takes a Set of email addresses and returns a Set of the same addresses after cleaning.

Cleaning consists of making sure that any naked email addresses (i.e., without an @ sign or hostname) have the Ganymede server's default domain, if any, appended. This may reduce the number of addresses in the resulting Set if the parameter Set had both naked and default domain variants of the same address.

To set the default domain for a Ganymede server, set the 'ganymede.defaultdomain' property in the server's ganymede.properties file.

describeTransaction

private static java.lang.String describeTransaction(MailOut mailOut,
                                   DBEditSet transaction)

Synthesize a descriptive subject for transaction summary email.

describeSmallTransaction

private static java.lang.String describeSmallTransaction(MailOut mailOut,
                                        DBEditSet transaction)

describeSmallTransaction provides a subject line with the types and names of the objects created, modified, or deleted by transaction.

describeSmallTransaction should be used instead of describeLargeTransaction if the number of events in a transaction is small enough that a more complete summary can reasonably be included in the generated email subject.

describeLargeTransaction

private static java.lang.String describeLargeTransaction(MailOut mailOut,
                                        DBEditSet transaction)

describeLargeTransaction provides a subject line with the types and count of objects created, modified, or deleted by transaction, but without the names of the objects that describeSmallTransaction provides.