wt.mail
Class EMailMessage

java.lang.Object
  wt.mail.EMailMessage

All Implemented Interfaces:

Evolvable, Externalizable, NetFactor, ObjectMappable, RemoteAccess, Serializable

public class EMailMessage

extends Object

implements RemoteAccess, ObjectMappable, Evolvable

An instance of this class represents an e-mail message. The subject and text bodies of the e-mail message are defined in terms of resource bundles, keys of entries within the bundles, and arrays of strings to be inserted into the entries. Various types of objects from which principals can be obtained may be added as recipients of the message. The message may be constructed as a multipart message, and the individual parts can be specified as text bodies or as URL's from which objects of any type may be read.

Use the newEMailMessage static factory method(s), not the EMailMessage constructor, to construct instances of this class. Instances must be constructed using the static factory(s), in order to ensure proper initialization of the instance.

Supported API: true

Extendable: false

See Also:

Serialized Form

Field Summary

private static String	CLASSNAME
private static String	DEFAULT_MIME_CHARSET
private static String	EMAIL_QUEUE_NAME
private static long	EMAIL_QUEUE_TTL
static long	EXTERNALIZATION_VERSION_UID
private static String	FC_RESOURCE
private static String	MAIL_HOST
private static String	MAIL_TASK
private static String	MIME_CHARSET_CONTENT_PROPERTY
private static String	MIME_CHARSET_HEADERS_PROPERTY
private static String	MIME_CHARSET_PROPERTY
static String	MULTIPART_SUBTYPE Label for the attribute.
private static int	MULTIPART_SUBTYPE_UPPER_LIMIT
private String	multipartSubtype
protected static long	OLD_FORMAT_VERSION_UID
private static long	ONE_DAY
private static long	ONE_HOUR
private static long	ONE_MINUTE
private WTPrincipalReference	originator
static String	ORIGINATOR Label for the attribute.
private ObjectVector	parts
private static WTProperties	properties
private ObjectVector	recipients
private static String	RESOURCE
(package private) static long	serialVersionUID
(package private) static boolean	SERVER
private static String	SMTP_PASSWORD
private static String	SMTP_USERNAME
protected static String	SUBJECT_INSERTS Label for the attribute.
protected static String	SUBJECT_KEY Label for the attribute.
private static int	SUBJECT_KEY_UPPER_LIMIT
protected static String	SUBJECT_RESOURCE Label for the attribute.
private static int	SUBJECT_RESOURCE_UPPER_LIMIT
private Object[]	subjectInserts
private String	subjectKey
private String	subjectResource
private static long	TWO_HOURS
private static boolean	VERBOSE

Fields inherited from interface wt.method.RemoteAccess

versionID

Constructor Summary

EMailMessage()

Method Summary

