org.xmlBlaster.util.protocol.email
Class EmailData

java.lang.Object
  org.xmlBlaster.util.protocol.email.EmailData

public class EmailData
extends java.lang.Object

Value object holding the most commonly used email fields.

Add/access/delete attachments is not simultaneous possible (not thread save)

Example:

From:    demo@localhost
To:      xmlBlaster@localhost
Subject: Hello World
attachement {
   fileName: messageId.mid
   content:  abcd5
}
attachement {
   fileName: xmlBlaster.xbf
   content:  [the binary xmlBlaster format similar to that used with SOCKET]
}
 

Note on max. header length from RFC 2822:

"There are two limits that this standard places on the number of characters in a line. Each line of characters MUST be no more than 998 characters, and SHOULD be no more than 78 characters, excluding the CRLF."

Author:

Marcel Ruff

See Also:

http://www.faqs.org/rfcs/rfc2822.html

Field Summary

protected java.util.ArrayList	attachments Containts AttachmentHolder instances
protected javax.mail.internet.InternetAddress[]	bcc
protected javax.mail.internet.InternetAddress[]	cc
protected java.lang.String	content
protected java.lang.String	encoding
static java.lang.String	EXPIRES_HEADER_RFC2156 Expiry Date Indication Supported as new RFC 822 header (Expires:).
static java.lang.String	EXPIRES_TAG
protected java.sql.Timestamp	expiryTime
protected javax.mail.internet.InternetAddress	from
private static java.util.logging.Logger	log
static java.lang.String	MESSAGEID_EXTENSION Holding the relevant email meta info like a request identifier
static java.lang.String	MESSAGEID_TAG The root tag <messageId>
private java.lang.String	messageIdFileName
static java.lang.String	METHODNAME_TAG
protected javax.mail.internet.InternetAddress[]	recipients
protected javax.mail.internet.InternetAddress[]	replyTo
protected java.lang.String	requestId Contains requestId *
static java.lang.String	REQUESTID_TAG
protected boolean	requestIdFromSentDate Remember if we got an explicit requestId or if we extracted it from the sentDate
boolean	sendAsync
protected boolean	sendContentAsText
protected java.util.Date	sentDate The origination date from the email header, this field exists always for incoming emails
protected java.lang.String	sessionId Contains sessionId *
static java.lang.String	SESSIONID_TAG
protected java.lang.String	subject

Constructor Summary

EmailData(javax.mail.internet.InternetAddress recipient, javax.mail.internet.InternetAddress from, java.lang.String subject)

EmailData(java.lang.String[] recipients, java.lang.String from, java.lang.String subject, java.lang.String content)
Create a simple message for any number of recipients.

EmailData(java.lang.String recipient, java.lang.String from, java.lang.String subject, java.lang.String content)
Create a simple message.

Method Summary

