Using attachment types with web services

In use case scenarios, we may need to transfer documents, media, and other files with web services. These kinds of elements are defined with Multipurpose Internet Mail Extensions (MIME) types. The JAX-WS specification enables the Message Transmission Optimization Mechanism (MTOM) feature which enables efficient transfer of binary content via SOAP messages. This recipe explains how to use the MIME types with web services.

Getting ready

We will amend the example from the Creating literal and encoded web services recipe in order to complete this recipe.

How to do it…

To show the usage of MIME types in a web service, we will implement an additional method that enables the upload of an eBook to the book library:

  1. Open the BookLibrary interface and add the following code:
    @WebMethod public void uploadBook(String bookName, DataHandler data);
  2. Open BookLibraryImpl and amend the code with the following lines. We first need to decorate the class with the @MTOM annotation as shown in the following code:
    @MTOM
@WebService(name = "BookLibrary", serviceName = "BookLibraryService", portName = "BookLibraryPort")
@SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED)
public class BookLibraryImpl implements BookLibrary {
  3. We still need to implement the new method:
    public void uploadBook(String bookName, @XmlMimeType("application/pdf") DataHandler data) {
      try {
        File file = new File("C:\temp\books\" + bookName + ".pdf");
      
        OutputStream output = new BufferedOutputStream(new FileOutputStream(file));
        data.writeTo(output);
        output.close();            
      } catch (Exception e) {
            throw new WebServiceException(e);
      }
}

Initially, the name of the book file is generated. Then, the content is read from the data handler to the output stream. At the end, we close the output stream.

How it works…

Let us inspect the WSDL document, especially the SOAP binding tag definition as shown in the following code:

<binding name="BookLibraryPortBinding" type="tns:BookLibrary">
  <wsp:PolicyReference URI="#Mtom.xml"/>
  <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/>
<binding>

Beside the binding information, we can also see a PolicyReference tag which enables MTOM on the web service. The request message of the uploadBook operation has the following code in the schema:

<xs:complexType name="uploadBook">
  <xs:sequence>
    <xs:element name="arg0" type="xs:string" minOccurs="0"/>
    <xs:element xmlns:ns1="http://www.w3.org/2005/05/xmlmime" name="arg1" ns1:expectedContentTypes="application/pdf" type="xs:base64Binary" minOccurs="0"/>
  </xs:sequence>
</xs:complexType>

The content of the file is transferred through arg1. The type of arg1 is base64Binary, which means that binary content is transferred. A particularly interesting attribute is expectedContentTypes. Remember we annotate the data parameter of the uploadBook method with the @XmlMimeType("application/pdf") annotation. This is translated into the expectedContentTypes="application/pdf« attribute.

A sample of the SOAP request message is shown in the following code:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://ws.java.packt.org/">
  <soapenv:Header/>
  <soapenv:Body>
    <ws:uploadBook>
      <arg0>packt_book</arg0>
      <arg1>
        <inc:Include href="cid:SampleBook.pdf" xmlns:inc="http://www.w3.org/2004/08/xop/include"/>
      </arg1>
    </ws:uploadBook>
  </soapenv:Body>
</soapenv:Envelope>

We enter packt_book as arg0. Now look at the argument arg1. This argument holds the information about the book we want to upload. Actually, it holds the reference to the book. We can see the MTOM in action here. The arg1 argument holds the reference to the other part of the message (c id:SampleBook.pdf) where we can see the content of the book. We have omitted the complete request message as it is too long and would go through several pages. According to the web service operation implementation, we would expect to find the PDF book document at the C: empookspackt_book.pdf location. Indeed, the file is there, and if we open it with our favorite PDF reader, we will see the content as shown in the following screenshot:

How it works…
..................Content has been hidden....................

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