Using WS-I compliant referenced attachments in WebSphere ESB

This article shows you how to use the new support for WS-I compliant attachments in WebSphere ESB V7.0.0.3 to implement a mediation flow that can handle messages containing WS-I compliant referenced attachments, including how to define the interface using WSDL, how to create the mediation flow, and how to create a test client.

Andrew J. Howes (andrew_howes@uk.ibm.com), Software Engineer, IBM

Photo of Andy HowesAndy Howes is a Software Engineer on the IBM Integration Bus Development Team at the IBM Software Lab in Hursley, United Kingdom. He has been in the software industry for over 20 years and has been involved in software development, systems support, project management, and function and system test. You can contact Andy at andrew_howes@uk.ibm.com.



18 May 2011

Introduction

While IBM® WebSphere® ESB has supported attachments to SOAP messages, support for WS-I compliant attachments is a new feature in V7.0.0.3. The WS-I Attachments Profile V1.0 specification requires adherence to the Content-Id part encoding rules for WS-I, which requires the following format for the Content-Id header for the attachment in the instance message (the message flowing over the wire):

attachment_name=unique_id@domain_name

For example, with an attachment called idDocScan, the instance message might contain:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">...
   </soapenv:Envelope>
--MIMEBoundaryurn_uuid_F4185E1F2E30DAD5111283956065782
Content-Type: image/jpeg
Content-Transfer-Encoding: binary
Content-ID: <idDocScan=urn:uuid:F4185E1F2E30DAD5111283956064452@jaxws.myorg.com>

...MIME attachment of JPEG

--MIMEBoundaryurn_uuid_F4185E1F2E30DAD5111283956065782--

The type of WS-I compliant referenced attachment described in this article is defined in the message part of the WSDL. For example:

<wsdl:message name="messIn">
   <wsdl:part name="mainObject" type="types:mainBOType"/>
   <wsdl:part name="idDocScan" type="xsd:base64Binary"/>
</wsdl:message>

Implementing the example

There are three main parts to implementing this example:

  • Defining the business objects and interface in a library
  • Creating a mediation with a Web service export based on the interface
  • Creating a client to drive the Web service

Creating a library

Create a library containing request and response business objects:

  1. Select File => New => Library.
  2. Choose a name for the library and click Finish.
  3. Right-click the library and select New => Business object.
  4. Enter a name for the business object and click Finish.
  5. Specify fields to be used in a service request.
  6. Repeat the process to create a business object for a service response.

For example:

Figure 1
Figure 1

Create a document literal non-wrapped interface with a request/response operation and add an additional base64Binary input to carry the referenced attachment:

  1. Right-click the library and select New => Interface.
  2. Specify a name for the Interface and click Finish.
  3. Select the Add request response operation icon.
  4. Set the type of the Input for your request business object.
  5. Set the type of the output for your response business object.
  6. Right-click Inputs and select Add input.
  7. Set the type of the new input to base64Binary.
  8. For the Binding style item, click Change binding style to document literal non-wrapped.

For example:

Figure 2
Figure 2

Creating a mediation Web service

This section shows you how to create a mediation module and define it as a Web service that can accept WS-I compliant referenced attachments:

Setting up the assembly diagram

  1. Select File => New => Mediation module.
  2. Give the module a name and click Next.
  3. Select the library you have just created as a required library and click Finish.
  4. Right-click the mediation flow and select Add => Interface.
  5. Select the interface you created.
  6. Right-click the mediation flow and select Add => Reference.
  7. Select the interface you created.
  8. Right-click the mediation flow and select Generate export => Web service binding.
  9. Select SOAP 1.2/HTTP and click Next.
  10. Accept the default and click Next.
  11. Select Use WS-I compliant SOAP message and click Finish.
  12. On the warning pop-up, click OK.
  13. Drag a Java component onto the canvas and connect the output from the mediation flow to it:
Figure 3
Figure 3

Setting up the mediation flow

  1. Double-click the mediation flow and click Yes on the pop-up.
  2. Click OK to select the default folder.
  3. On the interface side (left), click on the name of the operation and select Blank mediation flow.
  4. Drag a Callout primitive onto the canvas.
  5. Select the reference operation from the interface.
  6. Drag a Custom Mediation primitive onto the canvas.
  7. Connect the Input node to the Custom Mediation input and connect the Custom Mediation output to the Callout node.
  8. Click on the Response tab.
  9. Connect the Callout response directly to the Input response.
  10. Click back on the Request tab.
  11. Select the Custom Mediation and in the Properties tab at the bottom, select the Details tab.
  12. Add some Java to manipulate the body of the message, and then save the flow:
