de.aristaflow.adept2.core.eventmanager.mailevents

Class MailTools

java.lang.Object

de.aristaflow.adept2.core.eventmanager.mailevents.MailTools

public class MailTools
extends java.lang.Object

Various tool methods for processing mails and handling mail events. For instance it provides methods for converting mail addresses to UDT values (either as list or subtable) and attachments to files and afterwards to a UDT value (either as file UDT, list of URI or subtable with file information.
Note that handling files requires the ability to create files. For this purpose a file store directory can be provided. This needs to be writable by this class. If no directory is configured, all files will be created as temporary files which has two consequences: The files will be deleted as soon as the JVM exits and since the file names are derived from the mail subject, there may be file name collisions in the temporary directory.

Author:

Ulrich Kreher

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	CONF_FILE_STORE_PATH Configuration key for the path to store files to.
static java.lang.String	CONF_IS_CRITICAL Configuration key: Whether the event handler is critical and problems handling the event should abort all handling of the current event.
static int	MAX_FILE_NAME_LENGTH The maximum length of the file name for a mail event.
static java.lang.String	PARAM_ATTACHMENTS Process parameter name for the list of attachments.
static java.lang.String	PARAM_BCC Process parameter name for the message's recipient list.
static java.lang.String	PARAM_BODY Process parameter name for the message's body.
static java.lang.String	PARAM_CC Process parameter name for the message's recipient list.
static java.lang.String	PARAM_FROM Process parameter name for the message's sender list.
static java.lang.String	PARAM_MESSAGE Process parameter name for the message.
static java.lang.String	PARAM_SENT_DATE Process parameter name for the message's sent date.
static java.lang.String	PARAM_SUBJECT Process parameter name for the message's subject.
static java.lang.String	PARAM_TO Process parameter name for the message's recipient list.
protected static java.lang.String	STRING_LIST_TYPE The name of the UDT type for String lists.
static java.lang.String	SUBTABLE_NAME_MAIL_ADDRESSES The name of the subtable that is created for mail addresses.
protected static java.lang.String	URI_LIST_TYPE The name of the UDT type for URI lists.

Constructor Summary

Constructors

Constructor and Description
MailTools()

Method Summary

Modifier and Type	Method and Description
protected static UDTValue	addressListToUDT(Parameter parameter, javax.mail.Address[] addresses, java.util.logging.Logger logger) Creates a UDT value for the designated parameter with the designated addresses.
protected static UDTValue	attachmentsToUDT(Parameter parameter, MailEvent event, java.io.File fileStore, java.util.logging.Logger logger) Creates a UDT value for the designated parameter with all attachments of the message of the designated mail event.
protected static java.lang.String	createFileNameForEvent(MailEvent event, boolean unique) Creates a file name for storing a message.
protected static UDTValue	getMessageAsFileUDT(MailEvent event, java.io.File fileStore, java.util.logging.Logger logger) Creates a file for the designated event and returns it as UDTValue.
static java.lang.String	getStringContentOfMessage(javax.mail.Message message) Gets a string representation of the content of the designated message.
static java.lang.String[]	toString(javax.mail.Address[] addresses) Converts Addresses to Strings.
static java.lang.String	toString(javax.mail.Message message, java.util.logging.Logger logger) Provides a string representing the designated message, that is the subject, the sender and the receiver of the message.
protected static java.io.File	writeMessageToFile(MailEvent event, boolean intermediate, java.io.File fileStore, java.util.logging.Logger logger) Writes the mail from the designated mail event to a file with an appropriate file name.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

STRING_LIST_TYPE

protected static final java.lang.String STRING_LIST_TYPE

The name of the UDT type for String lists.

URI_LIST_TYPE

protected static final java.lang.String URI_LIST_TYPE

The name of the UDT type for URI lists.

MAX_FILE_NAME_LENGTH

public static final int MAX_FILE_NAME_LENGTH

The maximum length of the file name for a mail event. This restriction is required since file systems usually only support 255 characters for a file name.

See Also:

Constant Field Values

PARAM_MESSAGE

public static final java.lang.String PARAM_MESSAGE

Process parameter name for the message.

See Also:

Constant Field Values

PARAM_ATTACHMENTS

public static final java.lang.String PARAM_ATTACHMENTS

Process parameter name for the list of attachments.

See Also:

Constant Field Values

PARAM_BODY

public static final java.lang.String PARAM_BODY

Process parameter name for the message's body.

See Also:

Constant Field Values

PARAM_TO

public static final java.lang.String PARAM_TO

Process parameter name for the message's recipient list.

See Also:

Constant Field Values

PARAM_CC

public static final java.lang.String PARAM_CC

Process parameter name for the message's recipient list.

See Also:

Constant Field Values

PARAM_BCC

public static final java.lang.String PARAM_BCC

Process parameter name for the message's recipient list.

See Also:

Constant Field Values

PARAM_FROM

public static final java.lang.String PARAM_FROM

Process parameter name for the message's sender list.

See Also:

Constant Field Values

PARAM_SENT_DATE

public static final java.lang.String PARAM_SENT_DATE

Process parameter name for the message's sent date.

See Also:

Constant Field Values

PARAM_SUBJECT

public static final java.lang.String PARAM_SUBJECT

Process parameter name for the message's subject.

See Also:

Constant Field Values

SUBTABLE_NAME_MAIL_ADDRESSES

public static final java.lang.String SUBTABLE_NAME_MAIL_ADDRESSES

The name of the subtable that is created for mail addresses.

See Also:

Constant Field Values

CONF_IS_CRITICAL

public static final java.lang.String CONF_IS_CRITICAL

Configuration key: Whether the event handler is critical and problems handling the event should abort all handling of the current event.

See Also:

Constant Field Values

CONF_FILE_STORE_PATH

public static final java.lang.String CONF_FILE_STORE_PATH

Configuration key for the path to store files to.

See Also:

Constant Field Values

Constructor Detail

MailTools

public MailTools()

Method Detail

toString

public static java.lang.String[] toString(javax.mail.Address[] addresses)

Converts Addresses to Strings.

Parameters:

addresses - The addresses to convert.

Returns:

The converted addresses or an empty array in case there are no addresses.

toString

public static java.lang.String toString(javax.mail.Message message,
                                        java.util.logging.Logger logger)

Provides a string representing the designated message, that is the subject, the sender and the receiver of the message.

Parameters:

message - The message for which to get a string representation.

logger - The logger for additional information in case the details of the message cannot be retrieved.

Returns:

A string representation for the designated message containing the subject, the sender and the receiver.

getStringContentOfMessage

public static java.lang.String getStringContentOfMessage(javax.mail.Message message)
                                                  throws javax.mail.MessagingException,
                                                         java.io.IOException

Gets a string representation of the content of the designated message. If no string content is found, an appropriate error string is returned.

Parameters:

message - The message to retrieve the string content of.

Returns:

A string representation for the content.

Throws:

javax.mail.MessagingException - If there are problems retrieving the message content, a MessagingException will be thrown.

java.io.IOException - If there are problems retrieving the body part content, an IOException will be thrown.

addressListToUDT

protected static UDTValue addressListToUDT(Parameter parameter,
                                           javax.mail.Address[] addresses,
                                           java.util.logging.Logger logger)
                                    throws java.io.IOException,
                                           InvalidDataTypeException

Creates a UDT value for the designated parameter with the designated addresses. These are either a java.util.List<STRING> or a subtable.

Parameters:

parameter - The parameter for which to create a UDT value.

addresses - The addresses for which to retrieve a UDT value.

logger - The logger for log messages.

Returns:

A UDT value for the designated parameter containing the designated addresses.

Throws:

java.io.IOException - If there are problems serialising the list or the subtable or creating the subtable-XML, an IOException will be thrown.

InvalidDataTypeException - If the UDT name of the parameter is unknown or there are problems creating an XML-document for the subtable, an InvalidDataTypeException will be thrown.

getMessageAsFileUDT

protected static UDTValue getMessageAsFileUDT(MailEvent event,
                                              java.io.File fileStore,
                                              java.util.logging.Logger logger)
                                       throws javax.mail.MessagingException,
                                              java.io.IOException

Creates a file for the designated event and returns it as UDTValue. The file will be deleted after the UDTValue has been created.

Parameters:

event - The mail event of which to retrieve the message as file in an UDTValue.

fileStore - The directory for storing attachments. If this is null, temporary files will be used for the attachments.

logger - The logger for log messages.

Returns:

The message of the designated mail event as file in an UDTValue.

Throws:

javax.mail.MessagingException - If writing the mail to the file fails, a MessagingException will be thrown.

java.io.IOException - If creating the file or writing to the file fails, an IOException will be thrown.

writeMessageToFile

protected static java.io.File writeMessageToFile(MailEvent event,
                                                 boolean intermediate,
                                                 java.io.File fileStore,
                                                 java.util.logging.Logger logger)
                                          throws javax.mail.MessagingException,
                                                 java.io.IOException

Writes the mail from the designated mail event to a file with an appropriate file name. The file name will be similar to the mail subject. If the file is not intermediate, its name will be prepended by a random UUID. The complete file name will be a UUID if the file cannot be created with the subject as file name.
If a file store is configured, it will be used, otherwise all files will be created as temporary files.

Parameters:

event - The mail event of which to write the message to a file.

intermediate - Whether the file is just for intermediate purpose and thus the file name does not need to be unique for a longer time.

fileStore - The directory for storing attachments. If this is null, temporary files will be used for the attachments.

logger - The logger for log messages.

Returns:

The file containing the mail of the designated event.

Throws:

javax.mail.MessagingException - If writing the mail to the file fails, a MessagingException will be thrown.

java.io.IOException - If creating the file or writing to the file fails, an IOException will be thrown.

createFileNameForEvent

protected static java.lang.String createFileNameForEvent(MailEvent event,
                                                         boolean unique)

Creates a file name for storing a message. Tries to uses the subject of the message after replacing some chars which may not be supported by all file systems. If you like to use a file extension like .eml, you need to add it manually. The length of the name is restricted (MAX_FILE_NAME_LENGTH).

Parameters:

event - The mail event to create the file name for.

unique - Whether the created file name should be unique to allow for storing several mails in the same directory.

Returns:

The file name w/o extension for storing the given message.

attachmentsToUDT

protected static UDTValue attachmentsToUDT(Parameter parameter,
                                           MailEvent event,
                                           java.io.File fileStore,
                                           java.util.logging.Logger logger)
                                    throws javax.mail.MessagingException,
                                           java.io.IOException,
                                           InvalidUDTException

Creates a UDT value for the designated parameter with all attachments of the message of the designated mail event. The attachments are stored locally either in the configured file store or as temporary files. These files are then either added to a java.util.List<URI> or a subtable, depending on the UDT of the designated parameter.
Note that not configuring a file store and thus using temporary files may lead to problems when storing the attachments since the file names may not be unique and thus storing the attachments may fail.

Parameters:

parameter - The parameter for which to create a UDT value.

event - The mail event of which to store all attachments of the message.

fileStore - The directory for storing attachments. If this is null, temporary files will be used for the attachments.

logger - The logger for log messages.

Returns:

A UDT value for the designated parameter containing the file date of the attachments of the message of the designated mail event.

Throws:

javax.mail.MessagingException - If there are problems retrieving the message content/attachments or file data, a MessagingException will be thrown.

java.io.IOException - If there are problems serialising the list or the subtable or creating the subtable-XML or if the directory below the configured file store cannot be created, an IOException will be thrown.

InvalidUDTException - If the UDT name of the parameter is unknown, there are problems creating an XML-document for the subtable or the directory below the configured file store cannot be created, an InvalidUDTException will be thrown.