3
Design Time and Runtime Concepts

This chapter describes the design time and runtime concepts for the Simple Mail Transfer Protocol (SMTP) adapter.

This chapter contains these topics:

• SMTP Adapter Design Time Concepts

• SMTP Adapter Runtime Concepts

• Customizing the SMTP Adapter

• Starting the SMTP Adapter

• Stopping the SMTP Adapter

• SMTP Adapter Error Codes

SMTP Adapter Design Time Concepts

The SMTP adapter can handle XML and the data definition description language (D3L) structured payload data. For example:

• Pure XML data--string beginning with <?xml . . .

• Fixed layout, typically binary data described by a D3L XML file

  See Also: Oracle Application Server InterConnect User's Guide, Appendix B, for additional information on D3L

XML Payload

You can import a document type definition (DTD) in iStudio that determines how the SMTP adapter parses a received XML document into an Oracle Application Server InterConnect application view event. In addition, the DTD describes how an inbound application view message is converted into an XML document. Use the message type XML when defining a new integration point in any of the Event Wizards.

You must also ensure that the ota.type parameter in the adapter.ini file is set to XML instead of D3L. When the adapter operates in XML payload mode, no translations are performed between native view and application view messages sent or received through the SMTP adapter. This is apart from the implied straight ASCII to Java object conversion (parsing). Any Extensible Stylesheet Language Transformations (XSLT) should be performed before sending or receiving an XML document to or from Oracle Application Server InterConnect.

D3L Payload

The SMTP adapter supports both XML and D3L datatypes. The SMTP adapter translates application view messages to native format and vice versa.

An application based on the SMTP adapter can use the iStudio Message Type D3L and the iStudio D3L Data Type Import option when importing a datatype. In doing so, messages received or sent by the SMTP adapter must adhere to the fixed byte level layout defined in a D3L XML file.

If preferred, the D3L Data Type Import option can also define common view datatypes.

See Also: Oracle Application Server InterConnect User's Guide, Appendix B, for additional information on D3L and common view datatypes

SMTP Adapter Runtime Concepts

This section describes the two main SMTP adapter components.

This section contains these topics:

• SMTP Receiver

• SMTP Sender

• SMTP Adapter Message Format

  See Also: Oracle Application Server InterConnect User's Guide, Appendix B, for an example involving an Oracle adapter, the Advanced Queuing adapter, and D3L

SMTP Receiver

The SMTP adapter receives incoming messages from a single receiving endpoint, which is an e-mail address on an Internet Message Access Protocol (IMAP) server, to Oracle Application Server InterConnect.

The endpoint is of the form: imap://username@imapHostName

During each polling interval (configurable with the adapter.ini file smtp.receiver.polling_interval parameter), the SMTP receiver performs the following tasks:

• Polls the IMAP server for incoming e-mails

• Processes each e-mail

• Transforms the e-mail message into a transport message processed by the SMTP bridge. The maximum number of e-mails processed for each session is user configurable with the adapter.ini file smtp.receiver.max_msgs_retrieved parameter.

Once the SMTP bridge detects a message, in the case of D3L payload, it uses a D3L definition selected based on the name-value pair or magic value message header attributes (a sequence of bytes in the native message header) to parse from native format to an Oracle Application Server InterConnect message object and generates an application view event. The agent transforms the application view event into a common view event and sends it to Oracle Application Server InterConnect for further routing and processing.

Once the message is successfully sent to Oracle Application Server InterConnect, the corresponding e-mail residing on the IMAP server is marked to be deleted, and is deleted at the end of each session. In the event that an error occurs, the IMAP server administrator can specify an exception folder on the IMAP server for storing the unsuccessfully processed e-mails with the adapter.ini file smtp.receiver.exception_folder parameter. If no exception folder is set, the mail is deleted.

The properties for the SMTP receiver are defined in the adapter.ini file and take the form of smtp.receiver.*.

See Also: Oracle Application Server InterConnect User's Guide, Appendix B, for additional information on D3L name-value pair and magic value message header attributes Figure 1-1, "Incoming Messages" "SMTP Adapter-Specific Parameters"