protected void	_send(boolean immediate) Submit the message for delivery to its intended recipients.
void	addPart(Notification notification) Deprecated.
void	addPart(String text, String contentType) Add a textual message body of a specific MIME content type to the message.
void	addPart(String resource, String key, Object[] inserts, String contentType) Add a textual message body of a specific MIME content type to the message.
void	addPart(URL url) Add a message body whose content is read from a URL.
void	addRecipient(EMailDistributionList recipient) Add the principals associated with a distribution list.
void	addRecipient(RoleHolder2 roleHolder, Vector roles) Add the principals associated with specific roles of a role holder as recipients of the message.
void	addRecipient(WTPrincipal recipient) Add a specific principal as a recipient of the message.
void	addRecipient(WTPrincipalReference recipient) Add a specific principal by reference as a recipient of the message.
void	addRecipient(WTReference recipient, Vector roles) Add the principals associated with specific roles of a role holder as recipients of the message.
private String	getCharset(Locale locale) Gets the MIME character set specified by the charset properties in WTProperties for the specified locale.
ClassInfo	getClassInfo() Returns the ClassInfo object for this class.
String	getConceptualClassname() Deprecated.
private String	getContentCharset(Locale locale) Gets the MIME character set specified by the content charset properties in WTProperties for the specified locale.
private String	getHeadersCharset(Locale locale) Gets the MIME character set specified by the headers charset properties in WTProperties for the specified locale.
String	getMultipartSubtype() Gets the value of the attribute: MULTIPART_SUBTYPE.
WTPrincipalReference	getOriginator() Gets the value of the attribute: ORIGINATOR.
Enumeration	getRecipients() Return the current list of recipients as an enumeration of objects.
protected Object[]	getSubjectInserts() Gets the value of the attribute: SUBJECT_INSERTS.
protected String	getSubjectKey() Gets the value of the attribute: SUBJECT_KEY.
protected String	getSubjectResource() Gets the value of the attribute: SUBJECT_RESOURCE.
protected void	initialize() Supports initialization, following construction of an instance.
static EMailMessage	newEMailMessage() Construct a new instance with no recipients, subject, or content.
protected void	queueMessage(long deadline, int backOff, String status, String message)
void	readExternal(ObjectInput input) Reads the non-transient fields of this class from an external source.
void	readExternal(PersistentRetrieveIfc input) Used by Persistent Data Service to populate the persistent attributes of this class from a persistent store.
private boolean	readOldVersion(ObjectInput input, long readSerialVersionUID, boolean passThrough, boolean superDone) Reads the non-transient fields of this class from an external source, which is not the current version.
protected boolean	readVersion(EMailMessage thisObject, ObjectInput input, long readSerialVersionUID, boolean passThrough, boolean superDone) Reads the non-transient fields of this class from an external source.
private void	requeue(Vector addressVector, WTUser[] users, long deadline, int backOff, String status, String message) Requeue a message, possibly with a subset of the its original recipients.
void	send(boolean immediate) Submit the message for delivery to its intended recipients.
void	setMultipartSubtype(String a_MultipartSubtype) Sets the value of the attribute: MULTIPART_SUBTYPE.
void	setOriginator(WTPrincipal originator) Set the originator of the message.
void	setOriginator(WTPrincipalReference a_Originator) Sets the value of the attribute: ORIGINATOR.
void	setSubject(String subject) Set the subject of the message.
void	setSubject(String resource, String key, Object[] inserts) Set the resource bundle, key, and inserts from which the subject of the message will be obtained.
protected void	setSubjectInserts(Object[] a_SubjectInserts) Sets the value of the attribute: SUBJECT_INSERTS.
protected void	setSubjectKey(String a_SubjectKey) Sets the value of the attribute: SUBJECT_KEY.
protected void	setSubjectResource(String a_SubjectResource) Sets the value of the attribute: SUBJECT_RESOURCE.
static void	submitMessage(EMailMessage msg, Long deadline, Integer backOff)
private void	submitMessage(long deadline, int backOff) Submit the message to the mail server for delivery to the recipients.
String	toString() Returns the conceptual (modeled) name for the class.
void	writeExternal(ObjectOutput output) Writes the non-transient fields of this class to an external source.
void	writeExternal(PersistentStoreIfc output) Used by Persistent Data Service to obtain the values of the persistent attributes of this class, so they can be written to a persistent store.

Methods inherited from class java.lang.Object

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

Field Detail

RESOURCE

private static final String RESOURCE

See Also:

Constant Field Values

CLASSNAME

private static final String CLASSNAME

SUBJECT_RESOURCE

protected static final String SUBJECT_RESOURCE

Label for the attribute.

Supported API: false

See Also:

Constant Field Values

SUBJECT_RESOURCE_UPPER_LIMIT

private static int SUBJECT_RESOURCE_UPPER_LIMIT

subjectResource

private String subjectResource

SUBJECT_KEY

protected static final String SUBJECT_KEY

Label for the attribute.

Supported API: false

See Also:

Constant Field Values

SUBJECT_KEY_UPPER_LIMIT

private static int SUBJECT_KEY_UPPER_LIMIT

subjectKey

private String subjectKey

SUBJECT_INSERTS

protected static final String SUBJECT_INSERTS

Label for the attribute.

Supported API: false

See Also:

Constant Field Values

subjectInserts

private Object[] subjectInserts

ORIGINATOR

public static final String ORIGINATOR

Label for the attribute.

Supported API: true

See Also:

Constant Field Values

originator

private WTPrincipalReference originator

MULTIPART_SUBTYPE

public static final String MULTIPART_SUBTYPE

Label for the attribute.

Supported API: true

See Also:

Constant Field Values

MULTIPART_SUBTYPE_UPPER_LIMIT

private static int MULTIPART_SUBTYPE_UPPER_LIMIT

multipartSubtype

private String multipartSubtype

recipients

private ObjectVector recipients

parts

private ObjectVector parts

SERVER

static final boolean SERVER

FC_RESOURCE

private static final String FC_RESOURCE

See Also:

Constant Field Values

serialVersionUID

static final long serialVersionUID

See Also:

Constant Field Values

EXTERNALIZATION_VERSION_UID

public static final long EXTERNALIZATION_VERSION_UID

See Also:

Constant Field Values