Figure 4
Figure 4

Sample Java for the Custom Mediation:

 DataObject body = (DataObject) smo.getBody();

DataObject operation = (DataObject)body.get("operation1Parameters0");
String ref = operation.getString("applicationRef");
String type = operation.getString("accountType");
Double balance = operation.getDouble("balance");

if ( type.equals("Premium") ) {
   operation.setString("applicationRef",ref+type);
   operation.setDouble("balance", (balance*1.1));
}
else {
   operation.setString("applicationRef",ref+type);
}

body.set("operation1Parameters0",operation);

smo.setBody(body);

out.fire(smo);

Type Ctrl-Shift-O to add the required import for DataObject.

Setting up the Java component

  1. Go back to the assembly diagram.
  2. Double click the Java component.
  3. Select Yes on the pop-up.
  4. Select the default package and click OK.
  5. Add in Java to obtain the passed referenced attachment and write it to a file.
  6. Save the assembly diagram.

Sample Java for the service:

public DataObject AccountApplication(DataObject accountRequest,
   byte[] idDocScan) {

   // Get details from the input object
   String appRef = accountRequest.getString("applicationRef");
   Double balance = accountRequest.getDouble("balance");
   String fName = accountRequest.getString("firstName");
   String lName = accountRequest.getString("lastName");
   String type = accountRequest.getString("accountType");
   System.out.println
      ("Account request "+appRef+" from "+fName+" "+lName+" for "+type+" account");
   
   // Get the length of the received image
   int scanLength = idDocScan.length;
   System.out.println("Length of scanned image is "+scanLength);

   // Write the image out to file
   String fileloc = System.getProperty("java.io.tmpdir")+"/RcvdImage.jpg";
   System.out.println("Writing image to "+fileloc);
   File file = new File(fileloc);
   try {
      OutputStream out = new FileOutputStream(file);
      out.write(idDocScan);
      out.close();
   } catch (FileNotFoundException e) {
      e.printStackTrace();
   } catch (IOException e) {
      e.printStackTrace();
   }

   // Construct the response object
   ServiceManager serviceManager = ServiceManager.INSTANCE;
   BOFactory bofactory = (BOFactory) 
      serviceManager.locateService("com/ibm/websphere/bo/BOFactory");

   DataObject response = bofactory.create("http://AccountAppLib", "AccountResponse");

   // Set the response object values
   response.setBoolean("accepted",true);
   response.setString("applicationRef",appRef);
   response.setString("accountNumber",fileloc);
   response.setDouble("balance",(balance*0.9));

   return response;
}

Save the mediation service as an EAR file and deploy it to a WebSphere ESB server V7.0.0.3 or later.

Creating a client

  1. Expand the library Web service ports.
  2. Right-click the WSDL (AccountApplicationExport1_AccountApplicationHttpPort) and select Web Services => Generate Client.
  3. Set the slider on the left to Deploy service.
  4. Set the Server to WebSphere ESB Server V7.
  5. Set the Web service runtime to IBM WebSphere JAX-WS.
  6. Give the Client project a unique name.
  7. Set the Project type to Application client project.
  8. Click Next and then click Finish.

Expand the new Client project src => default package and open Main.java. Here is some sample client code that you can use:

public static void main(String[] args) {
   String endpoint = args[0];

   AccountRequest request = new AccountRequest();
   AccountResponse response = new AccountResponse();	
   AccountApplicationExport1_AccountApplicationHttpPortProxy proxy = new 
   AccountApplicationExport1_AccountApplicationHttpPortProxy();

   // Set up request
   request.setApplicationRef("AA936578");
   request.setAccountType("Premium");
   request.setFirstName("Syd");
   request.setLastName("Waters");
   request.setHouseNo("26");
   request.setPostCode("CB98 X32");
   request.setBalance(200.0);

   // Set up referenced attachment
   String attachment = "/tmp/pic1.JPG";
   File file = new File(attachment);
   InputStream in;
   byte buf[] = new byte[1024];
   byte[] idDocScan = {};
   try {
      in = new FileInputStream(file);
      int len = 0;
      int used = 0;
      try {
         while ( (len= in.read(buf)) > -1) {
            used = idDocScan.length;
            byte temp[] = new byte[used+len];
            System.arraycopy(idDocScan, 0, temp, 0, used);
            System.arraycopy(buf, 0, temp, used, len);
            idDocScan = temp;
         }
      } catch (IOException e) {
         e.printStackTrace();
      }
   } catch (FileNotFoundException e) {
      e.printStackTrace();
   }

   System.out.println("Sending request with file "+attachment+" attached ");

   try {
      // Set up proxy and call the operation
      proxy._getDescriptor().setEndpoint(endpoint);
      response = proxy.accountApplication(request, idDocScan);
      //
      // Process the response
      //
      boolean accepted = response.isAccepted();
      String account = response.getAccountNumber();
      Double balance = response.getBalance();

      if ( accepted ) {
         System.out.println("Request for account is accepted");
         System.out.println("Account balance is "+balance);	
         System.out.println("Sent attachment loc on target host is "+account);
         System.out.println("Test PASSED");
      }
      else {
         System.out.println("Request for account is rejected");
      }

   }
   catch (Exception e) {
      e.printStackTrace();
      System.out.println("Test FAILED with exception "+e);
   }
}

