Skip to main content

If you don't have an IBM ID and password, register here.

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

The first time you sign into developerWorks, a profile is created for you. This profile includes the first name, last name, and display name you identified when you registered with developerWorks. Select information in your developerWorks profile is displayed to the public, but you may edit the information at any time. Your first name, last name (unless you choose to hide them), and display name will accompany the content that you post.

All information submitted is secure.

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.

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

All information submitted is secure.

Web services programming tips and tricks: SOAP attachments with JAX-RPC

Russell Butek (butek@us.ibm.com), Software Engineer, IBM, Software Group
Russell Butek is one of the developers of the IBM WebSphere Web services engine. He is also an IBM representative on the JAX-RPC Java Specification Request (JSR) expert group. He was involved in the implementation of Apache's AXIS SOAP engine, driving AXIS 1.0 to comply with JAX-RPC 1.0. Previously, he was a developer of the IBM CORBA ORB and an IBM representative on a number of OMG task forces: the portable interceptor task force (of which he was chair), the core task force, and the interoperability task force.

Summary:  JAX-RPC supports SOAP with attachments. This tip describes how you can use JAX-RPC APIs to send MIME attachments.

Date:  27 Feb 2004
Level:  Intermediate

Comments:  

The SOAP messaging protocol allows you to send MIME attachments via SOAP messages. WSDL provides a description of these attachments. JAX-RPC provides a mapping of the WSDL description of attachments into Java artifacts. This tip describes how to use those JAX-RPC mappings to send attachments in SOAP messages.

The WSDL

The WSDL description of attachments is, unfortunately, not particularly straightforward. Take a look at the WSDL in Listing 1, particularly the highlighted elements of the binding.



Listing 1. WSDL with attachments
<?xml version="1.0" encoding="utf-8"?>
<definitions
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
    targetNamespace="urn:attachment.tip"
    xmlns:tns="urn:attachment.tip">
  <message name="empty"/>
  <message name="imageMsg">
    <part name="image" type="xsd:hexBinary"/>
  </message>
  <message name="octetMsg">
    <part name="octet" type="xsd:hexBinary"/>
  </message>

  <portType name="AttachmentTip">
    <operation name="sendImage">
      <input message="tns:imageMsg"/>
      <output message="tns:empty"/>
    </operation>
    <operation name="sendOctet">
      <input message="tns:octetMsg"/>
      <output message="tns:empty"/>
    </operation>
  </portType>

  <binding name="AttachmentBinding" type="tns:AttachmentTip">
    <soap:binding style="rpc"
                  transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="sendImage">
      <soap:operation soapAction=""/>
      <input>
        <mime:multipartRelated>
          <mime:part>
            <soap:body use="literal"/>
          </mime:part>
          <mime:part>
            <mime:content part="image" type="image/jpeg"/>
          </mime:part>
        </mime:multipartRelated>
      </input>
      <output>
        <soap:body use="literal"/>
      </output>
    </operation>
    <operation name="sendOctet">
      <soap:operation soapAction=""/>
      <input>
        <mime:multipartRelated>
          <mime:part>
            <soap:body use="literal"/>
          </mime:part>
          <mime:part>
            <mime:content part="octet" type="application/octet-stream"/>
          </mime:part>
        </mime:multipartRelated>
      </input>
      <output>
        <soap:body use="literal"/>
      </output>
    </operation>
  </binding>

  <service name="AttachmentService">
    <port name="AttachmentTip" binding="tns:AttachmentBinding">
      <soap:address
          location="http://localhost:9080/attachment/services/AttachmentTip"/>
    </port>
  </service>

</definitions>

WS-I and attachments

As the paragraphs to the left describe, MIME types cannot be described by WSDL's 'interface'. The WS-I organization (see Resources) is attempting to repair this shortcoming, at least partially, by introducing a new XML type for all MIME types: wsi:swaRef. But at the time of this writing, this type is still in the works, and no standardized Java language binding exists for it.

The first thing to note is that there is no MIME information until you get all the way down to the binding. If you ignore the binding for a moment and only look at the WSDL's 'interface' (portType and messages), you'll see two operations - sendImage and sendOctet. Each of these has a hexBinary input. hexBinary maps to byte[]. Using only this information, you could reasonably guess that this portType would map to a Java language Service Endpoint Interface (SEI) which would have two methods, each of which would have a single byte[] parameter. This is a good guess, and for anything but MIME types, you'd be correct. But for MIME types you must inspect the binding to determine the real parameter types.

In the binding you'll see that the inputs for the operations are really MIME content types -- image/jpeg and application/octet-stream -- instead of hexBinary. JAX-RPC defines these to map to java.awt.Image and javax.activation.DataHandler, respectively.


The Service Endpoint Interface

Listing 2 contains a Java language SEI generated from the WSDL in Listing 1.


Listing 2. The AttachmentTip SEI
package tip.attachment;

