Oracle Internet File System Developer's Guide Release 1.1 Part Number A75172-04 |
|
This chapter covers the following topics:
We are all familiar with using standard e-mail clients to create and send e-mail messages. However, e-mail can also be created and sent by an application program. This type of e-mail is called programmatic e-mail.
When a user inserts, updates, or deletes a file, your custom application can perform the following tasks:
The message is staged in the Oracle iFS Outbox to await delivery.
Programmatic e-mail takes place in a transactional environment. Applications that require transactional capability include multiple activities, one of which is an e-mail notification. For the application to complete the task, the application must perform some action and then send a notification of that action. The action and the notification must be so tightly linked that you want both to be rolled back if the message is not accepted by the Outbox. Here are the stages of the process:
An example of this type of application would be creating a new customer account, then sending a message to the customer saying, "Here is your new account number and password." If the message cannot be sent, the account and password are rolled back. The Oracle iFS framework for programmatic e-mail provides a mechanism for Oracle iFS applications to send such e-mail messages.
The Oracle iFS infrastructure for programmatic e-mail includes the Outbox folder and the IfsMessage class.
The Outbox folder is the location where messages are staged to await delivery. A system-wide Oracle iFS Outbox is created during the installation process. An Outbox agent delivers mail present in the Outbox on an event-driven basis.
The Oracle iFS API class, IfsMessage, provides methods to create and send e-mail programmatically. All e-mail consists of three parts:
The methods of the IfsMessage class allow you to set appropriate values for each of these parts.
One common use of programmatic e-mail is to use an application program to respond automatically to customer actions. For example, in an e-commerce application:
To create this automatic e-mail confirmation, you use information from multiple sources. Some information comes from the customer, such as name and e-mail address. Other information comes from your company, such as text for the confirmation message and any attachments, such as an invoice.
The application program must perform three tasks:
To write a programmatic e-mail application, follow these steps:
For more information about e-mail methods, see the Javadoc for the oracle.ifs.adk.mail.IfsMessage
class.
Parameter | Datatype |
---|---|
Session |
LibrarySession |
To |
String[] |
CC (Carbon Copy) |
String[] |
BCC (Blind Carbon Copy) |
String[] |
Subject |
String |
Body |
Reader |
// Use the convenience method to send a short message. mail.sendMessage(currentSession,"Recipient", "CcRecipient", "BccRecipient",
"Subject:Sending Short Messages","This is a one-sentence message.");
Creating a database connection is the first task of every Oracle iFS application, and requires both LibraryService and LibrarySession. For a complete sample of the standard technique for obtaining the current Library Session, see "Sample Code: Sending E-Mail Programmatically".
In this case, LibrarySession is the single parameter passed to the IfsMessage constructor.
For more information about LibraryService and LibrarySession, see Chapter 2, "API Overview":
Before you create the message object, check to be sure the current user has Admin privileges.
// Check that user is in Admin Mode. if (user.isAdminEnabled()) session.setAdministrationMode(true); // Use the IfsMessage constructor to create a message object. IfsMessage msg = new IfsMessage(session);
Multiple values are allowed for each of the following header items:
For example, to send the same message to multiple destinations, you could set three To headers and six CC headers. Any combination of the header items is acceptable, as long as at least one recipient is indicated. In other words, each message must have either a To, CC, or BCC specified, so the message can be delivered.
In some cases, one person will send mail on behalf of another person. In that case, you can specify a From value (the author of the message) that varies from the Sender value (the person who sends the message). If setFromHeader() is omitted, the From value will be set to the current user by default. If setSenderHeader() is provided, but not setFromHeader(), the value provided for Sender will be used for From and Sender will be omitted.
For details of the setter methods for the message header, see the Javadoc for oracle.ifs.adk.mail.IfsMessage.
All of the setter methods are overloaded to provide one method that accepts a single String value and another that accepts a String array.
msg.setFromHeader("tuser99@us.oracle.com"); msg.setSenderHeader(user); //Refers to a DirectoryUser msg.setToHeader("guest@us.oracle.com"); msg.setBccHeader("tuser51@us.oracle.com"); msg.setSubject("iFS email API: Mail with multi-part body");
The setBody() method is overloaded to accept several combinations of arguments, and includes 11 variants. For more information on methods used to construct the message body, see the Javadoc for oracle.ifs.adk.mail.IfsMessage.
Here are some basic guidelines:
The setMixedBodies() method will meet most application needs for sending any message with an attachment. The multipart/mixed content type is the most general MIME content type, and can be used for any multipart message or any message with attachments. The client is free to choose the method to display the message. Generally, the different body parts are treated as different parts of the message; that is, they are treated the same as if they were attachments.
When you pass only a single parameter to setMixedBodies(), rather than an array, setMixedBodies has the same effect as the setBody() method.
Use setAlternativeBodies() to specify alternative formats for use by specific browsers. A multipart/alternative body is a body of multiple body parts of the same content but in different formats. A compatible client should choose the most appropriate format to display the message to the user.
The content type of the message is always multipart/alterative if the message does not have attachments. Otherwise, the message content type will be multipart/mixed with a nested multipart/alternative message.
When you pass only a single parameter to setAlternativeBodies(), rather than an array, setAlternativeBodies() has the same effect as the setBody() method.
Use setParallelBodies() when all attachments are of a format that can be displayed following the message, rather than included as a separate file. A multipart/parallel body is a message body with multiple body parts that should be viewed in parallel using a compatible client.
The content type of the message is always multipart/parallel if the message does not have attachments. Otherwise, the message content type will be multipart/mixed with a nested multipart/parallel message.
When you pass only a single parameter to setParallelBodies(), rather than an array, setParallelBodies() has the same effect as the setBody() method.
msg.setBody("Hello there! This is a simple string body.");
//Construct a multipart message body using setAlternativeBodies(). MimeBodyPart[] bodies = new MimeBodyPart[2]; bodies[0] = new MimeBodyPart("Hello, this is plain text.", "text/plain", null); bodies[1] = new MimeBodyPart("<html><body>Hello, this is HTML text " + ".</body></html>", "text/html", null); msg.setAlternativeBodies(bodies);
In this example, note the class MimeBodyPart. MimeBodyPart is a class that represents a single body part of a multipart MIME message. This class provides a means to group the essential information of a message body part into a single class for ease of storage and retrieval. MimeBodyPart is an inner class of the IfsMessage class; many methods of IfsMessage accept MimeBodyPart objects as arguments.
// Add a document object attachment. msg.attach(doc);
To send the message, use the oracle.ifs.adk.mail.IfsMessage.send() method, with no arguments. The only validation the send() method performs is to be sure that one of the recipient fields is set (To, CC, or BCC). All other validation is performed by the outgoing e-mail protocol. The Outbox agent will automatically pick up messages from the outbox. The Outbox agent passes all messages to the SMTP port on the local machine.
msg.send();
Note that this method will return the following error messages if the message cannot be sent:
package oracle.ifs.adk.mail; /* --IfsMailTest.java-- */ import oracle.ifs.beans.DirectoryUser; import oracle.ifs.beans.Document; import oracle.ifs.beans.FolderPathResolver; import oracle.ifs.beans.LibrarySession; import oracle.ifs.common.IfsException; import oracle.ifs.beans.LibraryService; import oracle.ifs.protocols.email.beans.Mailbox; import oracle.ifs.adk.mail.IfsMessage.MimeBodyPart; public class IfsMailTest { public static void main(String[] args) { try { // Setting up the service, session, and user LibraryService service = new LibraryService(); ClearTextCredential me = new ClearTextCredential("tuser1", "tuser1"); ConnectOptions options = new ConnectOptions(); options.setLocale(Locale.getDefault()); LibrarySession session = service.connect(me, options); DirectoryUser user = (DirectoryUser) session.getDirectoryUser(); if (user.isAdminEnabled()) session.setAdministrationMode(true); IfsMessage msg = new IfsMessage(session); // Example 1 // Creating a simple message being sent to two destinations. // The message has a simple string body. // IfsMessage msg = new IfsMessage(session); msg.setToHeader(new String[] {"guest@us.oracle.com", "tuser51@us.oracle.com"}); msg.setFromHeader("tuser99@us.oracle.com"); msg.setSenderHeader(user); msg.setCcHeader("tuser51@us.oracle.com"); msg.setBccHeader("tuser51@us.oracle.com"); msg.setContentType("text/plain"); msg.setSubject("iFS email API: Mail with body and multiple recipients"); msg.setBody("Hello there! This is a simple string body"); msg.send(); //Example 2 // Creating a simple message being sent to two destinations. // The message has a multipart alternative structure. // IfsMessage msg = new IfsMessage(session); msg.setFromHeader("tuser99@us.oracle.com"); msg.setSenderHeader(user); msg.setToHeader("guest@us.oracle.com"); msg.setBccHeader("tuser51@us.oracle.com"); msg.setSubject("iFS email API: Mail with multi-part body"); MimeBodyPart[] bodies = new MimeBodyPart[2]; bodies[0] = new MimeBodyPart("hello this is plain text.", "text/plain", null); bodies[1] = new MimeBodyPart("<html><body>hello this is a html text " + ".</body></html>", "text/html", null); msg.setAlternativeBodies(bodies); msg.send(); //Example 3 // Creating a simple message being sent to two destinations. // The message has a multipart mixed structure. // IfsMessage msg = new IfsMessage(session); msg.setFromHeader("tuser99@us.oracle.com"); msg.setSenderHeader(user); msg.setToHeader("guest@us.oracle.com"); msg.setCcHeader("tuser51@us.oracle.com"); bodies = new MimeBodyPart[3]; bodies[0] = new MimeBodyPart("This is plain text again.", "text/plain", null); bodies[1] = new MimeBodyPart("<html><body>This is html text. " + "</body></html>", "text/html", IfsMessage.ASCII_CHARSET); bodies[2] = new MimeBodyPart("<html><body>hello this is another html " + "text.</body></html>", "text/html", IfsMessage.ISO88591_CHARSET); msg.setMixedBodies(bodies); // // Associate attachments for Example 3. // FolderPathResolver resolver = new FolderPathResolver(session); Document doc = (Document) resolver.findPublicObjectByPath( "/home/tuser1/test.txt"); msg.attach(doc); doc = (Document) resolver.findPublicObjectByPath("/home/tuser1/test.jpg"); msg.attach(doc); msg.send(); } catch (IfsException e) { e.printStackTrace(); } } }