OLD_FORMAT_VERSION_UID

protected static final long OLD_FORMAT_VERSION_UID

See Also:

Constant Field Values

MIME_CHARSET_PROPERTY

private static final String MIME_CHARSET_PROPERTY

See Also:

Constant Field Values

MIME_CHARSET_CONTENT_PROPERTY

private static final String MIME_CHARSET_CONTENT_PROPERTY

See Also:

Constant Field Values

MIME_CHARSET_HEADERS_PROPERTY

private static final String MIME_CHARSET_HEADERS_PROPERTY

See Also:

Constant Field Values

DEFAULT_MIME_CHARSET

private static final String DEFAULT_MIME_CHARSET

See Also:

Constant Field Values

ONE_MINUTE

private static long ONE_MINUTE

ONE_HOUR

private static long ONE_HOUR

TWO_HOURS

private static long TWO_HOURS

ONE_DAY

private static long ONE_DAY

EMAIL_QUEUE_NAME

private static final String EMAIL_QUEUE_NAME

EMAIL_QUEUE_TTL

private static final long EMAIL_QUEUE_TTL

MAIL_HOST

private static final String MAIL_HOST

MAIL_TASK

private static final String MAIL_TASK

SMTP_USERNAME

private static final String SMTP_USERNAME

SMTP_PASSWORD

private static final String SMTP_PASSWORD

VERBOSE

private static final boolean VERBOSE

properties

private static WTProperties properties

Constructor Detail

EMailMessage

public EMailMessage()

Method Detail

writeExternal

public void writeExternal(ObjectOutput output)
                   throws IOException

Writes the non-transient fields of this class to an external source.

Supported API: false

Specified by:

writeExternal in interface Externalizable

Parameters:

output -

Throws:

IOException

readExternal

public void readExternal(ObjectInput input)
                  throws IOException,
                         ClassNotFoundException

Reads the non-transient fields of this class from an external source.

Supported API: false

Specified by:

readExternal in interface Externalizable

Parameters:

input -

Throws:

IOException

ClassNotFoundException

readVersion

protected boolean readVersion(EMailMessage thisObject,
                              ObjectInput input,
                              long readSerialVersionUID,
                              boolean passThrough,
                              boolean superDone)
                       throws IOException,
                              ClassNotFoundException

Reads the non-transient fields of this class from an external source.

Supported API: false

Parameters:

thisObject -

input -

readSerialVersionUID -

passThrough -

superDone -

Returns:

boolean

Throws:

IOException

ClassNotFoundException

readOldVersion

private boolean readOldVersion(ObjectInput input,
                               long readSerialVersionUID,
                               boolean passThrough,
                               boolean superDone)
                        throws IOException,
                               ClassNotFoundException

Reads the non-transient fields of this class from an external source, which is not the current version.

Parameters:

input -

readSerialVersionUID -

passThrough -

superDone -

Returns:

boolean

Throws:

IOException

ClassNotFoundException

writeExternal

public void writeExternal(PersistentStoreIfc output)
                   throws SQLException,
                          DatastoreException

Used by Persistent Data Service to obtain the values of the persistent attributes of this class, so they can be written to a persistent store.

(Not intended for general use.)

Supported API: false

Specified by:

writeExternal in interface ObjectMappable

Parameters:

output -

Throws:

SQLException

DatastoreException

readExternal

public void readExternal(PersistentRetrieveIfc input)
                  throws SQLException,
                         DatastoreException

Used by Persistent Data Service to populate the persistent attributes of this class from a persistent store.

(Not intended for general use.)

Supported API: false

Specified by:

readExternal in interface ObjectMappable

Parameters:

input -

Throws:

SQLException

DatastoreException

getConceptualClassname

public String getConceptualClassname()

Deprecated.

Returns the conceptual (modeled) name for the class.

Supported API: false

Specified by:

getConceptualClassname in interface NetFactor

Returns:

String

toString

public String toString()

Returns the conceptual (modeled) name for the class.

Supported API: false

Returns:

String

getClassInfo

public ClassInfo getClassInfo()
                       throws WTIntrospectionException

Returns the ClassInfo object for this class.

Supported API: false

Specified by:

getClassInfo in interface NetFactor

Returns:

ClassInfo

Throws:

WTIntrospectionException

getSubjectResource

protected String getSubjectResource()

Gets the value of the attribute: SUBJECT_RESOURCE.

Supported API: false

Returns:

String

setSubjectResource

protected void setSubjectResource(String a_SubjectResource)

Sets the value of the attribute: SUBJECT_RESOURCE.

