SMTPAppender (reload4j 1.2.25 API)

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

Fields
Modifier and Type Field and Description

protected CyclicBuffer cb

protected TriggeringEventEvaluator evaluator

protected javax.mail.Message msg
- Fields inherited from class org.apache.log4j.AppenderSkeleton
  closed, errorHandler, headFilter, layout, name, tailFilter, threshold

Fields
Modifier and Type	Field and Description
`protected CyclicBuffer`	`cb`
`protected TriggeringEventEvaluator`	`evaluator`
`protected javax.mail.Message`	`msg`

Constructor Summary

Constructors
Constructor and Description
`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

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and 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 String`	`formatBody()` Layout body of email message.
`String`	`getBcc()` Get the bcc recipient addresses.
`int`	`getBufferSize()` Returns value of the BufferSize option.
`String`	`getCc()` Get the cc recipient addresses.
`boolean`	`getCheckServerIdentity()` This option enables server identity check and if false will disable server identity check.
`TriggeringEventEvaluator`	`getEvaluator()` Get triggering evaluator.
`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`	`getReplyTo()` Get the reply addresses.
`boolean`	`getSendOnClose()` Get sendOnClose.
`boolean`	`getSMTPDebug()` Get SMTP debug.
`String`	`getSMTPHost()` Returns value of the SMTPHost option.
`String`	`getSMTPPassword()` Get SMTP password.
`int`	`getSMTPPort()` Get port.
`String`	`getSMTPProtocol()` Get transport protocol.
`String`	`getSMTPUsername()` Get SMTP user name.
`String`	`getSubject()` Returns value of the Subject option.
`String`	`getTo()` Returns value of the To option.
`boolean`	`parseUnrecognizedElement(Element element, Properties props)` Called to inform a configured object when an unrecognized child element is encountered.
`boolean`	`requiresLayout()` The `SMTPAppender` requires a `layout`.
`protected void`	`sendBuffer()` Send the contents of the cyclic buffer as an e-mail message.
`void`	`setBcc(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(String addresses)` Set the cc recipient addresses.
`void`	`setCheckServerIdentity(boolean checkServerIdentity)` Setting the checkServerIdentity option to false will disable server identity check.
`void`	`setEvaluator(TriggeringEventEvaluator trigger)` Sets triggering evaluator.
`void`	`setEvaluatorClass(String value)` The EvaluatorClass option takes a string value representing the name of the class implementing the `TriggeringEventEvaluator` interface.
`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`	`setReplyTo(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(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(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(String val)` Set transport protocol.
`void`	`setSMTPUsername(String username)` The SmtpUsername option takes a string value which should be the username required to authenticate against the mail server.
`void`	`setSubject(String subject)` The Subject option takes a string value which should be a 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, isAsSevereAsThreshold, setErrorHandler, setLayout, setName, setThreshold

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - 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 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.
    
    Specified by:
    
    activateOptions in interface OptionHandler
    
    Overrides:
    
    activateOptions in class AppenderSkeleton
  - 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 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.
    
    Specified by:
    
    close in interface Appender
  - getTo
```
public String getTo()
```
    Returns value of the To option.
  - requiresLayout
```
public boolean requiresLayout()
```
    The SMTPAppender requires a layout.
    
    Specified by:
    
    requiresLayout in interface Appender
  - formatBody
```
protected 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 String getEvaluatorClass()
```
    Returns value of the EvaluatorClass option.
  - getFrom
```
public String getFrom()
```
    Returns value of the From option.
  - getReplyTo
```
public String getReplyTo()
```
    Get the reply addresses.
    
    Returns:
    
    reply addresses as comma separated string, may be null.
    
    Since:
    
    1.2.16
  - 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.
  - setReplyTo
```
public void setReplyTo(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(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 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)
```
    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.
  - 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(String addresses)
```
    Set the cc recipient addresses.
    
    Parameters:
    
    addresses - recipient addresses as comma separated string, may be null.
    
    Since:
    
    1.2.14
  - getCc
```
public 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(String addresses)
```
    Set the bcc recipient addresses.
    
    Parameters:
    
    addresses - recipient addresses as comma separated string, may be null.
    
    Since:
    
    1.2.14
  - getBcc
```
public 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(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(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
  - 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
```
public String getSMTPPassword()
```
    Get SMTP password.
    
    Returns:
    
    SMTP password, may be null.
    
    Since:
    
    1.2.14
  - getSMTPUsername
```
public 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(Element element,
                                        Properties props)
                                 throws Exception
```
    Called to inform a configured object when an unrecognized child element is encountered.
    
    Specified by:
    
    parseUnrecognizedElement in interface UnrecognizedElementHandler
    
    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
```
public final String getSMTPProtocol()
```
    Get transport protocol. Typically null or "smtps".
    
    Returns:
    
    transport protocol, may be null.
    
    Since:
    
    1.2.16
  - setSMTPProtocol
```
public final void setSMTPProtocol(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

Class SMTPAppender

Field Summary

Fields inherited from class org.apache.log4j.AppenderSkeleton

Constructor Summary

Method Summary

Methods inherited from class org.apache.log4j.AppenderSkeleton

Methods inherited from class java.lang.Object

Field Detail

cb

msg

evaluator

Constructor Detail

SMTPAppender

SMTPAppender

Method Detail

activateOptions

addressMessage

createSession

append

checkEntryConditions

close

getTo

requiresLayout

formatBody

sendBuffer

getEvaluatorClass

getFrom

getReplyTo

getSubject

setFrom

setReplyTo

setSubject

setBufferSize

setSMTPHost

getSMTPHost

setTo

getBufferSize

setEvaluatorClass

setLocationInfo

getLocationInfo

setCc

getCc

setBcc

getBcc

setSMTPPassword

setSMTPUsername

setSMTPDebug

setCheckServerIdentity

getCheckServerIdentity

getSMTPPassword

getSMTPUsername

getSMTPDebug

setEvaluator

getEvaluator

parseUnrecognizedElement

getSMTPProtocol

setSMTPProtocol

getSMTPPort

setSMTPPort

getSendOnClose

setSendOnClose