Package com.storedobject.mail

Class Mail

java.lang.Object

com.storedobject.core.StoredObject

com.storedobject.core.Message

com.storedobject.mail.Mail

All Implemented Interfaces:

Displayable, StringFiller, HasId

public class Mail
extends Message

Represents a Mail providing capabilities to manage and send emails with support for handling addresses, CC, sender information, message types, attachments, and error handling.

Author:

Syam

Field Summary

Fields inherited from class com.storedobject.core.Message

error, sentToId

Fields inherited from class com.storedobject.core.StoredObject

logger

Constructor Summary

Constructors

Constructor	Description
Mail()	Initializes a new instance of the Mail class with default settings.

Method Summary

Modifier and Type	Method	Description
static void	alert(Transaction transaction, String message, StoredObject person)	Sends an alert for the given transaction with a specified message and person information.
static void	alert(Transaction transaction, String message, StoredObject person, String subject)	Sends an alert with the specified details.
static void	alert(Transaction transaction, String message, Iterable<? extends StoredObject> persons)	Sends an alert with a specified message to a group of persons in the context of a given transaction.
static void	alert(Transaction transaction, String message, Iterable<? extends StoredObject> persons, String subject)	Sends an alert email to the specified recipients with the provided message and subject.
boolean	attach(TransactionManager tm, ContentProducer... content)	Attaches one or more content items to the mail using the provided transaction manager.
boolean	attach(TransactionManager tm, FileData... files)	Attaches the provided files to the specified transaction manager.
boolean	attach(TransactionManager tm, Iterable<FileData> files)	Attaches a collection of files to the current object using the provided TransactionManager.
boolean	attachFrom(TransactionManager tm, Mail another)	Attach attachments from another mail.
static void	columns(Columns columns)	Adds the necessary columns for the Mail table.
static Mail	createAlert()	Creates an alert and returns it as a Mail object.
static Mail	createAlert(TransactionManager tm)	Creates and prepares an alert mail based on the provided TransactionManager instance.
static boolean	customizeMetadata(String fieldName, UIFieldMetadata md)	Customizes the metadata for a specified field name by applying specific configurations.
String	getCCAddress()	Retrieves the "CC address" associated with the mail.
String	getErrorValue()	Retrieves the error value associated with the current object's error property.
static String	getErrorValue(int value)	Retrieves a specific error value from the predefined error values array based on the provided input value.
static String[]	getErrorValues()	Retrieves the array of error values associated with the mail.
String	getFromAddress()	Retrieves the "from address" associated with the sender of the mail.
String	getMessageType()	Retrieves the message type associated with this mail.
String	getReplyToAddress()	Retrieves the "reply-to address" associated with the mail.
Sender	getSender()	Retrieves the sender associated with the mail.
SenderGroup	getSenderGroup()	Retrieves the SenderGroup instance associated with the current senderGroupId.
Id	getSenderGroupId()	Retrieves the identifier of the sender group associated with the mail.
Id	getSenderId()	Retrieves the identifier of the sender associated with the mail.
String	getSubject()	Retrieves the subject of the mail.
String	getToAddress()	Retrieves the "to address" associated with the mail.
static void	indices(Indices indices)	Defines and adds various index configurations for a mail table.
static String[]	links()	Provides links to associated classes or objects related to 'Mail'.
void	setCCAddress(Id personId)	Set the "CC address".
void	setCCAddress(StoredObject person)	Set the "CC address".
void	setCCAddress(String ccAddress)	Set "CC address".
void	setErrorValue(String errorValue)	Sets the error value for the Mail instance.
void	setMessageType(String messageType)	Sets the message type for the mail.
void	setReplyToAddress(String replyToAddress)	Sets the "Reply-To" address for the email.
void	setSender(Id senderId)	Sets the sender for the mail using the specified sender ID.
void	setSender(Sender sender)	Sets the sender for the mail instance using the provided Sender object.
void	setSender(BigDecimal idValue)	Sets the sender information for the mail using the provided identifier value.
void	setSenderGroup(Id senderGroupId)	Sets the sender group for the mail.
void	setSenderGroup(SenderGroup senderGroup)	Sets the sender group for the mail.
void	setSenderGroup(String senderGroupName)	Sets the sender group for the mail based on the given sender group name.
void	setSenderGroup(BigDecimal idValue)	Sets the sender group using the given identifier value.
void	setSentTo(Person sentTo)	Sets the recipient of the message.
void	setSubject(String subject)	Sets the subject of the mail.
void	setToAddress(Id personId)	Set the "to address".
void	setToAddress(StoredObject person)	Set the "to address".
void	setToAddress(String toAddress)	Set "to address".
String	toString()	String representation of the instance.
void	validateData(TransactionManager tm)	This will be invoked by the system whenever the object is saved to the DB.