SMTP Sender

The SMTP adapter supports sending outgoing messages from Oracle Application Server InterConnect to multiple SMTP endpoints. This feature provides flexibility for sending messages to different remote SMTP servers. An endpoint is associated with a subscribing event in iStudio by adding the transport properties for this endpoint as metadata. This is done through the Modify Fields button of the Subscribe Wizard - Define Application View dialog for the event. Once the association of the endpoint and event is established, the message from the subscribing event is sent to the SMTP endpoint.

For example, the metadata in Table 3-1 is associated with an event called sendOrder, which sends messages to an e-mail account mailto:scott@tiger.com.

Table 3-1 SendOrder Event Metadata

Parameter	Description
ota.endpoint=sendOrderAppEP	Specifies a unique endpoint name set in iStudio
ota.send.endpoint=mailto:scott@tiger.com	Specifies the SMTP adapter's sending endpoint

If no metadata is associated with an event in iStudio, the endpoint specified by the ota.send.endpoint parameter in the adapter.ini file is used as the default endpoint.

The SMTP adapter is comprised of the SMTP bridge and the runtime agent. When the agent has a message to send to an endpoint, the bridge is notified. The bridge then uses D3L XML to perform the conversion of common view object to native format. The native format message is then sent through the SMTP transport layer to an SMTP endpoint.

The SMTP adapter's sending endpoint takes the following form:

mailto:username@hostname

The multiple endpoint feature enables messages to be sent to different SMTP servers. The subject header of each message sent by the SMTP adapter is automatically generated in the following form:

SMTP_adapter_application_namepertition-time_stamp

Note: When using the multiple-endpoint feature with XML data type, you must choose the event type of Generic, instead of XML. Using the Generic event type allows you to enter the metadata for the endpoints via the Modify Fields feature associated with iStudio.

Note: The sender properties are not inherited from the adapter.ini file.

The user can specify a rule for generating the file name when the SMTP adapter sends an email. To use this feature, the user has to add the parameter, smtp.sender.subject_rule, in the adapter.ini file. The adapter recognizes the following tokens:

%APP%--application name

%PART%--partition number

%BO%--business object name

%TYPE%--message type

%EVENT%--corresponding event name

%TIME%--time stamp

%MV%--message version

For example,

smtp.sender.subject_rule=Message_from_%APP%_%EVENT%_%TIME%

This rule instructs the SMTP adapter to generate subject with the following pattern:

Message_from_<your app name>_<event name>_<current time stamp>

If the above rule does not serve your needs, you can write your own customization rule by implementing the following interface:

oracle.oai.adapter.agent.technology.SMTPSenderCustomizer

The properties for the SMTP sender are defined in the adapter.ini file and take the form of smtp.sender.*.

See Also: Figure 1-2, "Outgoing Messages" "SMTP Adapter-Specific Parameters" Chapter 4 of the Oracle Application Server InterConnect User's Guide for information on adding transport properties as metadata in iStudio

SMTP Adapter Message Format

This section describes how to extract and send messages to the SMTP adapter for different types of payloads.

If the SMTP adapter operates in D3L mode (the ota.type parameter is set to D3L in the adapter.ini file), the message format is binary or plain text. The SMTP adapter expects the message to be sent or received as a one part Multipurpose Internet Mail Extension (MIME) message with the data encoded in base64. Example 3-1 shows how to send the message to the SMTP adapter in MIME format using the JavaMail API:

Example 3-1 Sending Messages to the SMTP Adapter

Message smtpMessage = new MimeMessage(session);
String msg = new String("This is a test.");
MimeBodyPart part = new MimeBodyPart();

// create a multipart object
Multipart mp = new MimeMultipart(); 
DataSource dataSource = new BytesDataSource(msg.getBytes());
part.setDataHandler(new DataHandler(dataSource));         
part.setHeader("Content-Transfer-Encoding", "base64");
mp.addBodyPart(part);
smtpMessage.setContent(mp);
...
Transport.send(smtpMessage);

