Operating streamed attachments

When using Streaming, if you receive a SOAP message of MIME Multipart/Related structure containing an attachment, the received attachment is mapped to the com.sun.xml.ws.developer.StreamingDataHandler class instead of the javax.activation.DataHandler class in JAX-WS, and can be handled as a streamed attachment.

For the com.sun.xml.ws.developer.StreamingDataHandler class, see 19.2.4 (2) com.sun.xml.ws.developer.StreamingDataHandler class.

The following is an example of operating a streamed attachment. In this example, the streamed attachment is output with a different name as "C:/portrait.png":

package com.sample;
 
......
 
@MTOM
@StreamingAttachment(dir="C:/TMP", parseEagerly=true, memoryThreshold=50000L)
@BindingType(...)
public class UserInfoImpl implements UserInfo {
 
    public DataHandler getUserInfo(DataHandler dataHandler)
        throws UserDefinedException {
        if (dataHandler instanceof StreamingDataHandler) {
            File file = new File("C:/portrait.png");
            StreamingDataHandler sdh = null;
            try {
                sdh = (StreamingDataHandler)dataHandler;
                sdh.moveTo(file);
                ......
            } finally {
                try {
                    if (sdh != null) {
                        sdh.close();
                    }
                } catch(Exception ex) {
                    ......
                }
            }
        }
    }
}

Organization of this subsection: (1) Points to be noted when operating the streamed attachments

The following are the points to be noted when operating the streamed attachments:

When using Streaming, you must distinguish the com.sun.xml.ws.developer.StreamingDataHandler class with the help of an instanceof operator.
Irrespective of whether the attachments are used, you must close the attachments that are output in the temporary files by using the com.sun.xml.ws.developer.StreamingDataHandler#close() method. If you do not close the attachments, JAX-WS will not remove the temporary files.
You can invoke only the com.sun.xml.ws.developer.StreamingDataHandler#close() method after invoking the com.sun.xml.ws.developer.StreamingDataHandler#readOnce() and com.sun.xml.ws.developer.StreamingDataHandler#moveTo(File) methods. The operation is not guaranteed if the methods other than the com.sun.xml.ws.developer.StreamingDataHandler#close() method are invoked.

If you invoke the com.sun.xml.ws.developer.StreamingDataHandler#readOnce() method, you must close the input stream after reading all the data from the input stream acquired when the attachment was no longer required. Thereafter, you must invoke the com.sun.xml.ws.developer.StreamingDataHandler#close() method. The following is an example of invoking the com.sun.xml.ws.developer.StreamingDataHandler#readOnce() method:

package com.sample;
...
 
@MTOM
@StreamingAttachment(...)
...
public class UserInfoImpl implements UserInfo {
 
    public @XmlMimeType("application/octet-stream")
           DataHandler getUserInfo(
               @XmlMimeType("application/octet-stream")
               DataHandler dataHandler)
        throws ... {
        if (dataHandler instanceof StreamingDataHandler) {
            StreamingDataHandler sdh = null;
            try {
                sdh = (StreamingDataHandler)dataHandler;
                ...
                InputStream inputStream = sdh.readOnce();
                ...
                // read all the data of the attachment from the input stream       
         while ((inputStream.read()) != -1);
 
                //close the input stream
                inputStream.close();
            } finally {
                try {
                    if (sdh != null) {
                        //invoke the close() method of the StreamingDataHandler
                        //class
                        sdh.close();
                    }
                } catch(Exception ex) {
                    ...
                }
            }
        }
        ...
    }
}

If you invoke the com.sun.xml.ws.developer.StreamingDataHandler#moveTo(File) method, you must invoke the com.sun.xml.ws.developer.StreamingDataHandler#close() method when the attachment is no longer required.

If an exception occurs when you invoke the com.sun.xml.ws.developer.StreamingDataHandler#moveTo(File) method, you must acquire the input stream by invoking the com.sun.xml.ws.developer.StreamingDataHandler#readOnce() method. Close the input stream after reading all the data from that input stream. Thereafter, you must invoke the com.sun.xml.ws.developer.StreamingDataHandler#close() method. The following is an example of invoking the com.sun.xml.ws.developer.StreamingDataHandler#moveTo(File) method:

package com.sample;
...
 
@MTOM
@StreamingAttachment(...)
...
public class UserInfoImpl implements UserInfo {
 
    public @XmlMimeType("application/octet-stream")
           DataHandler getUserInfo(
               @XmlMimeType("application/octet-stream")
               DataHandler dataHandler)
        throws ... {
        if (dataHandler instanceof StreamingDataHandler) {
            StreamingDataHandler sdh = null;
            try {
                File file = new File(...);
                sdh = (StreamingDataHandler)dataHandler;
                ...
                sdh.moveTo(file);
            } catch(Exception e)
                try {
                    if (sdh != null) {
                        InputStream inputStream = sdh.readOnce();
 
                        //read all the data of the attachment from the
                        //input stream
                        while ((inputStream.read()) != -1);
 
                        //close the input stream
                        inputStream.close();
                    }
                } catch(Exception ex) {
                    ...
                }
            } finally {
                try {
                    if (sdh != null) {
                        //invoke the close()method of the StreamingDataHandler class
                        sdh.close();
                    }
                } catch(Exception ex) {
                    ...
                }
            }
        }
       ...
    }
}

If you do not invoke the com.sun.xml.ws.developer.StreamingDataHandler#readOnce() and com.sun.xml.ws.developer.StreamingDataHandler#moveTo(File) methods, you must acquire the input stream by invoking the com.sun.xml.ws.developer.StreamingDataHandler#readOnce() method when the attachment is no longer required. Close the input stream after reading all the data from that input stream. Thereafter, you must invoke the com.sun.xml.ws.developer.StreamingDataHandler#close() method.
Among the methods of the javax.activation.DataHandler class, the com.sun.xml.ws.developer.StreamingDataHandler class can invoke only the getContentType()method. The operation is not guaranteed if any other method is invoked.
Do not send the streamed attachments of the received javax.activation.DataHandler class or the javax.xml.ws.Holder<DataHandler> class as it is in the Web Service client or Web Service Implementation Class after using them. While sending, generate a new javax.activation.DataHandler object, and then send the received streamed attachment.

32.2.4 Operating streamed attachments

(1) Points to be noted when operating the streamed attachments