ch.astorm.jotlmsg

Class OutlookMessage

java.lang.Object

ch.astorm.jotlmsg.OutlookMessage

public class OutlookMessage
extends Object

Represents an Outlook message.

This class is meant to be a very simple and easy-to-use API to read and create .msg files for Microsoft Outlook. It is also compatible with the standard javax.mail package, by the usage of the toMimeMessage() method.

This implementation is capable of generating .msg files that can be open by Microsoft Outlook, so it behaves like if the user has created a new email. However it's purpose is not to make a full-integration of Microsoft Outlook with all the features it has (such as calendars, appointments, tasks, ...). Those features may be covered in future developments.

The Microsoft specification MS-OXCMSG can be found in the ms-specifications folder of jotlmsg, or can be downloaded here. The detailed list of properties MS-OXPROPS is also available in the ms-specifications folder or here.

Author:

Cedric Tabin

Field Summary

Fields

Modifier and Type	Field and Description
static String	MIME_DATE_FORMAT Format of a MIME date that can be used as pattern in a SimpleDateFormat.

Constructor Summary

Constructors

Constructor and Description
OutlookMessage() Creates a new empty message.
OutlookMessage(File mapiMessageFile) Creates a new message with the data of the specified mapiMessageFile.
OutlookMessage(InputStream mapiMessageInputStream) Creates a new message with the data of the specified mapiMessageInputStream.
OutlookMessage(org.apache.poi.hsmf.MAPIMessage mapiMessage) Creates a new message with the data of the specified mapiMessage.

Method Summary

Modifier and Type	Method and Description
void	addAttachment(OutlookMessageAttachment attachment) Add a new attachment to this message.
OutlookMessageAttachment	addAttachment(String name, String mimeType, InputStream input) Add a new attachment to this message.
OutlookMessageAttachment	addAttachment(String name, String mimeType, OutlookMessageAttachment.InputStreamCreator inputStreamCreator) Add a new attachment to this message.
OutlookMessageRecipient	addRecipient(OutlookMessageRecipient.Type type, String email) Creates and add a new OutlookMessageRecipient to this message.
OutlookMessageRecipient	addRecipient(OutlookMessageRecipient.Type type, String email, String name) Creates and add a new OutlookMessageRecipient to this message.
void	addRecipient(OutlookMessageRecipient recipient) Add the specified recipient to this message.
static String	extractEmail(String mixedMailStr) Extracts the mail from a mixed mail string, for instance "John Doe <john.doe@hotmail.com>".
List<OutlookMessageRecipient>	getAllRecipients() Returns all the recipients of this message.
List<OutlookMessageAttachment>	getAttachments() Returns the attachments of this message.
String	getFrom() Defines the From email address from which a message has been sent.
String	getPlainTextBody() Defines the plain text body of the message.
List<OutlookMessageRecipient>	getRecipients(OutlookMessageRecipient.Type type) Returns all the recipients of the specified type.
List<String>	getReplyTo() Defines the addresses use when the user hits the 'reply' button.
Date	getSentDate() Defines the sent date of the message.
String	getSubject() Defines the subject of the message.
void	removeAllAttachments() Removes all the attachments from this message.
void	removeAllRecipients() Removes all the recipients.
void	removeAllRecipients(OutlookMessageRecipient.Type type) Removes all the recipients of the given type.
void	removeAttachment(OutlookMessageAttachment attachment) Removes the specified attachment from this message.
void	removeRecipient(OutlookMessageRecipient recipient) Removes the specified recipient from this message.
void	setFrom(String from)
void	setPlainTextBody(String plainTextBody)
void	setReplyTo(List<String> replyTo)
void	setSentDate(Date d)
void	setSubject(String subject)
javax.mail.internet.MimeMessage	toMimeMessage() Creates a new MimeMessage from this OutlookMessage.
javax.mail.internet.MimeMessage	toMimeMessage(Properties sessionProps) Creates a new MimeMessage from this OutlookMessage.
javax.mail.internet.MimeMessage	toMimeMessage(javax.mail.Session session) Creates a new MimeMessage from this OutlookMessage.
void	writeTo(File file) Writes the content of this message to the specified file.
void	writeTo(OutputStream outputStream) Writes the content of this message to the specified outputStream.

Methods inherited from class java.lang.Object

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

Field Detail

MIME_DATE_FORMAT

public static final String MIME_DATE_FORMAT

Format of a MIME date that can be used as pattern in a SimpleDateFormat.

See Also:

Constant Field Values

Constructor Detail

OutlookMessage

public OutlookMessage()

Creates a new empty message.

OutlookMessage

public OutlookMessage(InputStream mapiMessageInputStream)
               throws IOException

Creates a new message with the data of the specified mapiMessageInputStream.

Parameters:

mapiMessageInputStream - The source message data.

Throws:

IOException - If an I/O error occurs.

OutlookMessage

public OutlookMessage(File mapiMessageFile)
               throws IOException

Creates a new message with the data of the specified mapiMessageFile.

Parameters:

mapiMessageFile - The source message data.

Throws:

IOException - If an I/O error occurs.

OutlookMessage

public OutlookMessage(org.apache.poi.hsmf.MAPIMessage mapiMessage)

Creates a new message with the data of the specified mapiMessage. All the data will be copied from the source message and the latter can be then discarded.

Parameters:

mapiMessage - The source message data.

Method Detail

getSubject

public String getSubject()

Defines the subject of the message. This value may be null.

setSubject

public void setSubject(String subject)

getPlainTextBody

public String getPlainTextBody()

Defines the plain text body of the message. Currently, there is no way to define a formatted message (HTML/RTF) for technical reasons (RTF compression and PidTagBodyHtml not supported by Outlook). This value may be null.

setPlainTextBody

public void setPlainTextBody(String plainTextBody)

getFrom

public String getFrom()

Defines the From email address from which a message has been sent. This value may be null.

setFrom

public void setFrom(String from)

getReplyTo

public List<String> getReplyTo()

Defines the addresses use when the user hits the 'reply' button. Currently, this value is only used to create a MimeMessage but isn't used for .msg generation. This value may be null.

See Also:

toMimeMessage()

setReplyTo

public void setReplyTo(List<String> replyTo)

getSentDate

public Date getSentDate()

Defines the sent date of the message. If this value is not defined, then it means the message is considered as unsent.

However, it is possible that this value is set when reading a message that was created by Outlook and may then contains its creation date.

setSentDate

public void setSentDate(Date d)

getRecipients

public List<OutlookMessageRecipient> getRecipients(OutlookMessageRecipient.Type type)

Returns all the recipients of the specified type. If there is none, then an empty list will be returned.

Parameters:

type - The recipients type.

Returns:

An immutable list with all the recipients of the given type.

getAllRecipients

public List<OutlookMessageRecipient> getAllRecipients()

Returns all the recipients of this message. If there is no recipient, an empty list will be returned.

Returns:

A new list with all the recipients.

addRecipient

public OutlookMessageRecipient addRecipient(OutlookMessageRecipient.Type type,
                                            String email)

Creates and add a new OutlookMessageRecipient to this message.

Parameters:

type - The type.

email - The email.

Returns:

The created recipient.

addRecipient

public OutlookMessageRecipient addRecipient(OutlookMessageRecipient.Type type,
                                            String email,
                                            String name)

Creates and add a new OutlookMessageRecipient to this message.

Parameters:

type - The type.

email - The email.

name - The name or null.

Returns:

The created recipient.

addRecipient

public void addRecipient(OutlookMessageRecipient recipient)

Add the specified recipient to this message.

Parameters:

recipient - The recipient to add.

removeRecipient

public void removeRecipient(OutlookMessageRecipient recipient)

Removes the specified recipient from this message.

Parameters:

recipient - The recipient to remove.

removeAllRecipients

public void removeAllRecipients(OutlookMessageRecipient.Type type)

Removes all the recipients of the given type.

Parameters:

type - The type of recipients to remove.

removeAllRecipients

public void removeAllRecipients()

Removes all the recipients.

getAttachments

