Top Description Fields Constructors Methods
com.sun.mail.util.logging

public Class DurationFilter

extends Object
implements Filter
Class Inheritance
All Implemented Interfaces
java.util.logging.Filter
Static Imports
com.sun.mail.util.logging.LogManagerProperties.fromLogManager
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.

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
Author
Jason Mehrens
Since
JavaMail 1.5.5

Field Summary

Modifier and TypeField and Description
private long
count

The number of records seen for the current duration.

private final 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 final long
records

The number of expected records per duration.

private long
start

The start time for the current duration.

Constructor Summary

AccessConstructor and Description
public
DurationFilter()

Creates the filter using the default properties.

public
DurationFilter(final long
the number of records per duration.
records, final long
the number of milliseconds to suppress log records from being published.
duration)

Creates the filter using the given properties.

Method Summary

Modifier and TypeMethod and Description
private synchronized boolean

Returns:

true if accepted false otherwise.
accept(final long
the log record milliseconds.
millis)

Determines if the record is loggable by time.

private static long

Returns:

a valid duration.
checkDuration(final long
the duration to check.
duration)

Converts the duration to a valid duration.

private static long

Returns:

a valid number of record count.
checkRecords(final long
the record count.
records)

Converts record count to a valid record count.

protected DurationFilter

Returns:

a copy of this filter.
clone()

Overrides java.lang.Object.clone.

Creates a copy of this filter that retains the filter settings but does not include the current filter state.
public boolean

Returns:

true if equal otherwise false.
equals(final Object
the given object.
obj)

Overrides java.lang.Object.equals.

Determines if this filter is equal to another filter.
public int

Returns:

hash code for this filter.
hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code value for this filter.
private long

Returns:

a long value or Long.MIN_VALUE if unable to parse or undefined.
initLong(final String
a dot character followed by the key name.
suffix)

Reads a long value or multiplication expression from the LogManager.

public boolean

Returns:

true if the filter is idle; false otherwise.
isIdle()

Determines if this filter is able to accept the maximum number of log records for this instant in time.

public boolean

Returns:

true if allowed; false otherwise.
isLoggable(final LogRecord
the log record to check.
record)

Implements java.util.logging.Filter.isLoggable.

Check if the given log record should be published.
public boolean

Returns:

true if the filter is not saturated; false otherwise.
isLoggable()

Determines if this filter will accept log records for this instant in time.

private boolean

Returns:

true if the entry is a time entry.
isTimeEntry(final String
the suffix property.
suffix, final String
the value of the property.
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

Returns:

x times y.
multiplyExact(final long
the first value.
x, final long
the second value.
y)

Multiply and check for overflow.

private boolean

Returns:

true if not saturated or bellow the rate.
test(final long
the number of records allowed to be under the rate.
limit, final long
the current time in milliseconds.
millis)

Checks if this filter is not saturated or bellow a maximum rate.

private static String[]

Returns:

an array of long tokens, never empty.
tokenizeLongs(final String
the expression or value.
value)

Parse any long value or multiplication expressions into tokens.

public String

Returns:

a string representation of this filter.
toString()

Overrides java.lang.Object.toString.

Returns a string representation of this filter.
Inherited from java.lang.Object:
finalizegetClassnotifynotifyAllwaitwaitwait

Field Detail

countback to summary
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.

durationback to summary
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.

peakback to summary
private long peak

The most recent record time seen for the current duration.

recordsback to summary
private final long records

The number of expected records per duration.

startback to summary
private long start

The start time for the current duration.

Constructor Detail

DurationFilterback to summary
public DurationFilter()

Creates the filter using the default properties.

DurationFilterback to summary
public DurationFilter(final long records, final 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:long

the number of records per duration.

duration:long

the number of milliseconds to suppress log records from being published.

Method Detail

acceptback to summary
private synchronized boolean accept(final long millis)

Determines if the record is loggable by time.

Parameters
millis:long

the log record milliseconds.

Returns:boolean

true if accepted false otherwise.

checkDurationback to summary
private static long checkDuration(final long duration)

Converts the duration to a valid duration. If the value is out of bounds then the default duration is used.

Parameters
duration:long

the duration to check.

Returns:long

a valid duration.

checkRecordsback to summary
private static long checkRecords(final 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:long

the record count.

Returns:long

a valid number of record count.

cloneback to summary
protected DurationFilter clone() throws CloneNotSupportedException

Overrides java.lang.Object.clone.

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.

Returns:DurationFilter

a copy of this filter.

Annotations
@Override
Exceptions
CloneNotSupportedException:
if this filter is not allowed to be cloned.
equalsback to summary
public boolean equals(final Object obj)

Overrides java.lang.Object.equals.

Determines if this filter is equal to another filter.

Parameters
obj:Object

the given object.

Returns:boolean

true if equal otherwise false.

Annotations
@Override
hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code value for this filter.

Returns:int

hash code for this filter.

Annotations
@Override
initLongback to summary
private long initLong(final 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:String

a dot character followed by the key name.

Returns:long

a long value or Long.MIN_VALUE if unable to parse or undefined.

Exceptions
NullPointerException:
if suffix is null.
isIdleback to summary
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:boolean

true if the filter is idle; false otherwise.

isLoggableback to summary
public boolean isLoggable(final LogRecord record)

Implements java.util.logging.Filter.isLoggable.

Check if the given log record should be published. This method will modify the internal state of this filter.

Parameters
record:LogRecord

the log record to check.

Returns:boolean

true if allowed; false otherwise.

Annotations
@SuppressWarnings:override
Exceptions
NullPointerException:
if given record is null.
isLoggableback to summary
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:boolean

true if the filter is not saturated; false otherwise.

isTimeEntryback to summary
private boolean isTimeEntry(final String suffix, final 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:String

the suffix property.

value:String

the value of the property.

Returns:boolean

true if the entry is a time entry.

Exceptions
IndexOutOfBoundsException:
if value is empty.
NullPointerException:
if either argument is null.
multiplyExactback to summary
private static long multiplyExact(final long x, final long y)

Multiply and check for overflow. This can be replaced with java.lang.Math.multiplyExact when JavaMail requires JDK 8.

Parameters
x:long

the first value.

y:long

the second value.

Returns:long

x times y.

Exceptions
ArithmeticException:
if overflow is detected.
testback to summary
private boolean test(final long limit, final long millis)

Checks if this filter is not saturated or bellow a maximum rate.

Parameters
limit:long

the number of records allowed to be under the rate.

millis:long

the current time in milliseconds.

Returns:boolean

true if not saturated or bellow the rate.

tokenizeLongsback to summary
private static String[] tokenizeLongs(final String value)

Parse any long value or multiplication expressions into tokens.

Parameters
value:String

the expression or value.

Returns:String[]

an array of long tokens, never empty.

Exceptions
NullPointerException:
if the given value is null.
NumberFormatException:
if the expression is invalid.
toStringback to summary
public String toString()

Overrides java.lang.Object.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.

Returns:String

a string representation of this filter.

Annotations
@Override