Supported API: false

Parameters:

a_SubjectResource -

getSubjectKey

protected String getSubjectKey()

Gets the value of the attribute: SUBJECT_KEY.

Supported API: false

Returns:

String

setSubjectKey

protected void setSubjectKey(String a_SubjectKey)

Sets the value of the attribute: SUBJECT_KEY.

Supported API: false

Parameters:

a_SubjectKey -

getSubjectInserts

protected Object[] getSubjectInserts()

Gets the value of the attribute: SUBJECT_INSERTS.

Supported API: false

Returns:

Object []

setSubjectInserts

protected void setSubjectInserts(Object[] a_SubjectInserts)

Sets the value of the attribute: SUBJECT_INSERTS.

Supported API: false

Parameters:

a_SubjectInserts -

getOriginator

public WTPrincipalReference getOriginator()

Gets the value of the attribute: ORIGINATOR.

Supported API: true

Returns:

WTPrincipalReference

setOriginator

public void setOriginator(WTPrincipalReference a_Originator)

Sets the value of the attribute: ORIGINATOR.

Supported API: true

Parameters:

a_Originator -

getMultipartSubtype

public String getMultipartSubtype()

Gets the value of the attribute: MULTIPART_SUBTYPE.

Supported API: true

Returns:

String

setMultipartSubtype

public void setMultipartSubtype(String a_MultipartSubtype)

Sets the value of the attribute: MULTIPART_SUBTYPE.

Supported API: true

Parameters:

a_MultipartSubtype -

newEMailMessage

public static EMailMessage newEMailMessage()
                                    throws WTException

Construct a new instance with no recipients, subject, or content.

Supported API: true

Returns:

EMailMessage

Throws:

WTException

initialize

protected void initialize()
                   throws WTException

Supports initialization, following construction of an instance. Invoked by "new" factory having the same signature.

Supported API: true

Throws:

WTException

setOriginator

public void setOriginator(WTPrincipal originator)
                   throws WTException

Set the originator of the message.

Supported API: true

Parameters:

originator - The principal who is designated as the originator of the message.

Throws:

WTException

setSubject

public void setSubject(String resource,
                       String key,
                       Object[] inserts)

Set the resource bundle, key, and inserts from which the subject of the message will be obtained.

Supported API: true

Parameters:

resource - The name of the resource bundle containing the subject.

key - The key that identifies the entry within the resource bundle providing the message subject.

inserts - The objects to be inserted into the resource bundle entry to produce the subject string.

setSubject

public void setSubject(String subject)

Set the subject of the message. Generally the subject should be localized based on the preferred language of the recipients, so the method that sets the resource bundle, key, and inserts is preferred. Use of this method is strongly discouraged.

Supported API: false

Parameters:

subject - The subject text.

See Also:

#method(String resource, String key, Object [] inserts)

addRecipient

public void addRecipient(WTPrincipal recipient)
                  throws WTException

Add a specific principal as a recipient of the message.

Supported API: true

Parameters:

recipient - The principal to add as recipient.

Throws:

WTException

addRecipient

public void addRecipient(WTPrincipalReference recipient)
                  throws WTException

Add a specific principal by reference as a recipient of the message.

Supported API: true

Parameters:

recipient - The reference to the principal to be added as recipient.

Throws:

WTException

addRecipient

public void addRecipient(RoleHolder2 roleHolder,
                         Vector roles)
                  throws WTException

Add the principals associated with specific roles of a role holder as recipients of the message.

Supported API: false

Parameters:

roleHolder - The role holder containing roles from which recipients will be obtained.

roles - The specific roles within the role holder from which recipients will be obtained.

Throws:

WTException

addRecipient

public void addRecipient(WTReference recipient,
                         Vector roles)
                  throws WTException

Add the principals associated with specific roles of a role holder as recipients of the message. The role holder is identified by reference.

Supported API: false

Parameters:

recipient - The role holder reference.

roles - The roles identifying the role occupants to be added as recipients.

Throws:

WTException

addRecipient

public void addRecipient(EMailDistributionList recipient)
                  throws WTException

Add the principals associated with a distribution list.

Supported API: false

Parameters:

recipient - The distribution list whose members will be added as recipients.

Throws:

WTException

getRecipients

public Enumeration getRecipients()

Return the current list of recipients as an enumeration of objects.

Supported API: true

Returns:

Enumeration

addPart

public void addPart(String resource,
                    String key,
                    Object[] inserts,
                    String contentType)

Add a textual message body of a specific MIME content type to the message. The message body is produced from a resource within a resource bundle.

