3 Design-Time and Run-Time Concepts

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.

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.

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 scott@tiger.com.

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.

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.

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);

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.
...

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.

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.

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.

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);

   }

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);

   }

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.