Using Email Transport to receive e-mail

Oracle Service Bus offers the Email Transport for both receiving and sending e-mails.

In this recipe, we will show how we can set up a proxy service to listen on a mailbox for new e-mail messages. For each new e-mail message, the message processing as defined in the message flow of the proxy service is executed.

Using Email Transport to receive e-mail

Getting ready

In order to be able to receive e-mails on the OSB, we need a running mailserver. We could connect to an already existing e-mail server, but for this recipe to be standalone, we will use the Apache James mailserver. Perform the following steps for the installation of Apache James on the local machine:

  1. Download the latest version of Apache James binary from: http://james.apache.org/download.cgi#Apache_James_2.3.2_is_the_stable_version.
  2. Unzip the file into a local folder.
  3. Navigate to the bin folder within the Apache James binaries.
  4. Locate and execute the run.bat.
    Getting ready
  5. Open a command window and open a telnet session by entering telnet localhost 4555.
  6. Enter root on the Login id prompt.
  7. Enter root on the Password prompt.
  8. Create a new user by entering the command adduser <user> <password>.
  9. Create the osbuser and osbadmin user.
    Getting ready
  10. List the users by entering the listusers command.
  11. Enter quit to exit the telnet session and close the command window.

    Now, let's install an e-mail client in order to send and receive e-mails. We will use Mozilla Thunderbird here, but it can be replaced by any other e-mail client. Perform the following steps to set up Thunderbird:

  12. Download and install Mozilla Thunderbird from: http://www.mozilla.org/en-US/thunderbird/.
  13. Start Thunderbird by double-clicking on the icon installed on the desktop.
  14. On the main window click Create a new account.
  15. Enter OSB User into the Your name field.
  16. Enter osbuser@localhost into the Email address field. Ignore the warning message.
  17. Enter osbuser into the Password field.
  18. Click Continue.
  19. The configuration should be found and the account can be created by clicking on Create Account.
  20. Repeat step 14-19 for the OSB Admin user.
    Getting ready
  21. Test the two e-mail accounts by sending an e-mail message from the OSB User account to the OSB Admin account (E-mail address: osbadmin@localhost).

We have now configured the e-mail server and an e-mail client. Let's now implement the proxy service which consumes e-mail messages from the osbadmin@localhost mailbox.

How to do it...

First, we will create a service account object, which we will use in the proxy service to authenticate against the e-mail server. In Eclipse OEPE, perform the following steps:

  1. Create a new OSB project and name it consuming-emails.
  2. Create the folder structure with a proxy and security folder.
  3. Right-click on the security folder and select New | Service Account to create a new Service Account object.
  4. Enter EmailServer into the File Name field and click Finish.
  5. Select Static for the Resource Type option.
  6. Enter osbadmin into the User Name field and osbadmin into the Password and Confirm Password fields.
    How to do it...

    Now, we create the proxy service, which will use the service account to retrieve the e-mails from the e-mail server:

  7. Create a new proxy service in the proxy folder and name it EmailConsumer.
  8. Select Messaging Service for the Service Type option.
  9. On the Messaging tab, select the Text option for Request Message Type.
  10. Leave the Response Message Type option to None.
  11. Navigate to the Transport tab and select email for Protocol.
  12. Enter mailfrom:localhost:110 into the Endpoint URI field.
  13. Navigate to the Email Transport tab.
  14. Click Browser and select the EmailServer for the Service Account.
  15. Enter 10 into the Polling Interval to configure polling every 10 seconds.
  16. Enter c: empemails-download into the Download Directory field.
  17. Enter c: emperror into the Error Directory field.
  18. Navigate to the Message Flow tab.
  19. Insert a Pipeline Pair node and name it MailConsumerPipelinePair.
  20. Insert a Stage node into the Request Pipeline and name it LogStage.
  21. Insert a Log action into the LogStage.
  22. On the Properties of the Log action, enter $body into the Expression field and select Warning for the Severity.
  23. Deploy the project to the OSB server.

    Now it's time to test the proxy service. In Mozilla Thunderbird (or any other email client), perform the following steps in order to send a message to the osbadmin@localhost e-mail address.

  24. Click Write a new message.
  25. Enter osbadmin@localhost into the To field.
  26. Enter Email to OSB Server into the Subject field.
  27. Enter This is a message for the OSB Server! for the body of the e-mail message.
    How to do it...
  28. Click on Send.