public List<OutlookMessageAttachment> getAttachments()

Returns the attachments of this message. This list can be directly modified.

Returns:

The attachments.

addAttachment

public OutlookMessageAttachment addAttachment(String name,
                                              String mimeType,
                                              InputStream input)

Add a new attachment to this message.

The data of the InputStream will be loaded into memory (see OutlookMessageAttachment.MemoryInputStreamCreator). If you don't expect to invoke writeTo() or toMimeMessage() multiple times, then consider using the other method, which uses a OutlookMessageAttachment.InputStreamCreator.

The MIME type must be set accordingly to the input.

Parameters:

name - The name.

mimeType - The MIME type.

input - The input data.

Returns:

The created attachment.

addAttachment

public OutlookMessageAttachment addAttachment(String name,
                                              String mimeType,
                                              OutlookMessageAttachment.InputStreamCreator inputStreamCreator)

Add a new attachment to this message. The InputStreamCreator can be set to the attachment later.

To use this method with a single-usage InputStream:

message.addAttachment("myAttachment", "text/plain", a -> myInputStream);

The MIME type must be set accordingly to the input.

Parameters:

name - The name.

mimeType - The MIME type.

inputStreamCreator - The InputStream creator or null.

Returns:

The created attachment.

addAttachment

public void addAttachment(OutlookMessageAttachment attachment)

Add a new attachment to this message.

Parameters:

attachment - The attachment.

removeAttachment

public void removeAttachment(OutlookMessageAttachment attachment)

Removes the specified attachment from this message.

Parameters:

attachment - The attachment to remove.

removeAllAttachments

public void removeAllAttachments()

Removes all the attachments from this message.

toMimeMessage

public javax.mail.internet.MimeMessage toMimeMessage()
                                              throws IOException,
                                                     javax.mail.MessagingException

Creates a new MimeMessage from this OutlookMessage. A new Session will be created with an empty Properties instance.

Returns:

A new MimeMessage instance.

Throws:

IOException

javax.mail.MessagingException

See Also:

toMimeMessage(java.util.Properties)

toMimeMessage

public javax.mail.internet.MimeMessage toMimeMessage(Properties sessionProps)
                                              throws IOException,
                                                     javax.mail.MessagingException

Creates a new MimeMessage from this OutlookMessage. A new Session will be created with the specified sessionProps.

Parameters:

sessionProps - The Session properties.

Returns:

A new MimeMessage instance.

Throws:

IOException

javax.mail.MessagingException

See Also:

toMimeMessage(javax.mail.Session)

toMimeMessage

public javax.mail.internet.MimeMessage toMimeMessage(javax.mail.Session session)
                                              throws IOException,
                                                     javax.mail.MessagingException

Creates a new MimeMessage from this OutlookMessage. This method will generate a multipart/mixed MimeMessage, with the first part being the message body (named 'body').

Parameters:

session - The Session to use for message creation.

Returns:

A new MimeMessage instance.

Throws:

IOException

javax.mail.MessagingException

extractEmail

public static String extractEmail(String mixedMailStr)

Extracts the mail from a mixed mail string, for instance "John Doe <john.doe@hotmail.com>".

This method uses a simple pattern to get the first string which looks like an email, eg there is an @ with at least one char on each side. Spaces are considered as separators.

If there are multiple mails in mixedMailStr, only the first one will be returned.

This method does not check at all if the returned mail is valid.

Parameters:

mixedMailStr - A string that contains (potentially) an email address.

Returns:

The first string looking like an email or null.

writeTo

public void writeTo(File file)
             throws IOException

Writes the content of this message to the specified file. The created file will be in format .msg that can be open by Microsoft Outlook.

Parameters:

file - The .msg file to create.

Throws:

IOException - If an I/O error occurs.

writeTo

public void writeTo(OutputStream outputStream)
             throws IOException

Writes the content of this message to the specified outputStream. The bytes written represent a .msg file that can be open by Microsoft Outlook. The outputStream will remain open.

Parameters:

outputStream - The stream to write to.

Throws:

IOException - If an I/O error occurs.