void	addAttachment(AttachmentHolder attachmentHolder)
java.lang.String	createMessageId(MethodName methodName, java.sql.Timestamp expiryTimestamp) Use together with extractMessageId(EmailData messageData, String tag).
static java.lang.String	createMessageId(java.lang.String sessionId, java.lang.String requestId, MethodName methodName, java.sql.Timestamp expiryTimestamp) If any of the params is null no markup for this param is added.
java.lang.String	extractMessageId(java.lang.String tag, java.lang.String msgIdFileName) Find the given tag in the messageId of this message.
java.lang.String[]	getAllRecipients()
AttachmentHolder	getAttachment(java.lang.String fileName)
AttachmentHolder[]	getAttachments() Access all attachements.
javax.mail.internet.InternetAddress[]	getBcc()
javax.mail.internet.InternetAddress[]	getCc()
java.lang.String	getContent()
byte[]	getContentByExtension(java.lang.String extension) Lookup attachment.
java.lang.String	getEncoding() Encoding (charset) for example "UTF-8".
java.sql.Timestamp	getExpiryTime() Is transported in the email header "Expires: "
java.lang.String	getFileNameList() Comma separated value list of all attachment file names (unquoted) for logging.
java.lang.String	getFrom()
javax.mail.internet.InternetAddress	getFromAddress()
java.lang.String	getMessageId(java.lang.String msgIdFileName) Find the messageId of this message.
AttachmentHolder	getMessageIdAttachment(java.lang.String msgIdFileName) Find the messageId of this message.
AttachmentHolder	getMsgUnitAttachment() Lookup attachment.
java.lang.String	getRecipientsList() Comma separated value list of all recipient email addresses for logging.
java.lang.String	getRequestId(java.lang.String msgIdFileName) The requestId from the <messageId><requestId>123456</requestId></messageId> markup.
java.util.Date	getSentDate() Returns the value of the RFC 822 "Date" field.
java.lang.String	getSessionId(java.lang.String msgIdFileName) The emails session id.
java.lang.String	getSubject()
javax.mail.internet.InternetAddress[]	getToAddresses()
java.lang.String	getToAddressesStr()
boolean	isExpired(java.lang.String msgIdFileName) Check if an email can be deleted.
boolean	isMessageIdAttachment(AttachmentHolder holder, java.lang.String msgIdFileName)
boolean	isMsgUnitAttachment(AttachmentHolder holder)
boolean	isRequestIdFromSentDate()
boolean	isSendAsync()
boolean	isSendContentAsText()
static void	main(java.lang.String[] args) For manual tests.
private static int	parseTag(int startIndex, java.lang.String token, java.lang.String xml, java.lang.StringBuffer value) Internal helper for parsing.
private static int	parseTag(int startIndex, java.lang.String startToken, java.lang.String endToken, java.lang.String xml, java.lang.StringBuffer value) Internal helper for parsing.
static EmailData	parseXml(java.lang.String xml) Hand made parser to parse xml, much faster than SAX.
void	setAttachments(java.util.ArrayList attachmentHolders)
void	setBcc(java.lang.String bcc)
void	setCc(java.lang.String cc)
void	setContent(java.lang.String content)
void	setEncoding(java.lang.String aEncoding)
void	setExpiryTime(java.sql.Timestamp expiryTime) Set an absolute time in future when this email is regarded as obsolete.
void	setMessageIdFileName(java.lang.String name)
void	setReplyTo(javax.mail.internet.InternetAddress[] replyTo) Currenlty not supported!
void	setRequestId(java.lang.String requestId)
void	setRequestIdFromSentDate(boolean requestIdFromSentDate)
void	setSendAsync(boolean sendAsync) Set to true if you want to send the mail over a producer/consumer pattern from another thread.
void	setSendContentAsText(boolean sendContentAsText)
void	setSentDate(java.util.Date sentDate)
void	setSessionId(java.lang.String sessionId)
void	setSubject(java.lang.String subject)
private javax.mail.internet.InternetAddress	toInternetAddress(java.lang.String address)
java.lang.String	toString()
java.lang.String	toXml(boolean readable) Dumps message to xml.
java.lang.String	toXml(boolean readable, boolean dumpAttachmentData) Dumps message to xml.

Methods inherited from class java.lang.Object

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

Field Detail

log

private static java.util.logging.Logger log

encoding

protected java.lang.String encoding

recipients

protected javax.mail.internet.InternetAddress[] recipients

cc

protected javax.mail.internet.InternetAddress[] cc

bcc

protected javax.mail.internet.InternetAddress[] bcc

from

protected javax.mail.internet.InternetAddress from

subject

protected java.lang.String subject

sendContentAsText

protected boolean sendContentAsText

content

protected java.lang.String content

attachments

protected java.util.ArrayList attachments

Containts AttachmentHolder instances

sessionId

protected java.lang.String sessionId

Contains sessionId *

requestId

protected java.lang.String requestId

Contains requestId *

expiryTime

protected java.sql.Timestamp expiryTime