In Example 3-1, BytesDataSource is a user-written class that implements the DataSource class, which represents a data source consisting of a byte array. See the JavaMail API for additional information.

Example 3-2 shows how to extract the multipart message sent from the SMTP adapter when it operates in D3L mode.

Example 3-2 Extracting Messages Sent from the SMTP Adapter

Object o  = message.getContent();
Multipart mp = (Multipart)o;

// The message is contained in the
// first part. 
BodyPart part = mp.getBodyPart(0);
InputStream is = (InputStream)part.getContent();

// extract the data from input stream.
...

When the SMTP adapter operates in XML mode (the ota.type parameter is set to XML in the adapter.ini file), the message is sent or received in simple text format, as described in RFC 822. To send a message to the SMTP adapter, use the javax.mail.Message.setText() method in the JavaMail API.

Customizing the SMTP Adapter

You can modify some of the SMTP adapter behaviors by implementing the following two interfaces:

• oracle.oai.adapter.agent.technology.ReceiverCustomizer

• oracle.oai.adapter.agent.technology.SMTPSenderCustomizer

ReceiverCustomizer Interface

You can use the ReceiverCustomizer interface to customize the TransportMessage object that is received by the SMTP adapter. The customizeTransportMessage() method can be used to customize the TransportMessage object before the adapter processes it. The TransportMessage object represents the native message that the transport layer receives or sends.

File Structure

The following is the file structure of this interface.

package oracle.oai.agent.adapter.technology;
import oracle.oai.agent.adapter.transport.TransportMessage;
import oracle.oai.agent.adapter.sdk.Agent;
public interface ReceiverCustomizer {

   public void customizeTransportMessage(Agent agent, int receiverType, 
                                         TransportMessage transportMessage);
   public String createReplyMessage(Agent agent, int status, 
                                    TransportMessage receivedTransportMessage);
}

File Summary

The following table summarizes the ReceiverCustomizer Interface.

Methods	Description
customizeTransportMessage();	This method allows you to customize the transport message, Message, received by the adapter. It contains the following parameters: agent--Used to log a message. receiverType--Provides information on the type of adapter. transportMessage--Used to customize the transport message received by the adapter.
createReplyMessage();	This method creates a reply message, Message, based on the status and the message received. This method is used for backward compatibility. It contains the following parameters: agent--Used to log a message. status--The status of the message process. If the value is TransportResponse.TRANSPORT_ACK, the message is processed successfully. If the value is TransportResponse.TRANSPORT_ERROR, the message is processed unsuccessfully. receivedTransportMessage--The transport message is received by the adapter. This parameter is used to transport headers in the transport message to create a meaningful HTTP message. The return string contains the reply message. However, this method is used by the HTTP adapter. For the SMTP adapter, you should return a null value with this method.

Example 3-3 Example of ReceiverCustomizer Interface

The MyReceiverCustomizer class removes the first line in the native message.

import oracle.oai.agent.adapter.sdk.Agent;
import oracle.oai.agent.adapter.transport.TransportMessage;
import oracle.oai.agent.adapter.transport.TransportException;
import oracle.oai.agent.adapter.technology.ReceiverCustomizer;

public class MyReceiverCustomizer implements ReceiverCustomizer {

This example describes how to remove an extra line from an email that OracleAS InterConnect does not understand.

   public void customizeTransportMessage(Agent agent, int receiverType,
                                         TransportMessage transportMessage)
   {
      String payload = transportMessage.getBodyAsString();

Note: For debugging purposes only, the following syntax removes the first line from the payload. Details of removeFirstLine() is not provided.

      agent.logTraceMessage("payload received = " + payload, null, null, null);
      String newPayload = removeFirstLine(payload);

      try {
         transportMessage.setBody(newPayload);  
      }
      catch(TransportException te) {
      . . . . 
      }
   }

Note: For the SMTP adapter, a null string from the following method will be returned.

   public String createReplyMessage(Agent agent, int status,
                                    TransportMessage receivedTransportMessage)
   {  
   return null;
   }
}

