3 Design-Time and Run-Time Concepts

This chapter describes the design-time and run-time concepts for the Simple Mail Transfer Protocol (SMTP) adapter. It contains the following topics:

• SMTP Adapter Design-Time Concepts

• SMTP Adapter Run-Time 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 D3L structured payloads, such as pure XML data with strings beginning with <xml..., and binary data described by a D3L XML file.

XML Payload

You can import a Document Type Definition (DTD) or XML Schema Definition (XSD) in iStudio to determine how the SMTP adapter parses a received XML document into an OracleAS Integration InterConnect application view event. In addition, you can use the XSD or DTD to describe how an inbound application view message is converted to an XML document. Use the message type option XML when defining a new integration point in any of the event wizards.

Ensure that the ota.type parameter in the adapter.ini file is set to XML, instead of D3L.

When the SMTP adapter operates in the XML payload mode, no transformations are performed on the messages between native view and application view. Any Extensible Stylesheet Language Transformations (XSLT) should be performed either before sending an XML document to OracleAS Integration InterConnect or after receiving one from OracleAS Integration InterConnect.

D3L Payload

The SMTP adapter performs a two-way conversion and transformation of messages between application view and native format.

An application based on the SMTP adapter can use the iStudio Message Type D3L and the iStudio D3L Data Type Import options when importing a data type. In this case, messages received or sent by the SMTP adapter must adhere to the fixed byte-level layout defined in a D3L XML file.

The D3L Data Type Import option can also define common view data types.

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

SMTP Adapter Run-Time Concepts

This section describes the key run-time components of the SMTP adapter. It contains the following topics:

• SMTP Receiver

• SMTP Sender

• SMTP Adapter Message Format

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.

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

During each polling interval, the SMTP receiver:

• 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. You can configure the maximum number of e-mails processed for each session through the smtp.receiver.max_msgs_retrieved parameter of the adapter.ini file.

The polling interval is configured using the smtp.receiver.polling_interval parameter of the adapter.ini file.

The SMTP bridge uses the D3L XML file based on name/value pairs or magic value message header attributes (a sequence of bytes in the native format message header). The SMTP bridge uses this information to parse from the native message to an OracleAS Integration InterConnect message object and translate it to an application view event. The agent converts the application view event to a common view event and passes it to OracleAS Integration InterConnect for further routing and processing.

Once the message is successfully passed to OracleAS Integration InterConnect, the corresponding e-mail residing on the IMAP server is marked to be deleted, and is deleted at the end of each session. An exception folder on the IMAP server can be specified for storing the unsuccessfully processed e-mails. The exception folder can be set using the smtp.receiver.exception_folder parameter in the adapter.ini file. If no exception folder is set, then the mail is deleted.

The properties for the SMTP receiver are defined in the adapter.ini file in smtp.receiver.* format.

Note: The adapter subscribing to an event should be started before any other adapter can publish that event. If you publish an event before starting the subscribing adapter, then the event would not be delivered to the subscribing adapter.

See Also: Oracle Application Server Integration 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 consists of the SMTP bridge and the run-time 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 the common view object to the native format. The native format message is then sent through the SMTP transport layer to an SMTP endpoint.

The SMTP adapter's sending endpoint is written as follows:

mailto:username@hostname

The subject header of each message sent by the SMTP adapter is automatically generated by the adapter and is in the following syntax:

SMTP_adapter_application_namepartition-time_stamp

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

• %APP%: application name

• %BO%: business object name

• %EVENT%: corresponding event name

• %MV%: message version

• %PART%: partition number

• %TIME%: time stamp

• %TYPE%: message type

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

The SMTP adapter supports sending outgoing messages from OracleAS Integration InterConnect to multiple SMTP endpoints. The multiple endpoints feature enables sending messages to various remote mail servers.

An endpoint is associated with a subscribing event in iStudio by adding the transport properties for the SMTP endpoint as metadata for the event. This is done using the Modify Fields function of the Subscribe Wizard - Define Application View dialog box. After associating an endpoint and an event, the message from the subscribing event is sent to the SMTP endpoint.

When using the multiple endpoint feature with XML data type, you must use the Generic event type, instead of XML. Using the Generic event type enables you to enter the metadata for the endpoints using the Modify Fields feature associated with iStudio.

Table 3-1 shows how metadata is associated with an event called sendOrder that sends messages to an e-mail account [e-mail].

Table 3-1 SendOrder Event Metadata

Parameter	Description
ota.endpoint=sendOrderAppEP	Specifies a unique endpoint name set in iStudio
ota.send.endpoint=mailto:[e-mail]	Specifies the sending endpoint for the SMTP adapter

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

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

The properties for the SMTP sender are defined in the adapter.ini file in smtp.sender.* format.

See Also: Figure 1-2, "Outgoing Messages" "SMTP Adapter-Specific Parameters" Chapter 4 of the Oracle Application Server Integration 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, then the message format is binary or plain text. The message must be sent or received as one part Multipurpose Internet Mail Extension (MIME), 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. Refer to 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 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 customize the adapter behavior by implementing the following interfaces:

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

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