sentDate

protected java.util.Date sentDate

The origination date from the email header, this field exists always for incoming emails

requestIdFromSentDate

protected boolean requestIdFromSentDate

Remember if we got an explicit requestId or if we extracted it from the sentDate

replyTo

protected javax.mail.internet.InternetAddress[] replyTo

MESSAGEID_TAG

public static final java.lang.String MESSAGEID_TAG

The root tag <messageId>

See Also:

Constant Field Values

METHODNAME_TAG

public static final java.lang.String METHODNAME_TAG

See Also:

Constant Field Values

REQUESTID_TAG

public static final java.lang.String REQUESTID_TAG

See Also:

Constant Field Values

SESSIONID_TAG

public static final java.lang.String SESSIONID_TAG

See Also:

Constant Field Values

EXPIRES_TAG

public static final java.lang.String EXPIRES_TAG

See Also:

Constant Field Values

EXPIRES_HEADER_RFC2156

public static final java.lang.String EXPIRES_HEADER_RFC2156

Expiry Date Indication Supported as new RFC 822 header (Expires:). In general, no automatic action can be expected.

See Also:

http://www.faqs.org/rfcs/rfc2156.html, Constant Field Values

MESSAGEID_EXTENSION

public static final java.lang.String MESSAGEID_EXTENSION

Holding the relevant email meta info like a request identifier

See Also:

Constant Field Values

sendAsync

public boolean sendAsync

messageIdFileName

private java.lang.String messageIdFileName

Constructor Detail

EmailData

public EmailData(java.lang.String recipient,
                 java.lang.String from,
                 java.lang.String subject,
                 java.lang.String content)

Create a simple message.

Parameters:

recipient - For example "jack@gmx.net" or "jack@gmx.net,jeff@gmx.net"

from - For example "sue@gmx.net"

subject - For example "Hi"

content - For example "Best regards, Sue"

EmailData

public EmailData(java.lang.String[] recipients,
                 java.lang.String from,
                 java.lang.String subject,
                 java.lang.String content)

Create a simple message for any number of recipients.

See Also:

EmailData(String, String, String, String)

EmailData

public EmailData(javax.mail.internet.InternetAddress recipient,
                 javax.mail.internet.InternetAddress from,
                 java.lang.String subject)

Method Detail

isSendAsync

public boolean isSendAsync()

Returns:

the sendAsync

setSendAsync

public void setSendAsync(boolean sendAsync)

Set to true if you want to send the mail over a producer/consumer pattern from another thread. This is helpful to protect against blocking SMTP servers.

Parameters:

sendAsync - the sendAsync to set, defaults to false

setMessageIdFileName

public void setMessageIdFileName(java.lang.String name)

toInternetAddress

private javax.mail.internet.InternetAddress toInternetAddress(java.lang.String address)
                                                       throws java.lang.IllegalArgumentException

Throws:

java.lang.IllegalArgumentException

addAttachment

public void addAttachment(AttachmentHolder attachmentHolder)

setAttachments

public void setAttachments(java.util.ArrayList attachmentHolders)

getAttachments

public AttachmentHolder[] getAttachments()

Access all attachements.

Returns:

Never null

getContentByExtension

public byte[] getContentByExtension(java.lang.String extension)

Lookup attachment.

Parameters:

extension - For example XbfParser.XBFORMAT_EXTENSION=".xbf"

Returns:

null if no such attachment was found

getMsgUnitAttachment

public AttachmentHolder getMsgUnitAttachment()

Lookup attachment. If extension is not found try to find extensionBackup.

Parameters:

extension - For example XbfParser.XBFORMAT_EXTENSION=".xbf"

extensionZ - For example XbfParser.XBFORMAT_ZLIB_EXTENSION=".xbfz"

extensionBackup - For example ".xml"

Returns:

null if no such attachment was found

isMsgUnitAttachment

public boolean isMsgUnitAttachment(AttachmentHolder holder)

