Log4j 1.3alpha-8

org.apache.log4j.net
Class SMTPAppender

java.lang.Object
  |
  +--org.apache.log4j.spi.ComponentBase
        |
        +--org.apache.log4j.AppenderSkeleton
              |
              +--org.apache.log4j.net.SMTPAppender
All Implemented Interfaces:
Appender, Component, OptionHandler

public class SMTPAppender
extends AppenderSkeleton

Send an e-mail when a specific logging event occurs, typically on errors or fatal errors.

The number of logging events delivered in this e-mail depend on the value of BufferSize option. The SMTPAppender keeps only the last BufferSize logging events in its cyclic buffer. This keeps memory requirements at a reasonable level while still delivering useful application context.

There are three ways in which the trigger is fired, resulting in an email containing the buffered events:

* DEFAULT BEHAVIOR: relies on an internal TriggeringEventEvaluator class that triggers the sending of an email when an event with a severity of ERROR or greater is received.

* Set the 'evaluatorClass' param to the fully qualified class name of a class you have written that implements the TriggeringEventEvaluator interface.

* Set the 'expression' param to a valid (infix) expression supported by ExpressionRule and ExpressionRule's supported operators and operands. As events are received, events are evaluated against the expression rule. An event that causes the rule to evaluate to true triggers the email send. If both evaluatorClass and expression params are set, the evaluatorClass is used. See org.apache.log4j.rule.ExpressionRule for a more information.

Since:
1.0
Author:
Ceki Gülcü

Field Summary
protected  CyclicBuffer cb
           
protected  TriggeringEventEvaluator evaluator
           
protected  Message msg
           
 
Fields inherited from class org.apache.log4j.AppenderSkeleton
active, closed, errorHandler, headFilter, layout, name, tailFilter, threshold
 
Fields inherited from class org.apache.log4j.spi.ComponentBase
repository
 
Constructor Summary
SMTPAppender()
          The default constructor will instantiate the appender with a TriggeringEventEvaluator that will trigger on events with level ERROR or higher.
SMTPAppender(TriggeringEventEvaluator evaluator)
          Use evaluator passed as parameter as the TriggeringEventEvaluator for this SMTPAppender.
 
Method Summary
 void activateOptions()
          Activate the specified options, such as the smtp host, the recipient, from, etc.
 void append(LoggingEvent event)
          Perform SMTPAppender specific appending actions, mainly adding the event to a cyclic buffer and checking if the event triggers an e-mail to be sent.
protected  boolean checkEntryConditions()
          This method determines if there is a sense in attempting to append.
 void close()
          Release any resources allocated within the appender such as file handles, network connections, etc.
 int getBufferSize()
          Returns value of the BufferSize option.
 String getCharset()
          Returns the charset for messages.
 String getEvaluatorClass()
          Returns value of the EvaluatorClass option.
 String getFrom()
          Returns value of the From option.
 boolean getLocationInfo()
          Returns value of the LocationInfo option.
 String getSMTPHost()
          Returns value of the SMTPHost option.
 String getSubject()
          Returns value of the Subject option.
 String getTo()
          Returns value of the To option.
 boolean requiresLayout()
          The SMTPAppender requires a layout.
protected  void sendBuffer(LoggingEvent triggeringEvent)
          Send the contents of the cyclic buffer as an e-mail message.
 void setBufferSize(int bufferSize)
          The BufferSize option takes a positive integer representing the maximum number of logging events to collect in a cyclic buffer.
 void setCharset(String charset)
          Set charset for messages: ensure the charset you are using is available on your platform.
 void setEvaluator(TriggeringEventEvaluator evaluator)
          Set TriggeringEventEvaluator for this instance of SMTPAppender.
 void setEvaluatorClass(String value)
          Deprecated. replaced by setEvaluator(org.apache.log4j.spi.TriggeringEventEvaluator).
 void setFrom(String from)
          The From option takes a string value which should be a e-mail address of the sender.
 void setLocationInfo(boolean locationInfo)
          The LocationInfo option takes a boolean value.
 void setSMTPHost(String smtpHost)
          The SMTPHost option takes a string value which should be a the host name of the SMTP server that will send the e-mail message.
 void setSubject(String subject)
          The Subject option takes a string value which will be the subject of the e-mail message.
 void setTo(String to)
          The To option takes a string value which should be a comma separated list of e-mail address of the recipients.
 
Methods inherited from class org.apache.log4j.AppenderSkeleton
addFilter, clearFilters, doAppend, finalize, getErrorHandler, getFilter, getFirstFilter, getLayout, getName, getThreshold, isActive, isAsSevereAsThreshold, isAsSevereAsThreshold, isClosed, setErrorHandler, setLayout, setName, setThreshold
 