Supported API: true

Parameters:

resource - The name of the resource bundle.

key - The key of the resource within the bundle that contains the message body.

inserts - The objects, if any, to be inserted into the message body.

contentType - The MIME content type of the message body, .e.g., "text/html" or "text/plain".

addPart

public void addPart(URL url)

Add a message body whose content is read from a URL. The content can have any type. The MIME content type will be obtained from the URL object after a connection to the remote resource is established.

Supported API: true

Parameters:

url - The URL of the remote resource that provides the message body.

addPart

public void addPart(String text,
                    String contentType)

Add a textual message body of a specific MIME content type to the message. Generally the text should be localized based on the preferred language of the recipients, so the method that sets the resource bundle, key, and inserts or the method that specifies a URL is preferred. Use of this method is strongly discouraged.

Supported API: false

Parameters:

text - The textual message body.

contentType - The MIME content type of the message body, .e.g., "text/html" or "text/plain".

See Also:

#method(String resource, String key, Object [] inserts, String contentType), #method(URL url)

addPart

public void addPart(Notification notification)

Deprecated.

Supported API: false

Parameters:

notification -

See Also:

#method(String resource, String key, Object [] inserts, String contentType), #method(URL url)

send

public void send(boolean immediate)
          throws WTException

Submit the message for delivery to its intended recipients. If immediate is specified as true, the message is submitted to the mail server for delivery immediately. In this case, all recipients are resolved, all message bodies are assembled, and the message is submitted to the mail server before the method returns. Otherwise, if immediate is specified as false, the message is placed in a Windchill queue where it is submitted for delivery as a background process. In this case, the method returns immediately and resolution of recipients and assembly of message bodies are deferred until the background process begins handling the message.

Supported API: true

Parameters:

immediate - Indicates whether to submit the message to the mail server immediately (true), or place the message in a queue where it will be submitted to the mail server by a background process (false).

Throws:

WTException

_send

protected void _send(boolean immediate)
              throws WTException

Submit the message for delivery to its intended recipients. If immediate is specified as true, the message is submitted to the mail server for delivery immediately. In this case, all recipients are resolved, all message bodies are assembled, and the message is submitted to the mail server before the method returns. Otherwise, if immediate is specified as false, the message is placed in a Windchill queue where it is submitted for delivery as a background process. In this case, the method returns immediately and resolution of recipients and assembly of message bodies are deferred until the background process begins handling the message.

Supported API: true

Parameters:

immediate - Indicates whether to submit the message to the mail server immediately (true), or place the message in a queue where it will be submitted to the mail server by a background process (false).

Throws:

WTException

queueMessage

protected void queueMessage(long deadline,
                            int backOff,
                            String status,
                            String message)
                     throws WTException

Throws:

WTException

submitMessage

public static void submitMessage(EMailMessage msg,
                                 Long deadline,
                                 Integer backOff)
                          throws WTException

Throws:

WTException

submitMessage

private void submitMessage(long deadline,
                           int backOff)
                    throws WTException

Submit the message to the mail server for delivery to the recipients. Partition the recipients by locale and deliver a separate, locale-specific message to the recipients in each locale.

Throws:

WTException

getHeadersCharset

private String getHeadersCharset(Locale locale)

Gets the MIME character set specified by the headers charset properties in WTProperties for the specified locale. If there is no charset property for the specified locale, use the default headers charset property. In the case that there are no character sets specified for headers for the locale, charset will be defined according to the first defined character set found in the following order: headers(no locale), charset(locale), charset(no locale), and in the case that there are no character sets specified, ISO-8859-15 is used as the default.

getContentCharset

private String getContentCharset(Locale locale)

Gets the MIME character set specified by the content charset properties in WTProperties for the specified locale. If there is no charset property for the specified locale, use the default content charset property. In the case that there are no character sets specified for headers for the locale, charset will be defined according to the first defined character set found in the following order: content (no locale), charset (locale), charset (no locale), and in the case that there are no character sets specified, ISO-8859-15 is used as the default.

getCharset

private String getCharset(Locale locale)

Gets the MIME character set specified by the charset properties in WTProperties for the specified locale. If there is no charset property for the specified locale, use the default charset property. In the case that there are no character sets specified, ISO-8859-15 is used as the default.

requeue

private void requeue(Vector addressVector,
                     WTUser[] users,
                     long deadline,
                     int backOff,
                     String status,
                     String message)
              throws WTException

Requeue a message, possibly with a subset of the its original recipients.

Throws:

WTException