Methods inherited from class com.storedobject.core.Message

getCreatedAt, getError, getMessage, getMessageID, getSent, getSentAt, getSentTo, getSentToId, protectedColumns, ready, sent, sent, setCreatedAt, setError, setMessage, setMessageID, setSent, setSentAt, setSentTo, setSentTo

Methods inherited from class com.storedobject.core.StoredObject

addLink, addLink, addLink, addLink, addLink, addLink, addLink, addLink, checkCurrency, checkCurrency, checkForDuplicate, checkForDuplicate, checkTimeZone, checkTransaction, clearObjectLinks, contemporary, copy, copy, count, count, count, count, count, count, countLinks, countLinks, countLinks, countLinks, countLinks, countLinks, countLinks, countLinks, countLinks, countLinks, countLinks, countLinks, countLinks, countLinks, countLinks, countLinks, countLinks, countLinks, countLinks, countLinks, countLinks, countLinks, countLinks, countLinks, countMasters, countMasters, countMasters, countMasters, countMasters, countMasters, countMasters, countMasters, countMasters, countMasters, countMasters, countMasters, countMasters, countMasters, countMasters, countMasters, countMasters, countMasters, countMasters, countMasters, countMasters, countMasters, countMasters, countMasters, create, created, delete, delete, delete, deleted, directUpdate, equals, exists, exists, exists, exists, exists, existsFileData, existsLink, existsLink, existsLink, existsLink, existsLink, existsLink, existsLink, existsLink, existsLinks, existsLinks, existsLinks, existsLinks, existsLinks, existsLinks, existsLinks, existsLinks, existsLinks, existsLinks, existsLinks, existsLinks, existsLinks, existsLinks, existsLinks, existsLinks, existsLinks, existsLinks, existsLinks, existsLinks, existsLinks, existsLinks, existsLinks, existsLinks, existsLinks, existsLinks, existsMaster, existsMaster, existsMasters, existsMasters, existsMasters, existsMasters, existsMasters, existsMasters, existsMasters, existsMasters, existsMasters, existsMasters, existsMasters, existsMasters, existsMasters, family, family, family, fill, get, get, get, get, get, get, get, get, get, get, get, get, get, get, get, get, get, get, getAttachment, getAttachmentId, getChildren, getDeleted, getDeleted, getExistsCondition, getExistsCondition, getFileData, getFileData, getHistorical, getId, getKeyIndex, getMaster, getMaster, getMaster, getMaster, getMaster, getMaster, getMaster, getMaster, getMaster, getMaster, getMaster, getMaster, getMaster, getMaster, getMaster, getMaster, getMaster, getMaster, getMaster, getMaster, getMaster, getMaster, getMaster, getMaster, getNotExistsCondition, getNotExistsCondition, getParent, getParent, getParent, getParentId, getParentId, getParentId, getRelated, getRelated, getTransaction, getTransactionId, getTransactionIP, getUnique, getUniqueCondition, hashCode, inserted, isModified, isVirtual, list, list, list, list, list, list, list, list, list, list, list, list, list, listFileData, listFileData, listHistory, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listLinks, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listMasters, listTree, listTree, listTree, listTree, listViaQuery, listViaQuery, load, load, load, load, loaded, loading, makeNew, makeVirtual, migrate, moduleName, nextVersion, objectLink, objectLink, objectLink, objectLinks, objectLinks, old, person, previousVersion, previousVersion, query, query, query, query, query, query, query, query, query, query, query, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryLinks, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, queryMasters, reload, reload, reloaded, removeAllLinks, removeAllLinks, removeAllLinks, removeAllLinks, removeAllLinks, removeAllLinks, removeAllLinks, removeAllLinks, removeAllLinks, removeAllLinks, removeAllLinks, removeAllLinks, removeLink, removeLink, removeLink, removeLink, removeLink, removeLink, removeLink, removeLink, removeLink, removeLink, removeLink, removeLink, removeReverseLinks, removeReverseLinks, save, save, save, save, save, save, save, save, save, save, save, save, save, save, saved, saving, setMaster, setRawValue, setTransaction, stringify, tableName, timestamp, toCode, toDisplay, transacting, undelete, undelete, undeleted, updated, user, userId, validate, validateChildAttach, validateChildDetach, validateChildUpdate, validateDelete, validateInsert, validateParentAttach, validateParentDetach, validateParentUpdate, validateUndelete, validateUpdate, valueEquals

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Details

