- java.lang.Object
-
- java.util.logging.Handler
-
- com.sun.mail.util.logging.MailHandler
-
public class MailHandler extends java.util.logging.Handler
Handler
that formats log records as an email message.This
Handler
will store a fixed number of log records used to generate a single email message. When the internal buffer reaches capacity, all log records are formatted and placed in an email which is sent to an email server. The code to manually setup this handler can be as simple as the following:Properties props = new Properties(); props.put("mail.smtp.host", "my-mail-server"); props.put("mail.to", "me@example.com"); props.put("verify", "local"); MailHandler h = new MailHandler(props); h.setLevel(Level.WARNING);
Configuration: The LogManager should define at least one or more recipient addresses and a mail host for outgoing email. The code to setup this handler via the logging properties can be as simple as the following:
#Default MailHandler settings. com.sun.mail.util.logging.MailHandler.mail.smtp.host = my-mail-server com.sun.mail.util.logging.MailHandler.mail.to = me@example.com com.sun.mail.util.logging.MailHandler.level = WARNING com.sun.mail.util.logging.MailHandler.verify = local
For a custom handler, e.g.com.foo.MyHandler
, the properties would be:#Subclass com.foo.MyHandler settings. com.foo.MyHandler.mail.smtp.host = my-mail-server com.foo.MyHandler.mail.to = me@example.com com.foo.MyHandler.level = WARNING com.foo.MyHandler.verify = local
All mail properties documented in theJava Mail API
cascade to the LogManager by prefixing a key using the fully qualified class name of thisMailHandler
or the fully qualified derived class name dot mail property. If the prefixed property is not found, then the mail property itself is searched in the LogManager. By default eachMailHandler
is initialized using the following LogManager configuration properties where<handler-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.- <handler-name>.attachment.filters a comma
separated list of
Filter
class names used to create each attachment. The literalnull
is reserved for attachments that do not require filtering. (defaults to the body filter) - <handler-name>.attachment.formatters a comma
separated list of
Formatter
class names used to create each attachment. (default is no attachments) - <handler-name>.attachment.names a comma separated
list of names or
Formatter
class names of each attachment. All control characters are removed from the attachment names. (default is toString of the attachment formatter) - <handler-name>.authenticator name of an
Authenticator class used to provide login credentials
to the email server or string literal that is the password used with the
default user name.
(default is
null
) - <handler-name>.capacity the max number of
LogRecord
objects include in each email message. (defaults to1000
) - <handler-name>.comparator name of a
Comparator class used to sort the published
LogRecord
objects prior to all formatting. (defaults tonull
meaning records are unsorted). - <handler-name>.comparator.reverse a boolean
true
to reverse the order of the specified comparator orfalse
to retain the original order. (defaults tofalse
) - <handler-name>.encoding the name of the Java
character set to use for the
email message. (defaults to
null
, the default platform encoding). - <handler-name>.errorManager name of an
ErrorManager
class used to handle any configuration or mail transport problems. (defaults tojava.util.logging.ErrorManager
) - <handler-name>.filter name of a
Filter
class used for the body of the message. (defaults tonull
, allow all records) - <handler-name>.formatter name of a
Formatter
class used to format the body of this message. (defaults tojava.util.logging.SimpleFormatter
) - <handler-name>.level specifies the default level
for this
Handler
(defaults toLevel.WARNING
). - <handler-name>.mail.bcc a comma separated list of
addresses which will be blind carbon copied. Typically, this is set to the
recipients that may need to be privately notified of a log message or
notified that a log message was sent to a third party such as a support team.
The empty string can be used to specify no blind carbon copied address.
(defaults to
null
, none) - <handler-name>.mail.cc a comma separated list of
addresses which will be carbon copied. Typically, this is set to the
recipients that may need to be notified of a log message but, are not
required to provide direct support. The empty string can be used to specify
no carbon copied address. (defaults to
null
, none) - <handler-name>.mail.from a comma separated list of addresses which will be from addresses. Typically, this is set to the email address identifying the user running the application. The empty string can be used to override the default behavior and specify no from address. (defaults to the local address)
- <handler-name>.mail.host the host name or IP
address of the email server. (defaults to
null
, use defaultJava Mail
behavior) - <handler-name>.mail.reply.to a comma separated
list of addresses which will be reply-to addresses. Typically, this is set
to the recipients that provide support for the application itself. The empty
string can be used to specify no reply-to address.
(defaults to
null
, none) - <handler-name>.mail.to a comma separated list of addresses which will be send-to addresses. Typically, this is set to the recipients that provide support for the application, system, and/or supporting infrastructure. The empty string can be used to specify no send-to address which overrides the default behavior. (defaults to local address.)
- <handler-name>.mail.sender a single address
identifying sender of the email; never equal to the from address. Typically,
this is set to the email address identifying the application itself. The
empty string can be used to specify no sender address.
(defaults to
null
, none) - <handler-name>.subject the name of a
Formatter
class or string literal used to create the subject line. The empty string can be used to specify no subject. All control characters are removed from the subject line. (defaults to CollectorFormatter.) - <handler-name>.pushFilter the name of a
Filter
class used to trigger an early push. (defaults tonull
, no early push) - <handler-name>.pushLevel the level which will
trigger an early push. (defaults to
Level.OFF
, only push when full) - <handler-name>.verify used to
verify the
Handler
configuration prior to a push.- If the value is not set, equal to an empty string, or equal to the
literal
null
then no settings are verified prior to a push. - If set to a value of
limited
then theHandler
will verify minimal local machine settings. - If set to a value of
local
theHandler
will verify all of settings of the local machine. - If set to a value of
resolve
, theHandler
will verify all local settings and try to resolve the remote host name with the domain name server. - If set to a value of
login
, theHandler
will verify all local settings and try to establish a connection with the email server. - If set to a value of
remote
, theHandler
will verify all local settings, try to establish a connection with the email server, and try to verify the envelope of the email message.
Handler
is only implicitly closed by theLogManager
, then verification should be turned on. (defaults tonull
, no verify). - If the value is not set, equal to an empty string, or equal to the
literal
Normalization: The error manager, filters, and formatters when loaded from the LogManager are converted into canonical form inside the MailHandler. The pool of interned values is limited to each MailHandler object such that no two MailHandler objects created by the LogManager will be created sharing identical error managers, filters, or formatters. If a filter or formatter should not be interned then it is recommended to retain the identity equals and identity hashCode methods as the implementation. For a filter or formatter to be interned the class must implement the equals and hashCode methods. The recommended code to use for stateless filters and formatters is:
public boolean equals(Object obj) { return obj == null ? false : obj.getClass() == getClass(); } public int hashCode() { return 31 * getClass().hashCode(); }
Sorting: All
LogRecord
objects are ordered prior to formatting if thisHandler
has a non null comparator. Developers might be interested in sorting the formatted email by thread id, time, and sequence properties of aLogRecord
. Where as system administrators might be interested in sorting the formatted email by thrown, level, time, and sequence properties of aLogRecord
. If comparator for this handler isnull
then the order is unspecified.Formatting: The main message body is formatted using the
Formatter
returned bygetFormatter()
. Only records that pass the filter returned bygetFilter()
will be included in the message body. The subjectFormatter
will see allLogRecord
objects that were published regardless of the currentFilter
. The MIME type of the message body can be overridden by adding a MIME entry using the simple class name of the body formatter as the file extension. The MIME type of the attachments can be overridden by changing the attachment file name extension or by editing the default MIME entry for a specific file name extension.Attachments: This
Handler
allows multiple attachments per each email message. The presence of an attachment formatter will change the content type of the email message to a multi-part message. The attachment order maps directly to the array index order in thisHandler
with zero index being the first attachment. The number of attachment formatters controls the number of attachments per email and the content type of each attachment. The attachment filters determine if aLogRecord
will be included in an attachment. If an attachment filter isnull
then all records are included for that attachment. Attachments without content will be omitted from email message. The attachment name formatters create the file name for an attachment. Custom attachment name formatters can be used to generate an attachment name based on the contents of the attachment.Push Level and Push Filter: The push method, push level, and optional push filter can be used to conditionally trigger a push at or prior to full capacity. When a push occurs, the current buffer is formatted into an email and is sent to the email server. If the push method, push level, or push filter trigger a push then the outgoing email is flagged as high importance with urgent priority.
Buffering: Log records that are published are stored in an internal buffer. When this buffer reaches capacity the existing records are formatted and sent in an email. Any published records can be sent before reaching capacity by explictly calling the
flush
,push
, orclose
methods. If a circular buffer is required then this handler can be wrapped with a MemoryHandler typically with an equivalent capacity, level, and push level.Error Handling: If the transport of an email message fails, the email is converted to a raw string and is then passed as the
msg
parameter to reportError along with the exception describing the cause of the failure. This allows custom error managers to store, reconstruct, and resend the original MimeMessage. The message parameter string is not a raw email if it starts with value returned fromLevel.SEVERE.getName()
. Custom error managers can use the following test to determine if themsg
parameter from this handler is a raw email:public void error(String msg, Exception ex, int code) { if (msg == null || msg.length() == 0 || msg.startsWith(Level.SEVERE.getName())) { super.error(msg, ex, code); } else { //The 'msg' parameter is a raw email. } }
- Since:
- JavaMail 1.4.3
- Author:
- Jason Mehrens
- <handler-name>.attachment.filters a comma
separated list of
-
-
Constructor Summary
Constructors Constructor Description MailHandler()
Creates aMailHandler
that is configured by theLogManager
configuration properties.MailHandler(int capacity)
Creates aMailHandler
that is configured by theLogManager
configuration properties but overrides theLogManager
capacity with the given capacity.MailHandler(java.util.Properties props)
Creates a mail handler with the given mail properties.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
close()
Prevents any other records from being published.void
flush()
Pushes any buffered records to the email server as normal priority.java.util.logging.Filter[]
getAttachmentFilters()
Gets the attachment filters.java.util.logging.Formatter[]
getAttachmentFormatters()
Gets the attachment formatters.java.util.logging.Formatter[]
getAttachmentNames()
Gets the attachment name formatters.Authenticator
getAuthenticator()
Gets theAuthenticator
used to login to the email server.int
getCapacity()
Gets the number of log records the internal buffer can hold.java.util.Comparator<? super java.util.logging.LogRecord>
getComparator()
Gets the comparator used to order allLogRecord
objects prior to formatting.java.lang.String
getEncoding()
Return the character encoding for thisHandler
.java.util.logging.ErrorManager
getErrorManager()
Retrieves the ErrorManager for this Handler.java.util.logging.Filter
getFilter()
Get the currentFilter
for thisHandler
.java.util.logging.Formatter
getFormatter()
Return theFormatter
for thisHandler
.java.util.logging.Level
getLevel()
Get the log level specifying which messages will be logged by thisHandler
.java.util.Properties
getMailProperties()
Gets a copy of the mail properties used for the session.java.util.logging.Filter
getPushFilter()
Gets the push filter.java.util.logging.Level
getPushLevel()
Gets the push level.java.util.logging.Formatter
getSubject()
Gets the formatter used to create the subject line.boolean
isLoggable(java.util.logging.LogRecord record)
Check if thisHandler
would actually log a givenLogRecord
into its internal buffer.void
postConstruct()
A callback method for when this object is about to be placed into commission.void
preDestroy()
A callback method for when this object is about to be decommissioned.void
publish(java.util.logging.LogRecord record)
Stores aLogRecord
in the internal buffer.void
push()
Pushes any buffered records to the email server as high importance with urgent priority.protected void
reportError(java.lang.String msg, java.lang.Exception ex, int code)
Protected convenience method to report an error to this Handler's ErrorManager.void
setAttachmentFilters(java.util.logging.Filter... filters)
Sets the attachment filters.void
setAttachmentFormatters(java.util.logging.Formatter... formatters)
Sets the attachmentFormatter
object for this handler.void
setAttachmentNames(java.lang.String... names)
Sets the attachment file name for each attachment.void
setAttachmentNames(java.util.logging.Formatter... formatters)
Sets the attachment file name formatters.void
setAuthenticator(char... password)
Sets theAuthenticator
used to login to the email server.void
setAuthenticator(Authenticator auth)
Sets theAuthenticator
used to login to the email server.void
setComparator(java.util.Comparator<? super java.util.logging.LogRecord> c)
Sets the comparator used to order allLogRecord
objects prior to formatting.void
setEncoding(java.lang.String encoding)
Set the character encoding used by thisHandler
.void
setErrorManager(java.util.logging.ErrorManager em)
Define an ErrorManager for this Handler.void
setFilter(java.util.logging.Filter newFilter)
Set aFilter
to control output on thisHandler
.void
setFormatter(java.util.logging.Formatter newFormatter)
Set aFormatter
.void
setLevel(java.util.logging.Level newLevel)
Set the log level specifying which message levels will be logged by thisHandler
.void
setMailProperties(java.util.Properties props)
Sets the mail properties used for the session.void
setPushFilter(java.util.logging.Filter filter)
Sets the push filter.void
setPushLevel(java.util.logging.Level level)
Sets the push level.void
setSubject(java.lang.String subject)
Sets a literal string for the email subject.void
setSubject(java.util.logging.Formatter format)
Sets the subject formatter for email.
-
-
-
Constructor Detail
-
MailHandler
public MailHandler()
Creates aMailHandler
that is configured by theLogManager
configuration properties.- Throws:
java.lang.SecurityException
- if a security manager exists and the caller does not haveLoggingPermission("control")
.
-
MailHandler
public MailHandler(int capacity)
Creates aMailHandler
that is configured by theLogManager
configuration properties but overrides theLogManager
capacity with the given capacity.- Parameters:
capacity
- of the internal buffer.- Throws:
java.lang.IllegalArgumentException
- ifcapacity
less than one.java.lang.SecurityException
- if a security manager exists and the caller does not haveLoggingPermission("control")
.
-
MailHandler
public MailHandler(java.util.Properties props)
Creates a mail handler with the given mail properties. The key/value pairs are defined in theJava Mail API
documentation. ThisHandler
will also search theLogManager
for defaults if needed.- Parameters:
props
- a nonnull
properties object.- Throws:
java.lang.NullPointerException
- ifprops
isnull
.java.lang.SecurityException
- if a security manager exists and the caller does not haveLoggingPermission("control")
.
-
-
Method Detail
-
isLoggable
public boolean isLoggable(java.util.logging.LogRecord record)
Check if thisHandler
would actually log a givenLogRecord
into its internal buffer.This method checks if the
LogRecord
has an appropriate level and whether it satisfies anyFilter
including any attachment filters. However it does not check whether theLogRecord
would result in a "push" of the buffer contents.- Overrides:
isLoggable
in classjava.util.logging.Handler
- Parameters:
record
- aLogRecord
or null.- Returns:
- true if the
LogRecord
would be logged.
-
publish
public void publish(java.util.logging.LogRecord record)
Stores aLogRecord
in the internal buffer.The
isLoggable
method is called to check if the given log record is loggable. If the given record is loggable, it is copied into an internal buffer. Then the record's level property is compared with the push level. If the given level of theLogRecord
is greater than or equal to the push level then the push filter is called. If no push filter exists, the push filter returns true, or the capacity of the internal buffer has been reached then all buffered records are formatted into one email and sent to the server.- Specified by:
publish
in classjava.util.logging.Handler
- Parameters:
record
- description of the log event or null.
-
postConstruct
public void postConstruct()
A callback method for when this object is about to be placed into commission. This contract is defined by theorg.glassfish.hk2.api.PostConstruct
interface. If this class is loaded via a lifecycle managed environment other than HK2 then it is recommended that this method is called either directly or through extending this class to signal that this object is ready for use.- Since:
- JavaMail 1.5.3
-
preDestroy
public void preDestroy()
A callback method for when this object is about to be decommissioned. This contract is defined by theorg.glassfish.hk2.api.PreDestory
interface. If this class is loaded via a lifecycle managed environment other than HK2 then it is recommended that this method is called either directly or through extending this class to signal that this object will be destroyed.- Since:
- JavaMail 1.5.3
-
push
public void push()
Pushes any buffered records to the email server as high importance with urgent priority. The internal buffer is then cleared. Does nothing if called from inside a push.- See Also:
flush()
-
flush
public void flush()
Pushes any buffered records to the email server as normal priority. The internal buffer is then cleared. Does nothing if called from inside a push.- Specified by:
flush
in classjava.util.logging.Handler
- See Also:
push()
-
close
public void close()
Prevents any other records from being published. Pushes any buffered records to the email server as normal priority. The internal buffer is then cleared. Once this handler is closed it will remain closed.If this
Handler
is only implicitly closed by theLogManager
, then verification should be turned on.- Specified by:
close
in classjava.util.logging.Handler
- Throws:
java.lang.SecurityException
- if a security manager exists and the caller does not haveLoggingPermission("control")
.- See Also:
flush()
-
setLevel
public void setLevel(java.util.logging.Level newLevel)
Set the log level specifying which message levels will be logged by thisHandler
. Message levels lower than this value will be discarded.- Overrides:
setLevel
in classjava.util.logging.Handler
- Parameters:
newLevel
- the new value for the log level- Throws:
java.lang.NullPointerException
- ifnewLevel
isnull
.java.lang.SecurityException
- if a security manager exists and the caller does not haveLoggingPermission("control")
.
-
getLevel
public java.util.logging.Level getLevel()
Get the log level specifying which messages will be logged by thisHandler
. Message levels lower than this level will be discarded.- Overrides:
getLevel
in classjava.util.logging.Handler
- Returns:
- the level of messages being logged.
-
getErrorManager
public java.util.logging.ErrorManager getErrorManager()
Retrieves the ErrorManager for this Handler.- Overrides:
getErrorManager
in classjava.util.logging.Handler
- Returns:
- the ErrorManager for this Handler
- Throws:
java.lang.SecurityException
- if a security manager exists and if the caller does not haveLoggingPermission("control")
.
-
setErrorManager
public void setErrorManager(java.util.logging.ErrorManager em)
Define an ErrorManager for this Handler.The ErrorManager's "error" method will be invoked if any errors occur while using this Handler.
- Overrides:
setErrorManager
in classjava.util.logging.Handler
- Parameters:
em
- the new ErrorManager- Throws:
java.lang.SecurityException
- if a security manager exists and if the caller does not haveLoggingPermission("control")
.java.lang.NullPointerException
- if the given error manager is null.
-
getFilter
public java.util.logging.Filter getFilter()
Get the currentFilter
for thisHandler
.- Overrides:
getFilter
in classjava.util.logging.Handler
- Returns:
- a
Filter
object (may be null)
-
setFilter
public void setFilter(java.util.logging.Filter newFilter)
Set aFilter
to control output on thisHandler
.For each call of
publish
theHandler
will call thisFilter
(if it is non-null) to check if theLogRecord
should be published or discarded.- Overrides:
setFilter
in classjava.util.logging.Handler
- Parameters:
newFilter
- aFilter
object (may be null)- Throws:
java.lang.SecurityException
- if a security manager exists and if the caller does not haveLoggingPermission("control")
.
-
getEncoding
public java.lang.String getEncoding()
Return the character encoding for thisHandler
.- Overrides:
getEncoding
in classjava.util.logging.Handler
- Returns:
- The encoding name. May be null, which indicates the default encoding should be used.
-
setEncoding
public void setEncoding(java.lang.String encoding) throws java.io.UnsupportedEncodingException
Set the character encoding used by thisHandler
.The encoding should be set before any
LogRecords
are written to theHandler
.- Overrides:
setEncoding
in classjava.util.logging.Handler
- Parameters:
encoding
- The name of a supported character encoding. May be null, to indicate the default platform encoding.- Throws:
java.lang.SecurityException
- if a security manager exists and if the caller does not haveLoggingPermission("control")
.java.io.UnsupportedEncodingException
- if the named encoding is not supported.
-
getFormatter
public java.util.logging.Formatter getFormatter()
Return theFormatter
for thisHandler
.- Overrides:
getFormatter
in classjava.util.logging.Handler
- Returns:
- the
Formatter
(may be null).
-
setFormatter
public void setFormatter(java.util.logging.Formatter newFormatter) throws java.lang.SecurityException
Set aFormatter
. ThisFormatter
will be used to formatLogRecords
for thisHandler
.Some
Handlers
may not useFormatters
, in which case theFormatter
will be remembered, but not used.- Overrides:
setFormatter
in classjava.util.logging.Handler
- Parameters:
newFormatter
- theFormatter
to use (may not be null)- Throws:
java.lang.SecurityException
- if a security manager exists and if the caller does not haveLoggingPermission("control")
.java.lang.NullPointerException
- if the given formatter is null.
-
getPushLevel
public final java.util.logging.Level getPushLevel()
Gets the push level. The default isLevel.OFF
meaning that thisHandler
will only push when the internal buffer is full.- Returns:
- the push level.
-
setPushLevel
public final void setPushLevel(java.util.logging.Level level)
Sets the push level. This level is used to trigger a push so that all pending records are formatted and sent to the email server. When the push level triggers a send, the resulting email is flagged as high importance with urgent priority.- Parameters:
level
- Level object.- Throws:
java.lang.NullPointerException
- iflevel
isnull
.java.lang.SecurityException
- if a security manager exists and the caller does not haveLoggingPermission("control")
.java.lang.IllegalStateException
- if called from inside a push.
-
getPushFilter
public final java.util.logging.Filter getPushFilter()
Gets the push filter. The default isnull
.- Returns:
- the push filter or
null
.
-
setPushFilter
public final void setPushFilter(java.util.logging.Filter filter)
Sets the push filter. This filter is only called if the givenLogRecord
level was greater than the push level. If this filter returnstrue
, all pending records are formatted and sent to the email server. When the push filter triggers a send, the resulting email is flagged as high importance with urgent priority.- Parameters:
filter
- push filter ornull
- Throws:
java.lang.SecurityException
- if a security manager exists and the caller does not haveLoggingPermission("control")
.java.lang.IllegalStateException
- if called from inside a push.
-
getComparator
public final java.util.Comparator<? super java.util.logging.LogRecord> getComparator()
Gets the comparator used to order allLogRecord
objects prior to formatting. Ifnull
then the order is unspecified.- Returns:
- the
LogRecord
comparator.
-
setComparator
public final void setComparator(java.util.Comparator<? super java.util.logging.LogRecord> c)
Sets the comparator used to order allLogRecord
objects prior to formatting. Ifnull
then the order is unspecified.- Parameters:
c
- theLogRecord
comparator.- Throws:
java.lang.SecurityException
- if a security manager exists and the caller does not haveLoggingPermission("control")
.java.lang.IllegalStateException
- if called from inside a push.
-
getCapacity
public final int getCapacity()
Gets the number of log records the internal buffer can hold. When capacity is reached,Handler
will format allLogRecord
objects into one email message.- Returns:
- the capacity.
-
getAuthenticator
public final Authenticator getAuthenticator()
Gets theAuthenticator
used to login to the email server.- Returns:
- an
Authenticator
ornull
if none is required. - Throws:
java.lang.SecurityException
- if a security manager exists and the caller does not haveLoggingPermission("control")
.
-
setAuthenticator
public final void setAuthenticator(Authenticator auth)
Sets theAuthenticator
used to login to the email server.- Parameters:
auth
- anAuthenticator
object or null if none is required.- Throws:
java.lang.SecurityException
- if a security manager exists and the caller does not haveLoggingPermission("control")
.java.lang.IllegalStateException
- if called from inside a push.
-
setAuthenticator
public final void setAuthenticator(char... password)
Sets theAuthenticator
used to login to the email server.- Parameters:
password
- a password, empty array can be used to only supply a user name set bymail.user
property, or null if no credentials are required.- Throws:
java.lang.SecurityException
- if a security manager exists and the caller does not haveLoggingPermission("control")
.java.lang.IllegalStateException
- if called from inside a push.- Since:
- JavaMail 1.4.6
- See Also:
String.toCharArray()
-
setMailProperties
public final void setMailProperties(java.util.Properties props)
Sets the mail properties used for the session. The key/value pairs are defined in theJava Mail API
documentation. ThisHandler
will also search theLogManager
for defaults if needed.- Parameters:
props
- a nonnull
properties object.- Throws:
java.lang.SecurityException
- if a security manager exists and the caller does not haveLoggingPermission("control")
.java.lang.NullPointerException
- ifprops
isnull
.java.lang.IllegalStateException
- if called from inside a push.
-
getMailProperties
public final java.util.Properties getMailProperties()
Gets a copy of the mail properties used for the session.- Returns:
- a non null properties object.
- Throws:
java.lang.SecurityException
- if a security manager exists and the caller does not haveLoggingPermission("control")
.
-
getAttachmentFilters
public final java.util.logging.Filter[] getAttachmentFilters()
Gets the attachment filters. If the attachment filter does not allow anyLogRecord
to be formatted, the attachment may be omitted from the email.- Returns:
- a non null array of attachment filters.
-
setAttachmentFilters
public final void setAttachmentFilters(java.util.logging.Filter... filters)
Sets the attachment filters.- Parameters:
filters
- a nonnull
array of filters. Anull
index value is allowed. Anull
value means that all records are allowed for the attachment at that index.- Throws:
java.lang.SecurityException
- if a security manager exists and the caller does not haveLoggingPermission("control")
.java.lang.NullPointerException
- iffilters
isnull
java.lang.IndexOutOfBoundsException
- if the number of attachment name formatters do not match the number of attachment formatters.java.lang.IllegalStateException
- if called from inside a push.
-
getAttachmentFormatters
public final java.util.logging.Formatter[] getAttachmentFormatters()
Gets the attachment formatters. ThisHandler
is using attachments only if the returned array length is non zero.- Returns:
- a non
null
array of formatters.
-
setAttachmentFormatters
public final void setAttachmentFormatters(java.util.logging.Formatter... formatters)
Sets the attachmentFormatter
object for this handler. The number of formatters determines the number of attachments per email. This method should be the first attachment method called. To remove all attachments, call this method with empty array.- Parameters:
formatters
- a non null array of formatters.- Throws:
java.lang.SecurityException
- if a security manager exists and the caller does not haveLoggingPermission("control")
.java.lang.NullPointerException
- if the given array or any array index isnull
.java.lang.IllegalStateException
- if called from inside a push.
-
getAttachmentNames
public final java.util.logging.Formatter[] getAttachmentNames()
Gets the attachment name formatters. If the attachment names were set using explicit names then the names can be returned by callingtoString
on each attachment name formatter.- Returns:
- non
null
array of attachment name formatters.
-
setAttachmentNames
public final void setAttachmentNames(java.lang.String... names)
Sets the attachment file name for each attachment. All control characters are removed from the attachment names. This method will create a set of custom formatters.- Parameters:
names
- an array of names.- Throws:
java.lang.SecurityException
- if a security manager exists and the caller does not haveLoggingPermission("control")
.java.lang.IndexOutOfBoundsException
- if the number of attachment names do not match the number of attachment formatters.java.lang.IllegalArgumentException
- if any name is empty.java.lang.NullPointerException
- if any given array or name isnull
.java.lang.IllegalStateException
- if called from inside a push.- See Also:
Character.isISOControl(char)
,Character.isISOControl(int)
-
setAttachmentNames
public final void setAttachmentNames(java.util.logging.Formatter... formatters)
Sets the attachment file name formatters. The format method of each attachment formatter will see only theLogRecord
objects that passed its attachment filter during formatting. The format method will typically return an empty string. Instead of being used to format records, it is used to gather information about the contents of an attachment. ThegetTail
method should be used to construct the attachment file name and reset any formatter collected state. All control characters will be removed from the output of the formatter. ThetoString
method of the given formatter should be overridden to provide a useful attachment file name, if possible.- Parameters:
formatters
- and array of attachment name formatters.- Throws:
java.lang.SecurityException
- if a security manager exists and the caller does not haveLoggingPermission("control")
.java.lang.IndexOutOfBoundsException
- if the number of attachment name formatters do not match the number of attachment formatters.java.lang.NullPointerException
- if any given array or name isnull
.java.lang.IllegalStateException
- if called from inside a push.- See Also:
Character.isISOControl(char)
,Character.isISOControl(int)
-
getSubject
public final java.util.logging.Formatter getSubject()
Gets the formatter used to create the subject line. If the subject was created using a literal string then thetoString
method can be used to get the subject line.- Returns:
- the formatter.
-
setSubject
public final void setSubject(java.lang.String subject)
Sets a literal string for the email subject. All control characters are removed from the subject line.- Parameters:
subject
- a nonnull
string.- Throws:
java.lang.SecurityException
- if a security manager exists and the caller does not haveLoggingPermission("control")
.java.lang.NullPointerException
- ifsubject
isnull
.java.lang.IllegalStateException
- if called from inside a push.- See Also:
Character.isISOControl(char)
,Character.isISOControl(int)
-
setSubject
public final void setSubject(java.util.logging.Formatter format)
Sets the subject formatter for email. The format method of the subject formatter will see allLogRecord
objects that were published to thisHandler
during formatting and will typically return an empty string. This formatter is used to gather information to create a summary about what information is contained in the email. ThegetTail
method should be used to construct the subject and reset any formatter collected state. All control characters will be removed from the formatter output. ThetoString
method of the given formatter should be overridden to provide a useful subject, if possible.- Parameters:
format
- the subject formatter.- Throws:
java.lang.SecurityException
- if a security manager exists and the caller does not haveLoggingPermission("control")
.java.lang.NullPointerException
- ifformat
isnull
.java.lang.IllegalStateException
- if called from inside a push.- See Also:
Character.isISOControl(char)
,Character.isISOControl(int)
-
reportError
protected void reportError(java.lang.String msg, java.lang.Exception ex, int code)
Protected convenience method to report an error to this Handler's ErrorManager. This method will prefix all non null error messages withLevel.SEVERE.getName()
. This allows the receiving error manager to determine if themsg
parameter is a simple error message or a raw email message.- Overrides:
reportError
in classjava.util.logging.Handler
- Parameters:
msg
- a descriptive string (may be null)ex
- an exception (may be null)code
- an error code defined in ErrorManager
-
-