The ReceiverCustomizer Interface

You can use the ReceiverCustomizer interface to customize the TransportMessage object that is received by the SMTP adapter. The TransportMessage object represents the native message that the transport layer receives or sends.

• If you wish to customize the TransportMessage object itself, then use the customizeTransportMessage() method. This method is called before the adapter processes the TransportMessage object.

• If you wish to modify the message itself, then implement the customizeTransportMessage() method. You must also implement the createReplyMessage() method and ensure that it returns a null value.

The following code describes the file structure of the ReceiverCustomizer 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);
}

The following table summarizes the ReceiverCustomizer interface.

Methods	Description
customizeTransportMessage();	Enables you to customize the transport message received by the adapter. It uses the following parameters: agent: Log a message receiverType: Information on the type of adapter transportMessage: Customize the transport message received by the adapter
createReplyMessage();	Creates a reply message based on the status of the message received. It contains the following parameters: agent: Log a message status: Status of the message process. If the value is TransportResponse.TRANSPORT_ACK, then the message has been processed successfully. If the value is TransportResponse.TRANSPORT_ERROR, then the message has not been processed successfully. receivedTransportMessage: Transport message received by the adapter. This parameter is used to transport headers in the transport message to create a meaningful message. The return string contains the reply message. This method is used for backward compatibility for the SMTP adapter. However, for the SMTP adapter, you should return a null value with this method.

Example 3-3 Example of ReceiverCustomizer Interface

The MyReceiverCustomizer class to remove 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 Integration InterConnect does not understand.
   public void customizeTransportMessage(Agent agent, int receiverType,
                                         TransportMessage transportMessage)
   {
      String payload = transportMessage.getBodyAsString();
// 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) {
      . . . . 
      }
   }
// 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;
   }
}

List of Methods for the TransportMessage Class

The following table provides a list of methods you can use for the TransportMessage class.

Method	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. Parameters: body: body of the messageIt throws an exception of type TransportException.
public void setBody(InputStream in) throws TransportException;	Set the body of the message. The body type will be set to BYTES. Parameters: InputStream: Contains the message. It throws an exception of type 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.

The 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()

If you do not want to implement the generateSubjectName() method, then 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 need to implement only the customizeTransportMessage() method.

The SenderCustomizer Interface

The following code describes 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);

   }

Thw customizeTransportMessage method

This method specifies how to customize the transport message for transporting the sender. The adapter creates a TransportMessage object for the transport layer to send, based on the MessageObject object sent by OracleAS Integration InterConnect.

This method contains the following parameters:

• agent: Log messages

• transportMessage: The TransportMessage object that the adapter has created for sending.

• mobj: The MessageObject from OracleAS Integration InterConnect.

• aobj: The AttributeObject from OracleAS Integration InterConnect.

This method does not return anything. You can change the payload with the transportMessage parameter.

The SMTPSenderCustomizer Interface

The following code describes 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;

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

   }

The generateSubjectName method

This method generates an subject name for e-mail. It contains the following parameters:

• agent: Use the Agent object to log message.

• rule: Rule for generating subject. This parameter is read from smtp.sender.subjectRule in the adapter.inifile.

• app: The application name.

• partition: Partition.

• time: The time the OracleAS Integration InterConnect object is received.

• mobj: A MessageObject passed from OracleAS Integration InterConnect.

• aobj: An AttributeObject passed from OracleAS Integration InterConnect.

This method returns a string representing the subject name.

Starting the SMTP Adapter

The process for starting the adapter varies based on the operating system.

• To start the SMTP adapter on UNIX:

  1. Change to the directory containing the start script.

     cd ORACLE_HOME/integration/interconnect/adapters/Application
     
     

  2. Type start and press Enter.

• To start the SMTP adapter from Services on Windows.

  1. Access the Services window from the Start menu.

  2. Select the OracleHomeOracleASIntegrationInterConnectAdapter-Application service.

  3. Start the service.

     
     

     Note: You can also start and stop the SMTP adapter using the IC Manager. Refer to OracleAS Integration InterConnect User’s Guide for more details.

     
     

Log File of SMTP Adapter

You can verify the startup status by viewing the log.xml files. The files are located in the time-stamped subdirectory of the log directory of the SMTP adapter. Subdirectory names have the following form:

timestamp_in_milliseconds

The following is an example of the information about an SMTP adapter that started successfully:

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

The process for stopping the adapter varies based on the operating system.

• To stop the SMTP adapter on UNIX:

  1. Change to the directory containing the stop script.

     cd ORACLE_HOME/integration/interconnect/adapters/Application
     
     

  2. Type stop and press Enter.

• On Windows, stop the SMTP adapter from Services.

  1. Access the Services window from the Start menu.

  2. Select the OracleHomeOracleASInterConnectAdapter-Application service.

  3. Stop the service.

  You can verify the stop status of the SMTP adapter by viewing the log.xml files. These files are located in the time-stamped subdirectory of the log directory of the SMTP adapter.

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 Integration InterConnect User's Guide for information on the retry action