Example 3-4 List of Methods for the TransportMessage Class

This example provides a list of methods you may choose for the TransportMessage class.

Methods	Description
public String toString();	Dump messages and headers.
public void setTransportHeader(String name, String value);	Set a transport-specific header.
public Properties getTransportHeaders();	Get all transport-specific headers and return a Properties object that contains all the transport headers.
public void setBody(String body) throws TransportException;	Set the body of the message. The body type will be set to STRING. Parameter includes: body--body of the message It throws a TransportException.
public void setBody(InputStream in) throws TransportException;	Set the body of the message. The body type will be set to BYTES. Parameter includes: InputStream--Contains the message. It throws a TransportException.
public String getBodyAsString();	Get the body of the message as String object. Return the message in String object.
public byte[] getBodyAsBytes();	Get the body of the message as byte array. Return the message in byte[].
public InputStream getBodyAsInputStream();	Get the body of the message and return an InputStream object representing the body of the message.

SMTPSenderCustomizer Interface

You can use the SMTPSenderCustomizer interface to customize the subject name and payload of the TransportMessage object that is sent to the transport layer. The SMTPSenderCustomizer interface extends the SenderCustomizer interface. You must implement the SMTPSenderCustomizer interface by implementing the following two methods:

• SMTPSenderCustomizer.customizeTransportMessage()

• SMTPSenderCustomizer.generateSubjectName()

However, if you do not want to implement the more complicated generateSubjectName() method, you can create a class that extends the oracle.oai.agent.adapter.technology.SMTPDefaultSenderCustomizer class, which is provided in the oai.jar file. In this case, you only need to implement the customizeTransportMessage() method.

SenderCustomizer Interface

File Structure

The following is the file structure of the SenderCustomizer interface.

package oracle.oai.agent.adapter.technology;

import oracle.oai.agent.adapter.sdk.MessageObject;
import oracle.oai.agent.adapter.sdk.AttributeObject;
import java.util.Properties;
import oracle.oai.agent.adapter.sdk.Agent;
import oracle.oai.agent.adapter.transport.TransportMessage;

   public interface SenderCustomizer {

   public void customizeTransportMessage(Agent agent,
                                         TransportMessage transportMessage,
                                         MessageObject mobj,
                                         AttributeObject aobj);

   }

File Summary

The following table summarizes the customizeTransportMessage method.

Method

Description

customizeTransportMessage ();

This method specifies how to customize the transport message for transporting sender. The adapter creates a TransportMessage for the transport layer to send based on the MessageObject sent by OracleAS InterConnect. You can use this method to further customize the transport message that is to be sent out by the transport layer. This method contains the following parameters: agent--Can be used to log message. transportMessage--Indicates the TransportMessage object that the adapter has created for sending. mobj--Indicates the MessageObject from OracleAS InterConnect. aobj--Indicates the AttributeObject from OracleAS InterConnect. This method does not return anything. You can change the payload with the transportMessage parameter.

SMTPSenderCustomizer Interface

File Structure

The following is the file structure of the SMTPSenderCustomizer interface.

package oracle.oai.agent.adapter.technology;

import java.util.Date;
import oracle.oai.agent.adapter.sdk.MessageObject;
import oracle.oai.agent.adapter.sdk.AttributeObject;
import oracle.oai.agent.adapter.sdk.Agent;

package oracle.oai.agent.adapter.technology;

import oracle.oai.agent.adapter.sdk.MessageObject;
import oracle.oai.agent.adapter.sdk.AttributeObject;
import java.util.Date;
import oracle.oai.agent.adapter.sdk.Agent;

   public interface SMTPSenderCustomizer extends SenderCustomizer {
      public String generateSubjectName(Agent agent,
                                        String rule,
                                        String app,
                                        String partition,
                                        Date time,
                                        MessageObject mobj,
                                        AttributeObject aobj);

   }

File Summary

The following table summarizes the generateSubjectName method.

Method

Description

generateSubjectName ();