Mail

public Mail()

Initializes a new instance of the Mail class with default settings. This constructor sets the initial error status to 3.

Method Details

columns

public static void columns(Columns columns)

Adds the necessary columns for the Mail table.

Parameters:

columns - The Columns object used to define the column structure. This method adds the following columns:

                - "SenderGroup" with type "Id"
                - "ToAddress" with type "text"
                - "CCAddress" with type "text"
                - "ReplyToAddress" with type "text"
                - "Subject" with type "text"
                - "MessageType" with type "text"
                - "Sender" with type "Id"
                

indices

public static void indices(Indices indices)

Defines and adds various index configurations for a mail table.

Parameters:

indices - The Indices object used to specify the column combinations and constraints for table indexing.

links

public static String[] links()

Provides links to associated classes or objects related to 'Mail'.

Returns:

An array of strings, each representing a link in the format: "Label|QualifiedClassName|AdditionalInfo|". Example elements: "Attachments|com.storedobject.mail.Attachment||", "Errors|com.storedobject.mail.Error||".

customizeMetadata

public static boolean customizeMetadata(String fieldName,
 UIFieldMetadata md)

Customizes the metadata for a specified field name by applying specific configurations.

Parameters:

fieldName - the name of the field whose metadata needs to be customized

md - the UIFieldMetadata object that represents the metadata of the field

Returns:

true if the metadata was successfully customized for the specified field, false otherwise

setSenderGroup

public void setSenderGroup(String senderGroupName)

Sets the sender group for the mail based on the given sender group name. This method retrieves the SenderGroup object associated with the specified name and updates the sender group for the mail.

Parameters:

senderGroupName - the name of the sender group to be set

setSenderGroup

public void setSenderGroup(Id senderGroupId)

Sets the sender group for the mail.

Parameters:

senderGroupId - The ID of the sender group to be set.

setSenderGroup

@Column
public void setSenderGroup(BigDecimal idValue)

Sets the sender group using the given identifier value.

Parameters:

idValue - The identifier value of the sender group.

setSenderGroup

public void setSenderGroup(SenderGroup senderGroup)

Sets the sender group for the mail.

Parameters:

senderGroup - The sender group to be set. If null, the sender group ID is set to null.

getSenderGroupId

public Id getSenderGroupId()

Retrieves the identifier of the sender group associated with the mail.

Returns:

The identifier of the sender group as an Id.

getSenderGroup

public SenderGroup getSenderGroup()

Retrieves the SenderGroup instance associated with the current senderGroupId.

Returns:

The SenderGroup instance corresponding to senderGroupId, or null if it is not found.

getFromAddress

public String getFromAddress()

Retrieves the "from address" associated with the sender of the mail. If the sender is not defined, an empty string will be returned.

Returns:

The "from address" as a String, or an empty string if the sender is not set.

setToAddress

public void setToAddress(String toAddress)

Set "to address". Comma delimited email addresses.

Parameters:

toAddress - Addresses.

setToAddress

public void setToAddress(Id personId)

Set the "to address".

Parameters:

personId - Id of the Person, SystemUser, SystemUserGroup, Contact, PersonRole or MessageGroup.

setToAddress

public void setToAddress(StoredObject person)

Set the "to address".

Parameters:

person - Person, SystemUser, SystemUserGroup, Contact, PersonRole or MessageGroup.

getToAddress

public String getToAddress()

Retrieves the "to address" associated with the mail.

Returns:

The "to address" as a String. This typically contains comma-separated email addresses.

setCCAddress

public void setCCAddress(String ccAddress)

Set "CC address". Comma delimited email addresses.

Parameters:

ccAddress - Addresses.

setCCAddress

public void setCCAddress(Id personId)

Set the "CC address".

Parameters:

personId - Id of the Person, SystemUser, SystemUserGroup, Contact, PersonRole or MessageGroup.

setCCAddress

public void setCCAddress(StoredObject person)

Set the "CC address".

Parameters:

person - Person, SystemUser, SystemUserGroup, Contact, PersonRole or MessageGroup.

getCCAddress

@Column(required=false)
public String getCCAddress()

Retrieves the "CC address" associated with the mail.

Returns:

The "CC address" as a String. This typically contains comma-separated email addresses or may return null if no CC address is set.

setReplyToAddress

public void setReplyToAddress(String replyToAddress)

Sets the "Reply-To" address for the email. This address specifies where replies to the email should be sent.

Parameters:

replyToAddress - The "Reply-To" email address to be set. Typically, this is a valid email address in string format.

getReplyToAddress

@Column(required=false)
public String getReplyToAddress()

Retrieves the "reply-to address" associated with the mail. This value may be used to indicate the address that should receive replies to the mail if different from the "from address".

Returns:

The "reply-to address" as a String, or null if not set.

setSubject

public void setSubject(String subject)

Sets the subject of the mail.

Parameters:

subject - The subject of the mail as a string.

getSubject

public String getSubject()

Retrieves the subject of the mail.

Returns:

The subject of the mail as a String.

setMessageType

public void setMessageType(String messageType)

Sets the message type for the mail.

Parameters:

messageType - The type of the message to be set.

getMessageType

public String getMessageType()

Retrieves the message type associated with this mail.

Returns:

The message type as a String.

setErrorValue

public void setErrorValue(String errorValue)

Sets the error value for the Mail instance. The method determines the error code corresponding to the specified error value from the predefined errorValues array. If the provided error value is not found, a default error code is assigned.

Parameters:

errorValue - The error description string to set as the current error value. This string is compared against the elements in the errorValues array.

getErrorValues

public static String[] getErrorValues()

Retrieves the array of error values associated with the mail.

Returns:

An array of strings representing error values.

getErrorValue

public static String getErrorValue(int value)

Retrieves a specific error value from the predefined error values array based on the provided input value.

Parameters:

value - the input value used to determine the appropriate error value. This value is used as an index after being adjusted by the length of the error values array.

Returns:

the error value as a String corresponding to the adjusted index derived from the input value.

getErrorValue

public String getErrorValue()

Retrieves the error value associated with the current object's error property.

Returns:

The error value as a String, derived from the error property.

setSender

public void setSender(Id senderId)

Sets the sender for the mail using the specified sender ID.

Parameters:

senderId - The identifier of the sender to be set.

setSender

@Column
public void setSender(BigDecimal idValue)

Sets the sender information for the mail using the provided identifier value. The identifier value is wrapped into an Id object and assigned to the sender.

Parameters:

idValue - The identifier value of the sender as a BigDecimal.

setSender

public void setSender(Sender sender)

Sets the sender for the mail instance using the provided Sender object. If the sender is null, the sender ID is set to null.

Parameters:

sender - The Sender object representing the sender to be set. If null, the sender ID associated with the mail will also be set to null.

getSenderId

@Column(style="(any)",
        required=false)
public Id getSenderId()

Retrieves the identifier of the sender associated with the mail.

Returns:

The sender identifier as an Id instance, or null if not set.

getSender

public Sender getSender()

Retrieves the sender associated with the mail.

Returns:

The Sender instance corresponding to the senderId. If the sender is not found, the method may return null.

toString

public String toString()

Description copied from class: StoredObject

String representation of the instance. Mostly used for logging purposes.

Overrides:

toString in class StoredObject

Returns:

String representation of the instance.

validateData

public void validateData(TransactionManager tm)
                  throws Exception

Description copied from class: StoredObject

This will be invoked by the system whenever the object is saved to the DB. It will be invoked in all cases, while creating new objects and updating/deleting/un-deleting existing objects. If any exception is raised by this method, the process of saving to the DB will be abandoned.

Note: This method is mainly used to validate the data of all attributes of the object, and it may be used by others for validating the object. For example, front-end data-entry systems can use this method for validating the object.

Overrides:

validateData in class Message

Parameters:

tm - Current transaction manager.

Throws:

Exception - If data is invalid.

