Class SMTPAppender
- All Implemented Interfaces:
Appender,OptionHandler,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 last
BufferSize 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.2.18.3 checkServerIdentity option will check that the certificate presented by the server matches the
SMTPHost. Note that this option is 'true' by default but is only active if the SMTPProtocol is "smtps."
- Since:
- 1.0
- Author:
- Ceki Gülcü
-
Field Summary
FieldsModifier and TypeFieldDescriptionprotected CyclicBufferprotected TriggeringEventEvaluatorprotected javax.mail.MessageFields inherited from class org.apache.log4j.AppenderSkeleton
closed, errorHandler, headFilter, layout, name, tailFilter, threshold -
Constructor Summary
ConstructorsConstructorDescriptionThe default constructor will instantiate the appender with aTriggeringEventEvaluatorthat will trigger on events with level ERROR or higher.SMTPAppender(TriggeringEventEvaluator evaluator) Useevaluatorpassed as parameter as theTriggeringEventEvaluatorfor this SMTPAppender. -
Method Summary
Modifier and TypeMethodDescriptionvoidActivate the specified options, such as the smtp host, the recipient, from, etc.protected voidaddressMessage(javax.mail.Message msg) Address message.voidappend(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 booleanThis method determines if there is a sense in attempting to append.voidclose()Release any resources allocated within the appender such as file handles, network connections, etc.protected javax.mail.SessionCreate mail session.protected StringLayout body of email message.getBcc()Get the bcc recipient addresses.intReturns value of the BufferSize option.getCc()Get the cc recipient addresses.booleanThis option enables server identity check and if false will disable server identity check.final TriggeringEventEvaluatorGet triggering evaluator.Returns value of the EvaluatorClass option.getFrom()Returns value of the From option.booleanReturns value of the LocationInfo option.Get the reply addresses.final booleanGet sendOnClose.booleanGet SMTP debug.Returns value of the SMTPHost option.Get SMTP password.final intGet port.final StringGet transport protocol.Get SMTP user name.Returns value of the Subject option.getTo()Returns value of the To option.booleanparseUnrecognizedElement(Element element, Properties props) Called to inform a configured object when an unrecognized child element is encountered.booleanTheSMTPAppenderrequires alayout.protected voidSend the contents of the cyclic buffer as an e-mail message.voidSet the bcc recipient addresses.voidsetBufferSize(int bufferSize) The BufferSize option takes a positive integer representing the maximum number of logging events to collect in a cyclic buffer.voidSet the cc recipient addresses.voidsetCheckServerIdentity(boolean checkServerIdentity) Setting the checkServerIdentity option to false will disable server identity check.final voidsetEvaluator(TriggeringEventEvaluator trigger) Sets triggering evaluator.voidsetEvaluatorClass(String value) The EvaluatorClass option takes a string value representing the name of the class implementing theTriggeringEventEvaluatorinterface.voidThe From option takes a string value which should be a e-mail address of the sender.voidsetLocationInfo(boolean locationInfo) The LocationInfo option takes a boolean value.voidsetReplyTo(String addresses) Set the e-mail addresses to which replies should be directed.final voidsetSendOnClose(boolean val) Set sendOnClose.voidsetSMTPDebug(boolean debug) Setting the SmtpDebug option to true will cause the mail session to log its server interaction to stdout.voidsetSMTPHost(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.voidsetSMTPPassword(String password) The SmtpPassword option takes a string value which should be the password required to authenticate against the mail server.final voidsetSMTPPort(int val) Set port.final voidsetSMTPProtocol(String val) Set transport protocol.voidsetSMTPUsername(String username) The SmtpUsername option takes a string value which should be the username required to authenticate against the mail server.voidsetSubject(String subject) The Subject option takes a string value which should be a the subject of the e-mail message.voidThe 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 Details
-
cb
-
msg
protected javax.mail.Message msg -
evaluator
-
-
Constructor Details
-
SMTPAppender
public SMTPAppender()The default constructor will instantiate the appender with aTriggeringEventEvaluatorthat will trigger on events with level ERROR or higher. -
SMTPAppender
Useevaluatorpassed as parameter as theTriggeringEventEvaluatorfor this SMTPAppender.
-
-
Method Details
-
activateOptions
public void activateOptions()Activate the specified options, such as the smtp host, the recipient, from, etc.- Specified by:
activateOptionsin interfaceOptionHandler- Overrides:
activateOptionsin 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
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:
appendin 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
falseis returned. -
close
public void close()Description copied from interface:AppenderRelease 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
Returns value of the To option. -
requiresLayout
public boolean requiresLayout()TheSMTPAppenderrequires alayout.- Specified by:
requiresLayoutin interfaceAppender
-
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
Returns value of the EvaluatorClass option. -
getFrom
Returns value of the From option. -
getReplyTo
Get the reply addresses.- Returns:
- reply addresses as comma separated string, may be null.
- Since:
- 1.2.16
-
getSubject
Returns value of the Subject option. -
setFrom
The From option takes a string value which should be a e-mail address of the sender. -
setReplyTo
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
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 theBufferSizeis 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
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
Returns value of the SMTPHost option. -
setTo
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
The EvaluatorClass option takes a string value representing the name of the class implementing theTriggeringEventEvaluatorinterface. 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
Set the cc recipient addresses.- Parameters:
addresses- recipient addresses as comma separated string, may be null.- Since:
- 1.2.14
-
getCc
Get the cc recipient addresses.- Returns:
- recipient addresses as comma separated string, may be null.
- Since:
- 1.2.14
-
setBcc
Set the bcc recipient addresses.- Parameters:
addresses- recipient addresses as comma separated string, may be null.- Since:
- 1.2.14
-
getBcc
Get the bcc recipient addresses.- Returns:
- recipient addresses as comma separated string, may be null.
- Since:
- 1.2.14
-
setSMTPPassword
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
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
-
setCheckServerIdentity
public void setCheckServerIdentity(boolean checkServerIdentity) Setting the checkServerIdentity option to false will disable server identity check. By default this option is enabled. However, it is only active if the SMTPProtocol is "smtps."- Parameters:
checkServerIdentity-- Since:
- 1.2.18.3
-
getCheckServerIdentity
public boolean getCheckServerIdentity()This option enables server identity check and if false will disable server identity check. By default this option is enabled. However, it is only active if the SMTPProtocol is "smtps."- Parameters:
checkServerIdentity-- Since:
- 1.2.18.3
-
getSMTPPassword
Get SMTP password.- Returns:
- SMTP password, may be null.
- Since:
- 1.2.14
-
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
Sets triggering evaluator.- Parameters:
trigger- triggering event evaluator.- Since:
- 1.2.15
-
getEvaluator
Get triggering evaluator.- Returns:
- triggering event evaluator.
- Since:
- 1.2.15
-
parseUnrecognizedElement
Called to inform a configured object when an unrecognized child element is encountered.- Specified by:
parseUnrecognizedElementin interfaceUnrecognizedElementHandler- Parameters:
element- element, may not be null.props- properties in force, may be null.- Returns:
- true if configured object recognized the element
- Throws:
Exception- throw an exception to prevent activation of the configured object.- Since:
- 1.2.15
-
getSMTPProtocol
Get transport protocol. Typically null or "smtps".- Returns:
- transport protocol, may be null.
- Since:
- 1.2.16
-
setSMTPProtocol
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
-