Package org.apache.log4j.net

Class SMTPAppender

  • All Implemented Interfaces:
    org.apache.log4j.Appender, org.apache.log4j.spi.OptionHandler, org.apache.log4j.xml.UnrecognizedElementHandler
    public class SMTPAppender
extends org.apache.log4j.AppenderSkeleton
implements org.apache.log4j.xml.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.0
    Author:
    Ceki Gülcü

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected org.apache.log4j.helpers.CyclicBuffer cb  
      protected org.apache.log4j.spi.TriggeringEventEvaluator evaluator  
      protected javax.mail.Message msg  

      • 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 a TriggeringEventEvaluator that will trigger on events with level ERROR or higher.
      SMTPAppender​(org.apache.log4j.spi.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 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()  
      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.
      org.apache.log4j.spi.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)
      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 setEvaluator​(org.apache.log4j.spi.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

    • Field Detail

      • msg

        protected javax.mail.Message msg

      • evaluator

        protected org.apache.log4j.spi.TriggeringEventEvaluator evaluator

      • cb

        protected org.apache.log4j.helpers.CyclicBuffer cb

    • 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​(org.apache.log4j.spi.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 org.apache.log4j.spi.OptionHandler
        Overrides:
        activateOptions in class org.apache.log4j.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.
        Specified by:
        append in class org.apache.log4j.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

      • 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()
        Specified by:
        close in interface org.apache.log4j.Appender

      • requiresLayout

        public boolean requiresLayout()
        The SMTPAppender requires a layout.
        Specified by:
        requiresLayout in interface org.apache.log4j.Appender

      • getTo

        public String getTo()
        Returns value of the To 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.

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

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

      • getFrom

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

      • setFrom

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

      • getReplyTo

        public String getReplyTo()
        Get the reply addresses.
        Returns:
        reply addresses as comma separated string, may be null.
        Since:
        1.2.16

      • 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

      • getSubject

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

      • setSubject

        public void setSubject​(String subject)
        The Subject option takes a string value which should be a the subject of the e-mail message.

      • getSMTPHost

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

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

      • getBufferSize

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

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

      • getLocationInfo

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

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

      • getCc

        public String getCc()
        Get the cc recipient addresses.
        Returns:
        recipient addresses as comma separated string, may be null.
        Since:
        1.2.14

      • 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

      • getBcc

        public String getBcc()
        Get the bcc 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

      • getSMTPPassword

        public String getSMTPPassword()
        Get SMTP password.
        Returns:
        SMTP password, 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

      • getSMTPUsername

        public String getSMTPUsername()
        Get SMTP user name.
        Returns:
        SMTP user name, 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

      • getSMTPDebug

        public boolean getSMTPDebug()
        Get SMTP debug.
        Returns:
        SMTP debug flag.
        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

      • getEvaluator

        public final org.apache.log4j.spi.TriggeringEventEvaluator getEvaluator()
        Get triggering evaluator.
        Returns:
        triggering event evaluator.
        Since:
        1.2.15

      • setEvaluator

        public final void setEvaluator​(org.apache.log4j.spi.TriggeringEventEvaluator trigger)
        Sets triggering evaluator.
        Parameters:
        trigger - triggering event evaluator.
        Since:
        1.2.15

      • parseUnrecognizedElement

        public boolean parseUnrecognizedElement​(Element element,
                                        Properties props)
                                 throws Exception
        Specified by:
        parseUnrecognizedElement in interface org.apache.log4j.xml.UnrecognizedElementHandler
        Throws:
        Exception
        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