import java.awt.Image;
import java.rmi.Remote;
import java.rmi.RemoteException;
import javax.activation.DataHandler;

public interface AttachmentTip extends Remote {
    public void sendImage(Image image) throws RemoteException;
    public void sendOctet(DataHandler octet) throws RemoteException;
}

The WSDL's sendImage operation, which the binding says has a MIME content of image/jpeg, becomes a Java program method with a java.awt.Image parameter. Very straightforward. Nice and tidy. Table 1 lists all of the nice-and-tidy mappings of MIME types to Java types.


Table 1 - JAX-RPC mappings of MIME types to Java types
MIME TypeJava Type
image/gif, image/jpegjava.awt.Image
text/plainjava.lang.String
multipart/*javax.mail.internet.MimeMultipart
text/xml, application/xmljavax.xml.transform.Source

If you define a MIME type that is not in this table, as I did in the sendOctet operation, then a JAX-RPC implementation will map your type to javax.activation.DataHandler. The DataHandler type is defined in the Java Activation Framework (JAF -- see more details below, and also a link to the JAF pages in the Resources section).


The client implementation

From this point on, I assume that you have used your favorite JAX-RPC implementation to generate all the client-side mappings from the AttachmentTip WSDL. The client implementation will depend on these mappings, particularly the AttachmentTip SEI from Listing 2.

The client implementation of attachments must first acquire an implementation of the SEI from a Service. You can see how this is done in Listing 3 in the getTip method (a discussion of the ServiceFactory and Service is beyond the scope of this tip, see Resources for more information).

Call the sendImage method

Once you have an SEI implementation, you can call its methods with your attachment (which for this example is in a file whose name you provide). In the case of sendImage, that attachment is a java.awt.Image. That's all there is to it. The JAX-RPC implementation knows that all images are sent as attachments and it constructs the SOAP message accordingly. The client programmer need not even be aware that attachments are involved. See the highlighted code in Listing 3 for the call to sendImage.


Listing 3. The AttachmentTip client implementation to call sendImage
package tip.attachment;

import java.awt.Image;
import java.awt.Toolkit;

import java.net.URL;

import java.rmi.RemoteException;

import javax.xml.namespace.QName;

import javax.xml.rpc.Service;
import javax.xml.rpc.ServiceFactory;

public class AttachmentTipClient {

    static AttachmentTip getTip() throws Exception {
        QName serviceName = new QName(
                "urn:attachment.tip",
                "AttachmentService");
        URL wsdlLocation = new URL(
                "http://localhost:9080/attachment/services/AttachmentTip?wsdl");
        ServiceFactory factory = ServiceFactory.newInstance();
        Service service = factory.createService(wsdlLocation, serviceName);
        QName portName = new QName("", "AttachmentTip");
        return (AttachmentTip) service.getPort(
                portName,
                AttachmentTip.class);
    }

    static void sendImage(AttachmentTip tip, String fileName)
            throws RemoteException {
        Toolkit toolkit = Toolkit.getDefaultToolkit();
        Image image = toolkit.createImage(fileName);
        tip.sendImage(image);
    }

    public static void main(String[] args) {
        try {
            AttachmentTip tip = getTip();
            sendImage(tip, args[0]);
        }
        catch (Throwable t) {
            t.printStackTrace();
        }
    }
}

Call the sendOctet method

A caveat about mapping non-specified MIME types

JAX-RPC does not require an implementation to support MIME types which do not appear in Table 1. Implementations may not map unspecified MIME types to DataHandler. For instance, WebSphere Web services does not support this mapping until version 6.0 of the Application Server.

For those few MIME types for which JAX-RPC has defined a mapping (see Table 1), life is fairly easy. For those MIME types for which there is no explicit JAX-RPC mapping, you're left with a javax.activation.DataHandler object. This class is part of the Java Activation Framework (JAF -- see Resources), so you have to know something about the JAF, but it's not too difficult. A DataHandler contains a javax.activation.DataSource which, in turn, contains input and output streams. Most Java programming types can be converted fairly easily to/from streams, so this is fairly straightforward. Moreover, the activation framework itself even helps a little. If your attachment data is in a file, as this one is, the activation framework provides the javax.activation.FileDataSource class, so you can bypass the stream step. Listing 4 is the code from Listing 3 with the addition of a new method to call sendOctet and pass it a DataHandler.


Listing 4. The complete AttachmentTip client implementation
package tip.attachment;

import java.awt.Image;
import java.awt.Toolkit;

import java.net.URL;

import java.rmi.RemoteException;

import javax.activation.DataHandler;
import javax.activation.FileDataSource;

import javax.xml.namespace.QName;

import javax.xml.rpc.Service;
import javax.xml.rpc.ServiceFactory;

public class AttachmentTipClient {

    static AttachmentTip getTip() throws Exception {
        QName serviceName = new QName(
                "urn:attachment.tip",
                "AttachmentService");
        URL wsdlLocation = new URL(
                "http://localhost:9080/attachment/services/AttachmentTip?wsdl");
        ServiceFactory factory = ServiceFactory.newInstance();
        Service service = factory.createService(wsdlLocation, serviceName);
        QName portName = new QName("", "AttachmentTip");
        return (AttachmentTip) service.getPort(
                portName,
                AttachmentTip.class);
    }

    static void sendImage(AttachmentTip tip, String fileName)
            throws RemoteException {
        Toolkit toolkit = Toolkit.getDefaultToolkit();
        Image image = toolkit.createImage(fileName);
        tip.sendImage(image);
    }

    static void sendOctet(AttachmentTip tip, String fileName)
            throws RemoteException {
        FileDataSource fds = new FileDataSource(fileName);
        DataHandler dh = new DataHandler(fds);
        tip.sendOctet(dh);
    }

    public static void main(String[] args) {
        try {
            AttachmentTip tip = getTip();
            sendImage(tip, args[0]);
            sendOctet(tip, args[0]);
        }
        catch (Throwable t) {
            t.printStackTrace();
        }
    }
}

Note that I used the same file as the data for both attachment operations, but as far as sendOctet is concerned, the contents of the file is merely an application/octet-stream. It doesn't know, or care, that it's really an image. application/octet-stream is the default content type for FileDataSource, which is why I used it. It did everything for me. If you aren't so lucky to have your data in a file, and you have to send it as something other than an application/octet-stream, then you have to create your own implementation of DataSource, but it's a simple interface, so it shouldn't take too much effort. (This is left as an exercise to the reader!)


Summary

As I've shown, sending attachments via JAX-RPC mappings is a fairly simple matter. The application programmer doesn't have to be aware of attachments at all. At worst, the programmer must be aware of DataHandlers, DataSources, and streams.



Download

NameSizeDownload method
ws-tip-soapjax.zip40.0 KBHTTP

Information about download methods


Resources

About the author

Russell Butek is one of the developers of the IBM WebSphere Web services engine. He is also an IBM representative on the JAX-RPC Java Specification Request (JSR) expert group. He was involved in the implementation of Apache's AXIS SOAP engine, driving AXIS 1.0 to comply with JAX-RPC 1.0. Previously, he was a developer of the IBM CORBA ORB and an IBM representative on a number of OMG task forces: the portable interceptor task force (of which he was chair), the core task force, and the interoperability task force.

Report abuse help

Report abuse

Thank you. This entry has been flagged for moderator attention.


Report abuse help

Report abuse

Report abuse submission failed. Please try again later.


developerWorks: Sign in

If you don't have an IBM ID and password, register here.


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. This profile includes the first name, last name, and display name you identified when you registered with developerWorks. Select information in your developerWorks profile is displayed to the public, but you may edit the information at any time. Your first name, last name (unless you choose to hide them), and display name will accompany the content that you post.

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.

(Must be between 3 – 31 characters.)


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

 


Rate this article

Comments

Help: Update or add to My dW interests

What's this?

This little timesaver lets you update your My developerWorks profile with just one click! The general subject of this content (AIX and UNIX, Information Management, Lotus, Rational, Tivoli, WebSphere, Java, Linux, Open source, SOA and Web services, Web development, or XML) will be added to the interests section of your profile, if it's not there already. You only need to be logged in to My developerWorks.

And what's the point of adding your interests to your profile? That's how you find other users with the same interests as yours, and see what they're reading and contributing to the community. Your interests also help us recommend relevant developerWorks content to you.

View your My developerWorks profile

Return from help

Help: Remove from My dW interests

What's this?

Removing this interest does not alter your profile, but rather removes this piece of content from a list of all content for which you've indicated interest. In a future enhancement to My developerWorks, you'll be able to see a record of that content.

View your My developerWorks profile

Return from help

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=SOA and web services, XML
ArticleID=12380
ArticleTitle=Web services programming tips and tricks: SOAP attachments with JAX-RPC
publish-date=02272004
author1-email=butek@us.ibm.com
author1-email-cc=

Tags

Help
Use the search field to find all types of content in My developerWorks with that tag.

Use the slider bar to see more or fewer tags.

For articles in technology zones (such as Java technology, Linux, Open source, XML), Popular tags shows the top tags for all technology zones. For articles in product zones (such as Info Mgmt, Rational, WebSphere), Popular tags shows the top tags for just that product zone.

For articles in technology zones (such as Java technology, Linux, Open source, XML), My tags shows your tags for all technology zones. For articles in product zones (such as Info Mgmt, Rational, WebSphere), My tags shows your tags for just that product zone.

Use the search field to find all types of content in My developerWorks with that tag. Popular tags shows the top tags for this particular content zone (for example, Java technology, Linux, WebSphere). My tags shows your tags for this particular content zone (for example, Java technology, Linux, WebSphere).