This method generates an subject name for email. It contains the following parameters: agent--Indicates that the user can use the Agent object to log message. rule--Indicates Rule for generating subject. This is read from smtp.sender.subjectRule in adapter.ini. app--Indicates the application name. partition--Indicates Partition. time--This is a Date object which indicates the time the object is received. mobj--Indicates a MessageObject passed from OracleAS InterConnect. aobj--Indicates an AttributeObject passed from OracleAS InterConnect. This method returns a string representing the file name.

Starting the SMTP Adapter

On UNIX, start the SMTP adapter using the start script located in the following directory:

ORACLE_HOME/oai/9.0.4/adapters/Application

Type start, then press Enter.

On Windows, start the SMTP adapter from the Services window available from the Start menu.

1. Access the Services window from the Start menu:

   On...	Choose...
   Windows NT	Start > Settings > Control Panel > Services
   Windows 2000	Start > Settings > Control Panel > Administrative Tools > Services

   The Services window appears.

2. Select the OracleHomeOracleASInterConnectAdapter-Application service.

3. Start the service based on the operating system:

   On...	Choose...
   Windows NT	Choose Start.
   Windows 2000	Right-click the service and choose Start from the menu that appears.

   See Also: "SMTP Adapter Configuration Parameters" for the location of the start script

Log File Example of Successfully Started SMTP Adapter

You can verify the startup status by viewing the oailog.txt files. These files are located in the appropriate timestamped subdirectory of the log directory of the SMTP adapter directory. Subdirectory names take the following form:

timestamp_in_milliseconds

The following file displays information about an SMTP adapter that started successfully:

D:\oracle\ora904\oai\9.0.4\adapters\smtpapp>D:\oracle\ora904\oai\9.0.4\bin\JavaS
ervice.exe -debug "Oracle OAI Adapter 9.0.4 -
smtpapp" D:\oracle\ora904\oai\9.0.4\adapters\smtpapp adapter.ini 
The Adapter service is starting.. 
Registering your application (SMTPAPP).. 
Initializing the Bridge oracle.oai.agent.adapter.technology.TechBridge.. 
Starting the Bridge oracle.oai.agent.adapter.technology.TechBridge.. 
Service started successfully. 

Stopping the SMTP Adapter

On UNIX, stop the SMTP adapter using the stop script located in the following directory named after the Oracle HTTP application.

ORACLE_HOME/oai/9.0.4/adapters/Application

Type stop, then press Enter.

On Windows, stop the SMTP adapter from the Services window available from the Start menu.

1. Access the Services window from the Start menu:

   On...	Choose...
   Windows NT	Start > Settings > Control Panel > Services
   Windows 2000	Start > Settings > Control Panel > Administrative Tools > Services

   The Services window appears.

2. Select the OracleHomeOracleASInterConnectAdapter-Application service.

3. Stop the service based on the operating system:

   On...	Choose...
   Windows NT	Choose Stop.
   Windows 2000	Right-click the service and choose Stop from the menu that appears.

   You can verify the stop status by viewing the oailog.txt files. These files are located in the appropriate timestamped subdirectory of the log directory of the SMTP adapter directory.

   See Also: "SMTP Adapter Configuration Parameters" for the location of the stop script

SMTP Adapter Error Codes

This section defines the error codes (derived from the JavaMail exception) that the SMTP adapter returns in the event of an exception.

OTA-IMAP-1002
Reason: Authentication failed due to bad user name or password.
Action: Check user name or password.

OTA-IMAP-1003
Reason: Folder closed exception is thrown when a method is invoked on
an invalid Messaging Object or Folder Object.
Action: None.

OTA-IMAP-1004
Reason: Message removed exception. A method is invoked on an expunge message.
Action: None.

OTA-IMAP-1005
Reason: Read-only folder exception. Tried to write to a read-only folder.
Action: Check the properties of the folder. Make sure it has the correct write
privilege.

OTA-SMTP-1001
Reason: Message cannot be sent exception.
Action: Make sure the email address for sending is valid.

See Also: Oracle Application Server InterConnect User's Guide for information on the retry action