Save the project as an EAR file rather than a JAR file.

Testing the service

Make a binary file (such as a .jpg image) available for use as an attachment and put it in a convenient location such as /tmp/pic1.jpg on the system where the client will be run. Initiate the client EAR file using the WebSphere ESB launchClient tool. The Web service endpoint of the deployed mediation is provided as a parameter to the client. For example:

C:\ESB\bin\launchClient AccountClientEAR.ear 
   http://mysystem.com:9080/AccountMediationWeb/sca/AccountApplicationExport1

Here is the expected output at the command console:

Sending request with file /tmp/pic1.JPG attached
Request for account is accepted
Account balance is 198.00000000000003
Sent attachment location on target host is /tmp/RcvdImage.jpg
Test PASSED

To ensure that the attachment has been processed correctly, navigate to the attachment location on the WebSphere ESB host (/tmp/RcvdImage.jpg) and check that the file is present with an appropriate timestamp. Open the file, in a browser for example, and check that the picture is correct and uncorrupted.

Conclusion

This article showed you how to implement a WebSphere ESB mediation flow that can handle a message containing a WS-I compliant referenced attachment, including how to define the interface using WSDL, how to create the mediation flow, and how to create a test client.

Resources

  • WebSphere ESB resources
  • WebSphere resources
    • developerWorks WebSphere developer resources
      Technical information and resources for developers who use WebSphere products. developerWorks WebSphere provides product downloads, how-to information, support resources, and a free technical library of more than 2000 technical articles, tutorials, best practices, IBM Redbooks, and online product manuals.
    • developerWorks WebSphere application connectivity developer resources
      How-to articles, downloads, tutorials, education, product info, and other resources to help you build WebSphere application connectivity and business integration solutions.
    • developerWorks WebSphere SOA and Web services developer resources
      How-to articles, downloads, tutorials, education, product info, and other resources to help you design and build WebSphere SOA and Web services solutions.
    • Most popular WebSphere trial downloads
      No-charge trial downloads for key WebSphere products.
    • WebSphere forums
      Product-specific forums where you can get answers to your technical questions and share your expertise with other WebSphere users.
    • WebSphere on-demand demos
      Download and watch these self-running demos, and learn how WebSphere products and technologies can help your company respond to the rapidly changing and increasingly complex business environment.
    • developerWorks WebSphere weekly newsletter
      The developerWorks newsletter gives you the latest articles and information only on those topics that interest you. In addition to WebSphere, you can select from Java, Linux, Open source, Rational, SOA, Web services, and other topics. Subscribe now and design your custom mailing.
    • WebSphere-related books from IBM Press
      Convenient online ordering through Barnes & Noble.
    • WebSphere-related events
      Conferences, trade shows, Webcasts, and other events around the world of interest to WebSphere developers.
  • developerWorks resources
    • Trial downloads for IBM software products
      No-charge trial downloads for selected IBM® DB2®, Lotus®, Rational®, Tivoli®, and WebSphere® products.
    • developerWorks blogs
      Join a conversation with developerWorks users and authors, and IBM editors and developers.
    • developerWorks tech briefings
      Free technical sessions by IBM experts to accelerate your learning curve and help you succeed in your most difficult software projects. Sessions range from one-hour virtual briefings to half-day and full-day live sessions in cities worldwide.
    • developerWorks podcasts
      Listen to interesting and offbeat interviews and discussions with software innovators.
    • IBM Education Assistant
      A collection of multimedia educational modules that will help you better understand IBM software products and use them more effectively to meet your business requirements.

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=658593
ArticleTitle=Using WS-I compliant referenced attachments in WebSphere ESB
publish-date=05182011