getFileNameList

public java.lang.String getFileNameList()

Comma separated value list of all attachment file names (unquoted) for logging.

Returns:

For example "a.xbf, b.xml, m.mid"

getRecipientsList

public java.lang.String getRecipientsList()

Comma separated value list of all recipient email addresses for logging.

Returns:

For example "joe@locahost,demo@localhost"

setEncoding

public void setEncoding(java.lang.String aEncoding)

See Also:

getEncoding()

getEncoding

public java.lang.String getEncoding()

Encoding (charset) for example "UTF-8". To support Japanese, English and German, use "UTF-8", this sets for example the mail header:

  Content-Type: text/plain; charset=UTF-8
 

"ISO-8859-1" is good enough for German and English

Returns:

Never null, defaults to "ISO-8859-1"

getAllRecipients

public java.lang.String[] getAllRecipients()

Returns:

All destinations of the message, never null

getFrom

public java.lang.String getFrom()

Returns:

The from of the message, never null

getFromAddress

public javax.mail.internet.InternetAddress getFromAddress()

Returns:

Never null

getToAddresses

public javax.mail.internet.InternetAddress[] getToAddresses()

getToAddressesStr

public java.lang.String getToAddressesStr()

getSubject

public java.lang.String getSubject()

Returns:

The subject of the message, never null

setSubject

public void setSubject(java.lang.String subject)

Parameters:

subject - The subject to set.

getContent

public java.lang.String getContent()

Returns:

The content of the message, never null

getAttachment

public AttachmentHolder getAttachment(java.lang.String fileName)

toXml

public java.lang.String toXml(boolean readable)

Dumps message to xml.

Parameters:

readable - If true '\0' are replaced by '*'

toXml

public java.lang.String toXml(boolean readable,
                              boolean dumpAttachmentData)

Dumps message to xml.

Parameters:

readable - If true '\0' are replaced by '*'

dumpAttachmentData - set to false to avoid dumping huge attachment binaries

parseTag

private static int parseTag(int startIndex,
                            java.lang.String startToken,
                            java.lang.String endToken,
                            java.lang.String xml,
                            java.lang.StringBuffer value)

Internal helper for parsing.

Parameters:

startIndex - >= 0

value - The wanted text between the tags

Returns:

The current start position and -1 if not found

parseTag

private static int parseTag(int startIndex,
                            java.lang.String token,
                            java.lang.String xml,
                            java.lang.StringBuffer value)

Internal helper for parsing.

Parameters:

startIndex - >= 0

token - The tag name without "<", ">"

value - The wanted text between the tags

Returns:

The current start position and -1 if not found

parseXml

public static EmailData parseXml(java.lang.String xml)

Hand made parser to parse xml, much faster than SAX. Will fail if a tag is omitted and this tag occurs for example in the CDATA section of the content. Therefor we always dump the complete xml in toXml(). Not for production use, Attachments are not yet supported!

Multiple <to> tags are allowed or a single with comma separated addresses.

getRequestId

public java.lang.String getRequestId(java.lang.String msgIdFileName)

The requestId from the <messageId><requestId>123456</requestId></messageId> markup. If not found the sent-date from the email header is used, note that this is not unique if more than one emails per seconds are send. It is more safe to explicitely use our requestId markup.

Returns:

Returns the requestId, never null

setRequestId

public void setRequestId(java.lang.String requestId)

Parameters:

requestId - The requestId to set.

getSessionId

public java.lang.String getSessionId(java.lang.String msgIdFileName)

The emails session id. Can (but must not) be identical to the SessionInfo-secretSessionId

Returns:

Returns the sessionId, never null

setSessionId

public void setSessionId(java.lang.String sessionId)

Parameters:

sessionId - The sessionId to set.

getMessageId

public java.lang.String getMessageId(java.lang.String msgIdFileName)

Find the messageId of this message. This is usually in the subject or in an attachment with extension ".mid"

