Package de.aristaflow.adept2.core.eventmanager.mailevents

Class MailTools

java.lang.Object

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

public class MailTools
extends 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.

Field Summary

Fields

Modifier and Type	Field	Description
static String	CONF_FILE_STORE_PATH	Configuration key for the path to store files to.
static 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 String	PARAM_ATTACHMENTS	Process parameter name for the list of attachments.
static String	PARAM_BCC	Process parameter name for the message's recipient list.
static String	PARAM_BODY	Process parameter name for the message's body.
static String	PARAM_CC	Process parameter name for the message's recipient list.
static String	PARAM_FROM	Process parameter name for the message's sender list.
static String	PARAM_MESSAGE	Process parameter name for the message.
static String	PARAM_SENT_DATE	Process parameter name for the message's sent date.
static String	PARAM_SUBJECT	Process parameter name for the message's subject.
static String	PARAM_TO	Process parameter name for the message's recipient list.
protected static String	STRING_LIST_TYPE	The name of the UDT type for String lists.
static String	SUBTABLE_NAME_MAIL_ADDRESSES	The name of the subtable that is created for mail addresses.
protected static String	URI_LIST_TYPE	The name of the UDT type for URI lists.

Constructor Summary

Constructors

Constructor	Description
MailTools()

Method Summary

Modifier and Type	Method	Description
protected static UDTValue	addressListToUDT(Parameter parameter, javax.mail.Address[] addresses, Logger logger)	Creates a UDT value for the designated parameter with the designated addresses.
protected static UDTValue	attachmentsToUDT(Parameter parameter, MailEvent event, File fileStore, Logger logger)	Creates a UDT value for the designated parameter with all attachments of the message of the designated mail event.
protected static String	createFileNameForEvent(MailEvent event, boolean unique)	Creates a file name for storing a message.
protected static UDTValue	getMessageAsFileUDT(MailEvent event, File fileStore, Logger logger)	Creates a file for the designated event and returns it as UDTValue.
static String	getStringContentOfMessage(javax.mail.Message message)	Deprecated, for removal: This API element is subject to removal in a future version. Use getStringContentOfMessage(Message, Logger) instead.
static String	getStringContentOfMessage(javax.mail.Message message, Logger logger)	Gets a string representation of the content of the designated message.
static UDTValue	getUdtValue(MailEvent event, String udtName, File fileStore, Logger logger)	Gets the UDT value with the designated type name for the designated file.
static String[]	toString(javax.mail.Address[] addresses, Logger logger)	Gets Strings of the designated Addresses using either InternetAddress.toUnicodeString() or MimeUtility.decodeText and toString().
static String	toString(javax.mail.Message message, Logger logger)	Provides a string representing the designated message, that is the subject, the sender and the receiver of the message.
protected static File	writeMessageToFile(MailEvent event, boolean intermediate, File fileStore, 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 String STRING_LIST_TYPE

The name of the UDT type for String lists.

URI_LIST_TYPE

protected static final 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 String PARAM_MESSAGE

Process parameter name for the message.

See Also:

Constant Field Values

PARAM_ATTACHMENTS

public static final String PARAM_ATTACHMENTS

Process parameter name for the list of attachments.

See Also:

Constant Field Values

PARAM_BODY

public static final String PARAM_BODY

Process parameter name for the message's body.

See Also:

Constant Field Values

PARAM_TO

public static final String PARAM_TO

Process parameter name for the message's recipient list.

See Also:

Constant Field Values

PARAM_CC

public static final String PARAM_CC

Process parameter name for the message's recipient list.

See Also:

Constant Field Values

PARAM_BCC

public static final String PARAM_BCC

Process parameter name for the message's recipient list.

See Also:

Constant Field Values

PARAM_FROM

public static final String PARAM_FROM

Process parameter name for the message's sender list.

See Also:

Constant Field Values

PARAM_SENT_DATE

public static final String PARAM_SENT_DATE

Process parameter name for the message's sent date.

See Also:

Constant Field Values

PARAM_SUBJECT

public static final String PARAM_SUBJECT

Process parameter name for the message's subject.

See Also:

Constant Field Values

SUBTABLE_NAME_MAIL_ADDRESSES

public static final 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 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 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 String[] toString(javax.mail.Address[] addresses,
                                Logger logger)

Gets Strings of the designated Addresses using either InternetAddress.toUnicodeString() or MimeUtility.decodeText and toString(). If the encoding is not supported, the address will be used encoded.

Parameters:

addresses - The addresses to convert.

logger - The logger in case the encoding is not supported.

Returns:

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

toString

public static String toString(javax.mail.Message message,
                              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

@Deprecated(since="14.4.0",
            forRemoval=true)
public static String getStringContentOfMessage(javax.mail.Message message)
                                        throws javax.mail.MessagingException,
                                               IOException

Deprecated, for removal: This API element is subject to removal in a future version.

Use getStringContentOfMessage(Message, Logger) instead.

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.

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

getStringContentOfMessage

public static String getStringContentOfMessage(javax.mail.Message message,
                                               Logger logger)
                                        throws javax.mail.MessagingException,
                                               IOException

Gets a string representation of the content of the designated message. If no string content is found, null will be returned with a corresponding info message in the designated logger.

Parameters:

message - The message to retrieve the string content of.

logger - The logger for log messages.

Returns:

A string representation for the content or null.

Throws:

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

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,
                                           Logger logger)
                                    throws 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. The caller is responsible for closing.

Throws:

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.

getUdtValue

public static UDTValue getUdtValue(MailEvent event,
                                   String udtName,
                                   File fileStore,
                                   Logger logger)
                            throws javax.mail.MessagingException,
                                   IOException

Gets the UDT value with the designated type name for the designated file.

Parameters:

event - The mail event for which to retrieve an UDT value containing the message as file.

udtName - The type name of the UDT.

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 UDT value of the designated type name for the designated file. The caller is responsible for closing.

Throws:

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

IOException - If there are problems creating the file, writing to the file, or creating the FileUDT or UDTValue from message of the event fails, an IOException will be thrown.

getMessageAsFileUDT

protected static UDTValue getMessageAsFileUDT(MailEvent event,
                                              File fileStore,
                                              Logger logger)
                                       throws javax.mail.MessagingException,
                                              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. The caller is responsible for closing.

Throws:

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

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

writeMessageToFile

protected static File writeMessageToFile(MailEvent event,
                                         boolean intermediate,
                                         File fileStore,
                                         Logger logger)
                                  throws javax.mail.MessagingException,
                                         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.

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

createFileNameForEvent

protected static String createFileNameForEvent(MailEvent event,
                                               boolean unique)

Creates a file name for storing a message. Tries to use 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,
                                           File fileStore,
                                           Logger logger)
                                    throws javax.mail.MessagingException,
                                           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. The caller is responsible for closing.

Throws:

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

IOException - If there are problems serialising the list or the subtable or creating the subtable-XML or if the file name cannot be decoded 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.