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

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: Oracle9iAS InterConnect User's Guide 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 Oracle9iAS 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) are performed before sending or receiving an XML document to or from Oracle9iAS 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: Oracle9iAS InterConnect User's Guide 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 (Incoming Messages from IMAP Server to Oracle9iAS InterConnect)

• SMTP Sender (Outgoing Messages from Oracle9iAS InterConnect to SMTP Server)

• SMTP Adapter Message Format

• Starting the SMTP Adapter

• Stopping the SMTP Adapter

• SMTP Adapter Error Codes

  See Also: Oracle9iAS InterConnect User's Guide for a use case example involving an Oracle adapter, the Advanced Queuing adapter, and D3L

SMTP Receiver (Incoming Messages from IMAP Server to Oracle9iAS InterConnect)

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 (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, it uses D3L XML 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 Oracle9iAS 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 Oracle9iAS InterConnect for further routing and processing.

Once the message is successfully sent to Oracle9iAS 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: Oracle9iAS InterConnect User's Guide 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 (Outgoing Messages from Oracle9iAS InterConnect to SMTP Server)

The SMTP adapter supports sending outgoing messages 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:[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 SMTP adapter's sending endpoint set in the adapter.ini file.

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_nameinstance_number-time_stamp

For example, for an SMTP application named smtpapp (the value for SMTP_adapter_application_name) with an instance number of 1 (the value for instance_name), the subject header generated by the SMTP sender object is smtpapp1-004408921310. This information is useful in debugging an SMTP adapter application.

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

Starting the SMTP Adapter

Start the SMTP adapter using the start script located in the directory named after the Oracle SMTP application. On Windows NT or Windows 2000, you can also start it from the Services window available from the Start menu.

To start the SMTP adapter:

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 OracleHome9iASInterConnectAdapter-Application service.

3. Start the service based on the operating system being used:

   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

Verify startup status by viewing the oailog.txt files. These files are located in the appropriate timestamped subdirectory of the logs 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\ora902\oai\9.0.2\adapters\smtpapp>D:\oracle\ora902\oai\9.0.2\bin\JavaS
ervice.exe -debug "Oracle OAI Adapter 9.0.2 -
smtpapp" D:\oracle\ora9021\oai\9.0.2\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

Stop the SMTP adapter using the stop script located in the directory named after the Oracle SMTP application. On Windows NT or Windows 2000, you can also stop it from the Services window available from the Start menu.

To stop the SMTP adapter:

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 OracleHome9iASInterConnectAdapter-Application service.

3. Stop the service based on the operating system being used:

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

   Verify stop status by viewing the oailog.txt files. These files are located in the appropriate timestamped subdirectory of the logs 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: Oracle9iAS InterConnect User's Guide for information on the retry action