Class SMTPAppender
- java.lang.Object
-
- org.apache.log4j.AppenderSkeleton
-
- org.apache.log4j.net.SMTPAppender
-
- All Implemented Interfaces:
Appender
,OptionHandler
,UnrecognizedElementHandler
public class SMTPAppender extends AppenderSkeleton implements UnrecognizedElementHandler
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 lastBufferSize
logging events in its cyclic buffer. This keeps memory requirements at a reasonable level while still delivering useful application context. By default, an email message will be sent when an ERROR or higher severity message is appended. The triggering criteria can be modified by setting the evaluatorClass property with the name of a class implementing TriggeringEventEvaluator, setting the evaluator property with an instance of TriggeringEventEvaluator or nesting a triggeringPolicy element where the specified class implements TriggeringEventEvaluator. This class has implemented UnrecognizedElementHandler since 1.2.15. Since 1.2.16, SMTP over SSL is supported by setting SMTPProtocol to "smpts".- Since:
- 1.0
-
-
Field Summary
Fields Modifier and Type Field Description private java.lang.String
bcc
Comma separated list of bcc recipients.private int
bufferSize
protected CyclicBuffer
cb
private java.lang.String
cc
Comma separated list of cc recipients.protected TriggeringEventEvaluator
evaluator
private java.lang.String
from
private boolean
locationInfo
protected javax.mail.Message
msg
private java.lang.String
replyTo
Comma separated list of replyTo addresses.private boolean
sendOnClose
private boolean
smtpDebug
private java.lang.String
smtpHost
private java.lang.String
smtpPassword
private int
smtpPort
private java.lang.String
smtpProtocol
private java.lang.String
smtpUsername
private java.lang.String
subject
private java.lang.String
to
-
Fields inherited from class org.apache.log4j.AppenderSkeleton
closed, errorHandler, headFilter, layout, name, tailFilter, threshold
-
-
Constructor Summary
Constructors Constructor Description SMTPAppender()
The default constructor will instantiate the appender with aTriggeringEventEvaluator
that will trigger on events with level ERROR or higher.SMTPAppender(TriggeringEventEvaluator evaluator)
Useevaluator
passed as parameter as theTriggeringEventEvaluator
for this SMTPAppender.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
activateOptions()
Activate the specified options, such as the smtp host, the recipient, from, etc.protected void
addressMessage(javax.mail.Message msg)
Address message.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.protected javax.mail.Session
createSession()
Create mail session.protected java.lang.String
formatBody()
Layout body of email message.(package private) javax.mail.internet.InternetAddress
getAddress(java.lang.String addressStr)
java.lang.String
getBcc()
Get the bcc recipient addresses.int
getBufferSize()
Returns value of the BufferSize option.java.lang.String
getCc()
Get the cc recipient addresses.TriggeringEventEvaluator
getEvaluator()
Get triggering evaluator.java.lang.String
getEvaluatorClass()
Returns value of the EvaluatorClass option.java.lang.String
getFrom()
Returns value of the From option.boolean
getLocationInfo()
Returns value of the LocationInfo option.java.lang.String
getReplyTo()
Get the reply addresses.boolean
getSendOnClose()
Get sendOnClose.boolean
getSMTPDebug()
Get SMTP debug.java.lang.String
getSMTPHost()
Returns value of the SMTPHost option.java.lang.String
getSMTPPassword()
Get SMTP password.int
getSMTPPort()
Get port.java.lang.String
getSMTPProtocol()
Get transport protocol.java.lang.String
getSMTPUsername()
Get SMTP user name.java.lang.String
getSubject()
Returns value of the Subject option.java.lang.String
getTo()
Returns value of the To option.(package private) javax.mail.internet.InternetAddress[]
parseAddress(java.lang.String addressStr)
boolean
parseUnrecognizedElement(org.w3c.dom.Element element, java.util.Properties props)
Called to inform a configured object when an unrecognized child element is encountered.boolean
requiresLayout()
TheSMTPAppender
requires alayout
.protected void
sendBuffer()
Send the contents of the cyclic buffer as an e-mail message.void
setBcc(java.lang.String addresses)
Set the bcc recipient addresses.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
setCc(java.lang.String addresses)
Set the cc recipient addresses.void
setEvaluator(TriggeringEventEvaluator trigger)
Sets triggering evaluator.void
setEvaluatorClass(java.lang.String value)
The EvaluatorClass option takes a string value representing the name of the class implementing theTriggeringEventEvaluator
interface.void
setFrom(java.lang.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
setReplyTo(java.lang.String addresses)
Set the e-mail addresses to which replies should be directed.void
setSendOnClose(boolean val)
Set sendOnClose.void
setSMTPDebug(boolean debug)
Setting the SmtpDebug option to true will cause the mail session to log its server interaction to stdout.void
setSMTPHost(java.lang.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
setSMTPPassword(java.lang.String password)
The SmtpPassword option takes a string value which should be the password required to authenticate against the mail server.void
setSMTPPort(int val)
Set port.void
setSMTPProtocol(java.lang.String val)
Set transport protocol.void
setSMTPUsername(java.lang.String username)
The SmtpUsername option takes a string value which should be the username required to authenticate against the mail server.void
setSubject(java.lang.String subject)
The Subject option takes a string value which should be a the subject of the e-mail message.void
setTo(java.lang.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, isAsSevereAsThreshold, setErrorHandler, setLayout, setName, setThreshold
-
-
-
-
Field Detail
-
to
private java.lang.String to
-
cc
private java.lang.String cc
Comma separated list of cc recipients.
-
bcc
private java.lang.String bcc
Comma separated list of bcc recipients.
-
from
private java.lang.String from
-
replyTo
private java.lang.String replyTo
Comma separated list of replyTo addresses.
-
subject
private java.lang.String subject
-
smtpHost
private java.lang.String smtpHost
-
smtpUsername
private java.lang.String smtpUsername
-
smtpPassword
private java.lang.String smtpPassword
-
smtpProtocol
private java.lang.String smtpProtocol
-
smtpPort
private int smtpPort
-
smtpDebug
private boolean smtpDebug
-
bufferSize
private int bufferSize
-
locationInfo
private boolean locationInfo
-
sendOnClose
private boolean sendOnClose
-
cb
protected CyclicBuffer cb
-
msg
protected javax.mail.Message msg
-
evaluator
protected TriggeringEventEvaluator evaluator
-
-
Constructor Detail
-
SMTPAppender
public SMTPAppender()
The default constructor will instantiate the appender with aTriggeringEventEvaluator
that will trigger on events with level ERROR or higher.
-
SMTPAppender
public SMTPAppender(TriggeringEventEvaluator evaluator)
Useevaluator
passed as parameter as theTriggeringEventEvaluator
for this SMTPAppender.
-
-
Method Detail
-
activateOptions
public void activateOptions()
Activate the specified options, such as the smtp host, the recipient, from, etc.- Specified by:
activateOptions
in interfaceOptionHandler
- Overrides:
activateOptions
in classAppenderSkeleton
-
addressMessage
protected void addressMessage(javax.mail.Message msg) throws javax.mail.MessagingException
Address message.- Parameters:
msg
- message, may not be null.- Throws:
javax.mail.MessagingException
- thrown if error addressing message.- Since:
- 1.2.14
-
createSession
protected javax.mail.Session createSession()
Create mail session.- Returns:
- mail session, may not be null.
- Since:
- 1.2.14
-
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.- Specified by:
append
in classAppenderSkeleton
-
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.
-
getAddress
javax.mail.internet.InternetAddress getAddress(java.lang.String addressStr)
-
parseAddress
javax.mail.internet.InternetAddress[] parseAddress(java.lang.String addressStr)
-
getTo
public java.lang.String getTo()
Returns value of the To option.
-
requiresLayout
public boolean requiresLayout()
TheSMTPAppender
requires alayout
.- Specified by:
requiresLayout
in interfaceAppender
-
formatBody
protected java.lang.String formatBody()
Layout body of email message.- Since:
- 1.2.16
-
sendBuffer
protected void sendBuffer()
Send the contents of the cyclic buffer as an e-mail message.
-
getEvaluatorClass
public java.lang.String getEvaluatorClass()
Returns value of the EvaluatorClass option.
-
getFrom
public java.lang.String getFrom()
Returns value of the From option.
-
getReplyTo
public java.lang.String getReplyTo()
Get the reply addresses.- Returns:
- reply addresses as comma separated string, may be null.
- Since:
- 1.2.16
-
getSubject
public java.lang.String getSubject()
Returns value of the Subject option.
-
setFrom
public void setFrom(java.lang.String from)
The From option takes a string value which should be a e-mail address of the sender.
-
setReplyTo
public void setReplyTo(java.lang.String addresses)
Set the e-mail addresses to which replies should be directed.- Parameters:
addresses
- reply addresses as comma separated string, may be null.- Since:
- 1.2.16
-
setSubject
public void setSubject(java.lang.String subject)
The Subject option takes a string value which should be a the subject of the e-mail message.
-
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 theBufferSize
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(java.lang.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 java.lang.String getSMTPHost()
Returns value of the SMTPHost option.
-
setTo
public void setTo(java.lang.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(java.lang.String value)
The EvaluatorClass option takes a string value representing the name of the class implementing theTriggeringEventEvaluator
interface. A corresponding object will be instantiated and assigned as the triggering event evaluator for the 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.
-
setCc
public void setCc(java.lang.String addresses)
Set the cc recipient addresses.- Parameters:
addresses
- recipient addresses as comma separated string, may be null.- Since:
- 1.2.14
-
getCc
public java.lang.String getCc()
Get the cc recipient addresses.- Returns:
- recipient addresses as comma separated string, may be null.
- Since:
- 1.2.14
-
setBcc
public void setBcc(java.lang.String addresses)
Set the bcc recipient addresses.- Parameters:
addresses
- recipient addresses as comma separated string, may be null.- Since:
- 1.2.14
-
getBcc
public java.lang.String getBcc()
Get the bcc recipient addresses.- Returns:
- recipient addresses as comma separated string, may be null.
- Since:
- 1.2.14
-
setSMTPPassword
public void setSMTPPassword(java.lang.String password)
The SmtpPassword option takes a string value which should be the password required to authenticate against the mail server.- Parameters:
password
- password, may be null.- Since:
- 1.2.14
-
setSMTPUsername
public void setSMTPUsername(java.lang.String username)
The SmtpUsername option takes a string value which should be the username required to authenticate against the mail server.- Parameters:
username
- user name, may be null.- Since:
- 1.2.14
-
setSMTPDebug
public void setSMTPDebug(boolean debug)
Setting the SmtpDebug option to true will cause the mail session to log its server interaction to stdout. This can be useful when debuging the appender but should not be used during production because username and password information is included in the output.- Parameters:
debug
- debug flag.- Since:
- 1.2.14
-
getSMTPPassword
public java.lang.String getSMTPPassword()
Get SMTP password.- Returns:
- SMTP password, may be null.
- Since:
- 1.2.14
-
getSMTPUsername
public java.lang.String getSMTPUsername()
Get SMTP user name.- Returns:
- SMTP user name, may be null.
- Since:
- 1.2.14
-
getSMTPDebug
public boolean getSMTPDebug()
Get SMTP debug.- Returns:
- SMTP debug flag.
- Since:
- 1.2.14
-
setEvaluator
public final void setEvaluator(TriggeringEventEvaluator trigger)
Sets triggering evaluator.- Parameters:
trigger
- triggering event evaluator.- Since:
- 1.2.15
-
getEvaluator
public final TriggeringEventEvaluator getEvaluator()
Get triggering evaluator.- Returns:
- triggering event evaluator.
- Since:
- 1.2.15
-
parseUnrecognizedElement
public boolean parseUnrecognizedElement(org.w3c.dom.Element element, java.util.Properties props) throws java.lang.Exception
Called to inform a configured object when an unrecognized child element is encountered.- Specified by:
parseUnrecognizedElement
in interfaceUnrecognizedElementHandler
- Parameters:
element
- element, may not be null.props
- properties in force, may be null.- Returns:
- true if configured object recognized the element
- Throws:
java.lang.Exception
- throw an exception to prevent activation of the configured object.- Since:
- 1.2.15
-
getSMTPProtocol
public final java.lang.String getSMTPProtocol()
Get transport protocol. Typically null or "smtps".- Returns:
- transport protocol, may be null.
- Since:
- 1.2.16
-
setSMTPProtocol
public final void setSMTPProtocol(java.lang.String val)
Set transport protocol. Typically null or "smtps".- Parameters:
val
- transport protocol, may be null.- Since:
- 1.2.16
-
getSMTPPort
public final int getSMTPPort()
Get port.- Returns:
- port, negative values indicate use of default ports for protocol.
- Since:
- 1.2.16
-
setSMTPPort
public final void setSMTPPort(int val)
Set port.- Parameters:
val
- port, negative values indicate use of default ports for protocol.- Since:
- 1.2.16
-
getSendOnClose
public final boolean getSendOnClose()
Get sendOnClose.- Returns:
- if true all buffered logging events will be sent when the appender is closed.
- Since:
- 1.2.16
-
setSendOnClose
public final void setSendOnClose(boolean val)
Set sendOnClose.- Parameters:
val
- if true all buffered logging events will be sent when appender is closed.- Since:
- 1.2.16
-
-