Package com.sun.mail.util.logging

Class DurationFilter

  • All Implemented Interfaces:
    java.util.logging.Filter
    public class DurationFilter
extends java.lang.Object
implements java.util.logging.Filter
    A filter used to limit log records based on a maximum generation rate. The duration specified is used to compute the record rate and the amount of time the filter will reject records once the rate has been exceeded. Once the rate is exceeded records are not allowed until the duration has elapsed.

    By default each DurationFilter is initialized using the following LogManager configuration properties where <filter-name> refers to the fully qualified class name of the handler. If properties are not defined, or contain invalid values, then the specified default values are used.

    • <filter-name>.records the max number of records per duration. A numeric long integer or a multiplication expression can be used as the value. (defaults to 1000)
    • <filter-name>.duration the number of milliseconds to suppress log records from being published. This is also used as duration to determine the log record rate. A numeric long integer or a multiplication expression can be used as the value. If the java.time package is available then an ISO-8601 duration format of PnDTnHnMn.nS can be used as the value. The suffixes of "D", "H", "M" and "S" are for days, hours, minutes and seconds. The suffixes must occur in order. The seconds can be specified with a fractional component to declare milliseconds. (defaults to PT15M)

    For example, the settings to limit MailHandler with a default capacity to only send a maximum of two email messages every six minutes would be as follows: 

     
  com.sun.mail.util.logging.MailHandler.filter = com.sun.mail.util.logging.DurationFilter
  com.sun.mail.util.logging.MailHandler.capacity = 1000
  com.sun.mail.util.logging.DurationFilter.records = 2L * 1000L
  com.sun.mail.util.logging.DurationFilter.duration = PT6M
    Since:
    JavaMail 1.5.5

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private long count
      The number of records seen for the current duration.
      private long duration
      The duration in milliseconds used to determine the rate.
      private long peak
      The most recent record time seen for the current duration.
      private long records
      The number of expected records per duration.
      private long start
      The start time for the current duration.

    • Constructor Summary

      Constructors 
      Constructor Description
      DurationFilter()
      Creates the filter using the default properties.
      DurationFilter​(long records, long duration)
      Creates the filter using the given properties.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      private boolean accept​(long millis)
      Determines if the record is loggable by time.
      private static long checkDuration​(long duration)
      Converts the duration to a valid duration.
      private static long checkRecords​(long records)
      Converts record count to a valid record count.
      protected DurationFilter clone()
      Creates a copy of this filter that retains the filter settings but does not include the current filter state.
      boolean equals​(java.lang.Object obj)
      Determines if this filter is equal to another filter.
      int hashCode()
      Returns a hash code value for this filter.
      private long initLong​(java.lang.String suffix)
      Reads a long value or multiplication expression from the LogManager.
      boolean isIdle()
      Determines if this filter is able to accept the maximum number of log records for this instant in time.
      boolean isLoggable()
      Determines if this filter will accept log records for this instant in time.
      boolean isLoggable​(java.util.logging.LogRecord record)
      Check if the given log record should be published.
      private boolean isTimeEntry​(java.lang.String suffix, java.lang.String value)
      Determines if the given suffix can be a time unit and the value is encoded as an ISO ISO-8601 duration format.
      private static long multiplyExact​(long x, long y)
      Multiply and check for overflow.
      private boolean test​(long limit, long millis)
      Checks if this filter is not saturated or bellow a maximum rate.
      private static java.lang.String[] tokenizeLongs​(java.lang.String value)
      Parse any long value or multiplication expressions into tokens.
      java.lang.String toString()
      Returns a string representation of this filter.

      • Methods inherited from class java.lang.Object

        finalize, getClass, notify, notifyAll, wait, wait, wait

    • Field Detail

      • records

        private final long records
        The number of expected records per duration.

      • duration

        private final long duration
        The duration in milliseconds used to determine the rate. The duration is also used as the amount of time that the filter will not allow records when saturated.

      • count

        private long count
        The number of records seen for the current duration. This value negative if saturated. Zero is considered saturated but is reserved for recording the first duration.

      • peak

        private long peak
        The most recent record time seen for the current duration.

      • start

        private long start
        The start time for the current duration.

    • Constructor Detail

      • DurationFilter

        public DurationFilter()
        Creates the filter using the default properties.

      • DurationFilter

        public DurationFilter​(long records,
                      long duration)
        Creates the filter using the given properties. Default values are used if any of the given values are outside the allowed range.
        Parameters:
        records - the number of records per duration.
        duration - the number of milliseconds to suppress log records from being published.

    • Method Detail

      • equals

        public boolean equals​(java.lang.Object obj)
        Determines if this filter is equal to another filter.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        obj - the given object.
        Returns:
        true if equal otherwise false.

      • isIdle

        public boolean isIdle()
        Determines if this filter is able to accept the maximum number of log records for this instant in time. The result is a best-effort estimate and should be considered out of date as soon as it is produced. This method is designed for use in monitoring the state of this filter.
        Returns:
        true if the filter is idle; false otherwise.

      • hashCode

        public int hashCode()
        Returns a hash code value for this filter.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        hash code for this filter.

      • isLoggable

        public boolean isLoggable​(java.util.logging.LogRecord record)
        Check if the given log record should be published. This method will modify the internal state of this filter.
        Specified by:
        isLoggable in interface java.util.logging.Filter
        Parameters:
        record - the log record to check.
        Returns:
        true if allowed; false otherwise.
        Throws:
        java.lang.NullPointerException - if given record is null.

      • isLoggable

        public boolean isLoggable()
        Determines if this filter will accept log records for this instant in time. The result is a best-effort estimate and should be considered out of date as soon as it is produced. This method is designed for use in monitoring the state of this filter.
        Returns:
        true if the filter is not saturated; false otherwise.

      • toString

        public java.lang.String toString()
        Returns a string representation of this filter. The result is a best-effort estimate and should be considered out of date as soon as it is produced.
        Overrides:
        toString in class java.lang.Object
        Returns:
        a string representation of this filter.

      • clone

        protected DurationFilter clone()
                        throws java.lang.CloneNotSupportedException
        Creates a copy of this filter that retains the filter settings but does not include the current filter state. The newly create clone acts as if it has never seen any records.
        Overrides:
        clone in class java.lang.Object
        Returns:
        a copy of this filter.
        Throws:
        java.lang.CloneNotSupportedException - if this filter is not allowed to be cloned.

      • test

        private boolean test​(long limit,
                     long millis)
        Checks if this filter is not saturated or bellow a maximum rate.
        Parameters:
        limit - the number of records allowed to be under the rate.
        millis - the current time in milliseconds.
        Returns:
        true if not saturated or bellow the rate.

      • accept

        private boolean accept​(long millis)
        Determines if the record is loggable by time.
        Parameters:
        millis - the log record milliseconds.
        Returns:
        true if accepted false otherwise.

      • initLong

        private long initLong​(java.lang.String suffix)
        Reads a long value or multiplication expression from the LogManager. If the value can not be parsed or is not defined then Long.MIN_VALUE is returned.
        Parameters:
        suffix - a dot character followed by the key name.
        Returns:
        a long value or Long.MIN_VALUE if unable to parse or undefined.
        Throws:
        java.lang.NullPointerException - if suffix is null.

      • isTimeEntry

        private boolean isTimeEntry​(java.lang.String suffix,
                            java.lang.String value)
        Determines if the given suffix can be a time unit and the value is encoded as an ISO ISO-8601 duration format.
        Parameters:
        suffix - the suffix property.
        value - the value of the property.
        Returns:
        true if the entry is a time entry.
        Throws:
        java.lang.IndexOutOfBoundsException - if value is empty.
        java.lang.NullPointerException - if either argument is null.

      • tokenizeLongs

        private static java.lang.String[] tokenizeLongs​(java.lang.String value)
        Parse any long value or multiplication expressions into tokens.
        Parameters:
        value - the expression or value.
        Returns:
        an array of long tokens, never empty.
        Throws:
        java.lang.NullPointerException - if the given value is null.
        java.lang.NumberFormatException - if the expression is invalid.

      • multiplyExact

        private static long multiplyExact​(long x,
                                  long y)
        Multiply and check for overflow. This can be replaced with java.lang.Math.multiplyExact when JavaMail requires JDK 8.
        Parameters:
        x - the first value.
        y - the second value.
        Returns:
        x times y.
        Throws:
        java.lang.ArithmeticException - if overflow is detected.

      • checkRecords

        private static long checkRecords​(long records)
        Converts record count to a valid record count. If the value is out of bounds then the default record count is used.
        Parameters:
        records - the record count.
        Returns:
        a valid number of record count.

      • checkDuration

        private static long checkDuration​(long duration)
        Converts the duration to a valid duration. If the value is out of bounds then the default duration is used.
        Parameters:
        duration - the duration to check.
        Returns:
        a valid duration.