Methods inherited from class org.apache.log4j.spi.ComponentBase
getLogger, getLoggerRepository, getNonFloodingLogger, resetErrorCount, setLoggerRepository
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.apache.log4j.spi.Component
setLoggerRepository
 

Field Detail

cb

protected CyclicBuffer cb

msg

protected Message msg

evaluator

protected TriggeringEventEvaluator evaluator
Constructor Detail

SMTPAppender

public SMTPAppender()
The default constructor will instantiate the appender with a TriggeringEventEvaluator that will trigger on events with level ERROR or higher.

SMTPAppender

public SMTPAppender(TriggeringEventEvaluator evaluator)
Use evaluator passed as parameter as the TriggeringEventEvaluator for this SMTPAppender.
Method Detail

activateOptions

public void activateOptions()
Activate the specified options, such as the smtp host, the recipient, from, etc.
Overrides:
activateOptions in class AppenderSkeleton

append

public void append(LoggingEvent event)
Perform SMTPAppender specific appending actions, mainly adding the event to a cyclic buffer and checking if the event triggers an e-mail to be sent.
Overrides:
append in class AppenderSkeleton

checkEntryConditions

protected boolean checkEntryConditions()
This method determines if there is a sense in attempting to append.

It checks whether there is a set output target and also if there is a set layout. If these checks fail, then the boolean value false is returned.


close

public void close()
Description copied from interface: Appender
Release any resources allocated within the appender such as file handles, network connections, etc.

It is a programming error to append to a closed appender.


getTo

public String getTo()
Returns value of the To option.

requiresLayout

public boolean requiresLayout()
The SMTPAppender requires a layout.

sendBuffer

protected void sendBuffer(LoggingEvent triggeringEvent)
Send the contents of the cyclic buffer as an e-mail message.

getEvaluatorClass

public String getEvaluatorClass()
Returns value of the EvaluatorClass option.

getFrom

public String getFrom()
Returns value of the From option.

getSubject

public String getSubject()
Returns value of the Subject option.

setFrom

public void setFrom(String from)
The From option takes a string value which should be a e-mail address of the sender.

setSubject

public void setSubject(String subject)
The Subject option takes a string value which will be the subject of the e-mail message. This value can be string literal or a conversion pattern in the same format as expected by PatternLayout.

The conversion pattern is applied on the triggering event to dynamically compute the subject of the outging email message. For example, setting the Subject option to "%properties{host} - %m" will set the subject of outgoing message to the "host" property of the triggering event followed by the message of the triggering event.


setBufferSize

public void setBufferSize(int bufferSize)
The BufferSize option takes a positive integer representing the maximum number of logging events to collect in a cyclic buffer. When the BufferSize is reached, oldest events are deleted as new events are added to the buffer. By default the size of the cyclic buffer is 512 events.

setSMTPHost

public void setSMTPHost(String smtpHost)
The SMTPHost option takes a string value which should be a the host name of the SMTP server that will send the e-mail message.

getSMTPHost

public String getSMTPHost()
Returns value of the SMTPHost option.

setTo

public void setTo(String to)
The To option takes a string value which should be a comma separated list of e-mail address of the recipients.

getBufferSize

public int getBufferSize()
Returns value of the BufferSize option.

setEvaluatorClass

public void setEvaluatorClass(String value)
Deprecated. replaced by setEvaluator(org.apache.log4j.spi.TriggeringEventEvaluator).

The EvaluatorClass option takes a string value representing the name of the class implementing the TriggeringEventEvaluator interface. A corresponding object will be instantiated and assigned as the triggering event evaluator for the SMTPAppender.

setEvaluator

public void setEvaluator(TriggeringEventEvaluator evaluator)
Set TriggeringEventEvaluator for this instance of SMTPAppender.

setLocationInfo

public void setLocationInfo(boolean locationInfo)
The LocationInfo option takes a boolean value. By default, it is set to false which means there will be no effort to extract the location information related to the event. As a result, the layout that formats the events as they are sent out in an e-mail is likely to place the wrong location information (if present in the format).

Location information extraction is comparatively very slow and should be avoided unless performance is not a concern.


getLocationInfo

public boolean getLocationInfo()
Returns value of the LocationInfo option.

setCharset

public void setCharset(String charset)
Set charset for messages: ensure the charset you are using is available on your platform.

getCharset

public String getCharset()
Returns the charset for messages. The default is "ISO-8859-1." This method should not return null.

Log4j 1.3alpha-8

Copyright © 2000-2006 Apache Software Foundation.
Licensed under the Apache License, Version 2.0.