Accessing SOAP Attachments in Web Services

The SOAP Specification defines SOAP attachments as a way to include MIME data in or associated with SOAP messages. Some web service designs use SOAP attachments to pass typed files between a client and a web service. This topic describes how WebLogic Workshop web services can send and receive MIME messages as SOAP attachments.

WebLogic Workshop's SOAP attachment support is based on the SOAP Messages with Attachments specification.

WebLogic Workshop supports SOAP attachments only for web service method invocations that arrive via HTTP. Specifically, in order to support SOAP attachments a web service method must support the http-soap or http-soap12 protocols. You specify the protocols a web service supports using the @jws:protocol annotation.

SOAP attachments are held in memory, and the size of the SOAP attachment supported depends on the amount of memory available on the WebLogic Server machine.

What is MIME?

MIME stands for Multipurpose Internet Mail Extensions. As the name implies, MIME was originally developed to standardize the format and identification of email attachments. Specifically, MIME messages can contain text, images, audio, video, or other application-specific data. The standardized MIME type system has found uses in many other applications besides email. Whenever you use a Download button on a web page or play a media file by clicking on a link in a browser, MIME is used by the browser or other application to identify the type of the linked file and determine how to interact with that resource.

To learn more about MIME, including MIME content types, see RFC 1341.

The Java API includes the javax.activation package that can decode MIME messages and provide application access to the operations that are possible on each type of content.

Handling SOAP Attachments in a Web Service

Handling SOAP attachments in a WebLogic Workshop web service is easy. When you want to access MIME SOAP attachments from a web service method, just reference the javax.activation.DataHandler class in the method's signature. See the examples that follow.

Example: Receiving SOAP Attachments in a Web Service Method

To specify that a web service method expects exactly one SOAP attachment, include an argument of type javax.activation.DataHandler in the method's signature as show below in a web service named EchoAttachmentService.jws:

  import javax.activation.DataHandler;
  
  public class EchoAttachmentService implements com.bea.jws.WebService
  {
    static final long serialVersionUID = 1L;
 
    /**
    * @common:operation
    * @jws:protocol form-get="false" form-post="false"
    */
    public String echoAttachment(DataHandler dh)
    {
      return("***Service received DataHandler of type: " + dh.getContentType());
    }
  }

The preceding example returns a String containing the content type of whatever MIME message it receives as an attachment. Examples of MIME content types are text/plain, text/html and application/octet-stream. There are many other registered MIME content types.

In the preceding example, the form-get and form-post attributes of the @jws:protocol annotation have been set to false. The FROM GET and FORM POST operations have no way to convey SOAP attachments. To access a web service that accepts SOAP attachments, clients must send raw SOAP messages (via some supported transport protocol, typically HTTP or JMS).

To specify that a web service expects multiple SOAP attachments, include an argument of type javax.activation.DataHandler[] in the method's signature.

Example: Returning SOAP Attachments from a Web Service Method

To specify that a web service method returns one or more SOAP attachments to the client, declare the method's return value as javax.activation.DataHandler or javax.activation.DataHandler[].

The FileRetrieverService web service below demonstrates a web service method whose return value is a MIME message packaged as a SOAP attachment:

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

  public class FileRetrieverService implements com.bea.jws.WebService
  {
    static final long serialVersionUID = 1L;
 
    /**
    * @common:operation
    * @jws:protocol form-get="false" form-post="false"
    */
    public DataHandler getFileAsAttachment(String filename)
    {
      return(new DataHandler(new FileDataSource(filename)));
    }
  }

The getFileAsAttachment method returns the named file as a MIME message SOAP attachment.

You may also return an array of MIME message SOAP attachments from a web service method by declaring the method's return value to be of type javax.activation.DataHandler[].

Tested Interoperation Scenarios

The following interoperation scenarios have been tested:

Related Topics

@jws:protocol Annotation

javax.activation.DataHandler (at java.sun.com)