After a while (around 10 seconds), the log message should appear on the Service Bus console window with the content of the e-mail body:

<16.10.2011 20:48 Uhr MESZ> <Warning> <ALSB Logging> <BEA-000000> < [MailConsume
rPipelinePair, MailConsumerPipelinePair_request, LogStage, REQUEST] Body of Emai
l: <soapenv:Body xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">This
is a message for the OSB Server!</soapenv:Body>>

How it works...

Receiving e-mails by the OSB server is as simple as using a proxy service with the Email Transport. In order to be able to select the Email Transport protocol on the Transport tab, either a Messaging Type or Any XML Service type of proxy service needs to be configured.

A proxy service using the Email Transport must always be one-way, that is, the Response Message Type needs to be set to None.

The Email Transport is a polling transport, which means that it polls the E-mail server repeatedly for new e-mails. The Polling Interval property on the Email Transport tab defines the time in seconds the transport should wait in between.

Both POP3 and IMAP can be used for the e-mail protocol. POP3 is the default.

If there are multiple new e-mails waiting on the mail server for consumption, then each e-mail will cause a new proxy service to be started, that is, the message flow will handle always only exactly one e-mail message. The Read Limit property on the Email Transport tab controls the number of e-mails to consume in each poll.

The body variable in the message flow holds the content of the e-mail body, as we have seen in the log output previously. The other information of the e-mail, such as the to-email-address or the subject, can be found in the transport element of the inbound variable. Here is the content of the transport element for the test we did previously:

<con:transport xmlns:con="http://www.bea.com/wli/sb/context">
  <con:uri>mailfrom:localhost:110</con:uri>
  <con:mode>request</con:mode>
  <con:qualityOfService>exactly-once</con:qualityOfService>
  <con:request xsi:type="ema:EmailRequestMetaData"
    xmlns:ema="http://www.bea.com/wli/sb/transports/email" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <tran:headers xsi:type="ema:EmailRequestHeaders"
      xmlns:tran="http://www.bea.com/wli/sb/transports">
      <tran:user-header name="Delivered-To" value="osbadmin@localhost" />
      <tran:user-header name="MIME-Version" value="1.0" />
      <tran:user-header name="Message-ID"
        value="&lt;4E9B28D3.6070802@localhost>" />
      <tran:user-header name="Return-Path" value="&lt;osbuser@localhost>" />
      <tran:user-header name="Content-Transfer-Encoding"
        value="7bit" />
      <tran:user-header name="Received"
        value="from 127.0.0.1 ([127.0.0.1]) by soavm11 (JAMES SMTP Server 2.3.2) with SMTP ID 98 for &lt;osbadmin@localhost>; Sun, 16 Oct 2011 20:56:19 +0200 (CEST)" />
      <tran:user-header name="User-Agent"
        value="Mozilla/5.0 (Windows NT 5.2; rv:7.0.1) Gecko/20110929 Thunderbird/7.0.1" />
      <ema:To>osbadmin@localhost</ema:To>
      <ema:From>OSB User &lt;osbuser@localhost></ema:From>
      <ema:Date>Sun Oct 16 20:56:19 CEST 2011</ema:Date>
      <ema:Subject>Email to OSB Server</ema:Subject>
      <ema:Content-Type>text/plain; charset=ISO-8859-1; format=flowed
      </ema:Content-Type>
    </tran:headers>
    <tran:encoding xmlns:tran="http://www.bea.com/wli/sb/transports">ISO-8859-1</tran:encoding>
  </con:request>
</con:transport>

There's more...

E-mails with attachments are also supported by the Email Transport. Let's change the test case from before and add two additional attachments.

The first attachment is a text file and the second one is a BMP image, with binary content.

There's more...

Information about the e-mail attachments is available through one of the standard OSB variables called attachments. The following screenshot shows the contents of the attachments variable during execution of the proxy service after consumption of the e-mail sent previously (content of the variables from the OSB debugger). Attachments hold a collection with an attachment element for each file attached to the e-mail.

There's more...

If an attachment is text-based (text/plain), then the content of the file is directly available through the body element. This is the case for the first attachment.

If an attachment is binary (image/bmp), then the body element only holds a reference to the binary content.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset