|
|
|
A zeroCode application has available two data ports, the mail data port and the mime message encoder/decoder data port, for handling e-mail. Using these data ports, the application can perform complex mail processing, such as sending and receiving messages, forwarding, handling attachments, and so forth.
|
|
The mail data port
|
|
The zeroCode mail data port enables a user data model (UDM) to retrieve and send e-mail. A UDM node that reads from the mail data port retrieves e-mail from the mail server, and a node that writes into the mail data port sends e-mail.
The mail data port can function in two modes. The simpler of the two is that of sending and receiving e-mail containing just a plain-text or HTML body without attachments. This mode suffices for many common e-mail-related chores. The more complex mode offers features such as attachments, custom mail headers and multipart/alternative messages. The latter mode requires the use of the mime message data port. These two modes correspond to the two data types, message and mimeMessage, provided by the mail data port.
|
|
The message data type
|
|
For sending and receiving simple e-mail, the UDM node employs the mail data port with the message data type. This data type is designed for simple uses, and therefore makes several simplifying assumptions. For example, instead of modeling the recipients of a message as a list of <email, name> pairs, it uses a comma-separated representation. Here is a list of the attributes of this data type, along with their properties. A “read only” attribute cannot be modified, i.e., the data port ignores attempts to change its value.
|
|
|
| Name |
Type |
Read Only |
Comment |
| id |
int |
Yes |
Index of the message in the mailbox. Used only when retrieving messages. |
| from |
string |
|
The e-mail address of the sender, e.g., zeroCode Administrator. |
| senderName |
String |
|
The user name of the sender, e.g.,
zde@zerocode.com |
to
|
String |
|
The comma- or semicolon-separated list of 'to' e-mail addresses. Each address can be in either the address-only form, such as info@zerocode.com, or the name-and-address form zeroCode Information <info@zerocode.com>. |
| cc
|
String |
|
Comma- or semicolon-separated list of 'cc' e-mail addresses.
|
| bcc |
String |
|
Comma- or semicolon-separated list of 'bcc' e-mail addresses. |
| receivedDate |
Date |
Yes |
Date and time at which the message was received. |
| sentDate |
Date |
|
Date and time at which the message was sent. |
| subject |
String |
|
Subject of message |
| contentType |
String |
|
The mime type of the message body, usually either text/plain or text/html. |
| body |
String |
|
The message body as a string. If the message is in HTML format, this string includes the necessary tags and escape characters, and the contentType will be set to text/html. |
| flag_ANSWERED |
Boolean |
Yes |
Whether the user has responded to the message. This and other flags below are set by the POP3 or IMAP mail delivery server. |
| flag_DELETED |
Boolean |
Yes |
Whether the user has deleted the message. |
| flag_DRAFT |
Boolean |
Yes |
Whether the message is marked as “draft”. |
| flag_FLAGGED |
Boolean |
Yes |
Whether the user has flagged the message for follow-up. |
| flag_SEEN |
Boolean |
Yes |
Whether the user has seen the message. |
| flag_RECENT |
Boolean |
Yes |
Whether the message is “recent”. |
| flag_USER |
Boolean |
Yes |
User-defined flag. |
|
|
|
| The mimeMessage data type
|
| The mimeMessage data type is used to get tighter control of message processing. If the UDM node uses the mail data port with the mimeMessage data type, the data port does not perform any parsing of the message, and instead restricts itself to merely fetching and sending the message in its raw form. The tasks of breaking down the message into its components (i.e., decoding it), or putting it back together (encoding it), must then be performed by other parts of the UDM. This encoding/decoding functionality is provided by the mime message encoder/decoder port, which is described subsequently.
|
|
|
| The mimeMessage data type provides none of the envelope or message-related attributes – instead, it includes just one attribute named messageBlock that contains the raw message being transported. This attribute can be bound as the parameter to the mime encoder data port for retrieving and storing the attributes of the mime message. The attributes of the mimeMessage data type are shown here.
|
|
|
| Name |
Type |
Read Only |
Comment |
| id |
int |
Yes |
Index of the message in the mailbox. Used only when retrieving messages. |
| messageBlock |
MimeMessage |
|
The encoded mime message. |
| sizeInBytes |
int |
|
The number of bytes in the message. |
| flag_ANSWERED |
Boolean |
Yes |
Whether the user has responded to the message. This and other flags below are set by the POP3 or IMAP mail delivery server. |
| flag_DELETED |
Boolean |
Yes |
Whether the user has deleted the message. |
| flag_DRAFT |
Boolean |
Yes |
Whether the message is marked as “draft”. |
| flag_FLAGGED |
Boolean |
Yes |
Whether the user has flagged the message for follow-up. |
| flag_SEEN |
Boolean |
Yes |
Whether the user has seen the message. |
| flag_RECENT |
Boolean |
Yes |
Whether the message is “recent”. |
| flag_USER |
Boolean |
Yes |
User-defined flag. |
|
|
|
|
MimeMessagePort: The mime message encoder / decoder data port
|
|
|
|
The usual concept of a data port is as a facility for transmitting data between the UDM and an external repository. The MimeMessagePort views its “repository” as a MimeMessage object, which is an in-memory encoded representation of a message sent by e-mail. When the MimeMessagePort “reads” from its repository, it is actually decoding the content of the MimeMessage object into its components. Conversely, when the MimeMessagePort “writes” to its repository, it is actually encoding data into its MimeMessage object. The MimeMessage object on which a MimeMessagePort operates is specified via a data port bind variable when the UDM node for the MimeMessagePort is created.
|
|
|
|
The MimeMessagePort provides five data types corresponding to message components: envelope, containing message envelope information; recipient, a recipient of the message; bodyElement, providing the attributes of the body of the message; attachment, representing a single attachment to the message; and header, for reading or setting the value of a specific (possibly custom) mail header.
|
|
|
|
Here is a little example of how to use the MimeMessagePort in conjunction with the mail data port. Suppose you wish to read the messages from a mailbox and show determine the subject and recipients of each message. The UDM that achieves this purpose is shown in outline below.
|
|
|
| Node
# |
Node
name |
Dataport |
Data
type |
Parameter |
Comment |
| 1 |
mailReader |
|
|
|
UDM Root |
| 2 |
mailbox (list) |
Mail dataport |
MimeMessage |
|
List of message |
| 3 |
id |
|
int |
|
|
| 4 |
messageBlock |
|
Raw mime message |
|
The raw (uncoded) mime message |
| |
Other attributes |
|
|
|
|
| |
|
|
|
|
|
| 5 |
envelope |
mime message dataport |
envelope |
Node # 4 |
Envelope information for the message |
| 6 |
messageId |
|
String |
|
|
| 7 |
Subject |
|
String |
|
|
| |
other attributes |
|
|
|
|
| |
|
|
|
|
|
| 8 |
recipients(list) |
Mime message dataport |
recipient |
Node # 4 |
List of recipients of the message |
| 9 |
email address |
|
String |
|
|
| 10 |
User Name |
|
String |
|
|
| 11 |
recipientType |
|
string |
|
one of "To", "Cc"
or "Bcc" |
|
|
|
|
Here the mailbox node (node 2) retrieves a list of messages from the mail data port. We then employ two other nodes, envelope (node 5) and recipients (node 8) to decode the needed attributes of the message. Notice the following:
|
|
|
|
The two nodes that use the MimeMessagePort are set up to use the messageBlock attribute (node 4) as parameter. This shows that we can use multiple MimeMessagePort nodes, each serving a different purpose, and all operating on the same raw mime message.
|
|
|
|
Using the MimeMessagePort for decoding recipients gives us the list of recipients in structured form, unlike the amorphous comma-separated string offered by the Mail data port's message data type. Thus, for example, we could extend the above UDM with a database node that uses the emailAddress field (node 9) to look up a user in the database. If we had used the simpler message data type, we would have to parse the address string before using it.
|
|
|