attach

public boolean attach(TransactionManager tm,
 ContentProducer... content)

Attaches one or more content items to the mail using the provided transaction manager. This method saves the current context if not already saved, processes the content, and creates attachments by linking the content to mail.

Parameters:

tm - the transaction manager used to handle database transactions

content - one or more content producers that generate the content to be attached

Returns:

true if the attachment process is successful, false otherwise

attach

public boolean attach(TransactionManager tm,
 FileData... files)

Attaches the provided files to the specified transaction manager.

Parameters:

tm - the transaction manager to which the files should be attached

files - the array of file data objects to be attached

Returns:

true if the files were successfully attached, false otherwise

attach

public boolean attach(TransactionManager tm,
 Iterable<FileData> files)

Attaches a collection of files to the current object using the provided TransactionManager.

Parameters:

tm - the TransactionManager to handle the transactional operations

files - an Iterable collection of FileData objects to be attached

Returns:

true if the files were successfully attached; false otherwise

attachFrom

public boolean attachFrom(TransactionManager tm,
 Mail another)

Attach attachments from another mail. When doing this, the actual contents are not duplicated. Instead, they are linked internally.

Parameters:

tm - Transaction manager

another - Another mail.

Returns:

True if successful.

createAlert

public static Mail createAlert()
                        throws SOException

Creates an alert and returns it as a Mail object. This method may throw an SOException in case of errors during the alert creation process.

Returns:

A Mail object representing the created alert.

Throws:

SOException - If an error occurs during the alert creation process.

createAlert

public static Mail createAlert(TransactionManager tm)
                        throws SOException

Creates and prepares an alert mail based on the provided TransactionManager instance. If no sender group with the name "Alert" exists, it attempts to create and save one using the transaction manager. The sender group ID is then assigned to the mail. If no TransactionManager is provided or the sender group creation fails, the method throws an SOException.

Parameters:

tm - the TransactionManager instance used to handle database transactions for creating a new sender group if required. It can be null.

Returns:

a Mail object initialized with sender group details for the alert.

Throws:

SOException - if no sender groups are defined for mail alerts, and the sender group creation fails or cannot be performed.

alert

public static void alert(Transaction transaction,
 String message,
 StoredObject person)
                  throws Exception

Sends an alert for the given transaction with a specified message and person information.

Note: The person object could be an instance of Person, SystemUser, HasContacts or Contact.

Parameters:

transaction - the transaction object associated with the alert

message - the message to be included in the alert

person - the person object related to the alert

Throws:

Exception - if an error occurs while processing the alert

alert

public static void alert(Transaction transaction,
 String message,
 Iterable<? extends StoredObject> persons)
                  throws Exception

Sends an alert with a specified message to a group of persons in the context of a given transaction.

Note: The person iterator could contain instances of Person, SystemUser, HasContacts or Contact.

Parameters:

transaction - The transaction within which the alert is being generated.

message - The message content for the alert.

persons - An iterable collection of recipients (StoredObject instances) to whom the alert is sent.

Throws:

Exception - If an error occurs while processing the alert.

alert

public static void alert(Transaction transaction,
 String message,
 StoredObject person,
 String subject)
                  throws Exception

Sends an alert with the specified details.

Note: The person object could be an instance of Person, SystemUser, HasContacts or Contact.

Parameters:

transaction - The transaction context in which the alert will be executed.

message - The message content of the alert.

person - The stored object representing the person to whom the alert is related.

subject - The subject of the alert.

Throws:

Exception - If an error occurs while sending the alert.

alert

public static void alert(Transaction transaction,
 String message,
 Iterable<? extends StoredObject> persons,
 String subject)
                  throws Exception

Sends an alert email to the specified recipients with the provided message and subject.

Note: The person object could be an instance of Person, SystemUser, HasContacts or Contact.

Parameters:

transaction - The transaction object used to save the email alert.

message - The message content of the alert email.

persons - An iterable collection of recipients represented as StoredObject instances.

subject - The subject line of the alert email. If null, the default subject "Alert" is used.

Throws:

Exception - If an error occurs during alert creation, email preparation, or saving the alert.

setSentTo

public void setSentTo(Person sentTo)

Sets the recipient of the message.

Overrides:

setSentTo in class Message

Parameters:

sentTo - The person to whom the message is being sent.