Returns:

null if none is found or for example somesecret5update

getMessageIdAttachment

public AttachmentHolder getMessageIdAttachment(java.lang.String msgIdFileName)

Find the messageId of this message. This is usually in the subject or in an attachment with extension ".mid"

Returns:

null if none is found or for example somesecret5update

isMessageIdAttachment

public boolean isMessageIdAttachment(AttachmentHolder holder,
                                     java.lang.String msgIdFileName)

extractMessageId

public java.lang.String extractMessageId(java.lang.String tag,
                                         java.lang.String msgIdFileName)

Find the given tag in the messageId of this message. Subject: abcd5update

Parameters:

tag - "requestId" or "sessionId" or "methodName"

Returns:

null if none is found

createMessageId

public java.lang.String createMessageId(MethodName methodName,
                                        java.sql.Timestamp expiryTimestamp)

Use together with extractMessageId(EmailData messageData, String tag).

Parameters:

methodName - Can be null

expiryTimestamp - Can be null

Returns:

A well formatted XML abcd5update

createMessageId

public static java.lang.String createMessageId(java.lang.String sessionId,
                                               java.lang.String requestId,
                                               MethodName methodName,
                                               java.sql.Timestamp expiryTimestamp)

If any of the params is null no markup for this param is added. If any of the param is empty "", an empty markup is added

Parameters:

methodName - Can be null

expiryTimestamp - Can be null

Returns:

A well formatted XML, the timestamp follows the ASCII ISO notation abcd5update2005-11-30T12:42:24.200Z

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

setContent

public void setContent(java.lang.String content)

getBcc

public javax.mail.internet.InternetAddress[] getBcc()

Returns:

Returns the bcc array, is never null

setBcc

public void setBcc(java.lang.String bcc)

Parameters:

bcc - The bcc to set.

getCc

public javax.mail.internet.InternetAddress[] getCc()

Returns:

Returns the cc array, is never null

setCc

public void setCc(java.lang.String cc)

Parameters:

cc - The cc to set.

isExpired

public boolean isExpired(java.lang.String msgIdFileName)

Check if an email can be deleted.

RFC 2822 defines: The header field "Date:" must exist in an email exactly once, example: "Fri, 21 Nov 1997 09:55:06 -0600" "The origination date specifies the date and time at which the creator of the message indicated that the message was complete and ready to enter the mail delivery system."

Parameters:

emailData - email to check

Returns:

true if is expired

getExpiryTime

public java.sql.Timestamp getExpiryTime()

Is transported in the email header "Expires: "

Returns:

Returns the expiryTime or null if none is defined

setExpiryTime

public void setExpiryTime(java.sql.Timestamp expiryTime)

Set an absolute time in future when this email is regarded as obsolete.

Parameters:

expiryTime - The expiryTime to set.

getSentDate

public java.util.Date getSentDate()

Returns the value of the RFC 822 "Date" field. This is the date on which this message was sent. Returns null if this field is unavailable or its value is absent.

According to RC 822 this field exists always for incoming emails.

Returns:

Returns the sentDate.

setSentDate

public void setSentDate(java.util.Date sentDate)

Parameters:

sentDate - The sentDate to set.

setReplyTo

public void setReplyTo(javax.mail.internet.InternetAddress[] replyTo)

Currenlty not supported!

Parameters:

replyTo - The address to set.

isRequestIdFromSentDate

public boolean isRequestIdFromSentDate()

Returns:

Returns the requestIdFromSentDate.

setRequestIdFromSentDate

public void setRequestIdFromSentDate(boolean requestIdFromSentDate)

Parameters:

requestIdFromSentDate - The requestIdFromSentDate to set.

main

public static void main(java.lang.String[] args)

For manual tests. java org.xmlBlaster.util.protocol.email.EmailData

isSendContentAsText

public boolean isSendContentAsText()

setSendContentAsText

public void setSendContentAsText(boolean sendContentAsText)