Package org.jvnet.staxex

Class StreamingDataHandler

java.lang.Object
javax.activation.DataHandler
org.jvnet.staxex.StreamingDataHandler
All Implemented Interfaces:
Transferable, Closeable, AutoCloseable
Direct Known Subclasses:
StreamingDataHandler
public abstract class StreamingDataHandler extends javax.activation.DataHandler implements Closeable
DataHandler extended to offer better buffer management in a streaming environment.

DataHandler is used commonly as a data format across multiple systems (such as JAXB/WS.) Unfortunately, DataHandler has the semantics of "read as many times as you want", so this makes it difficult for involving parties to handle a BLOB in a streaming fashion.

StreamingDataHandler solves this problem by offering methods that enable faster bulk "consume once" read operation.

Author:
Jitendra Kotamraju

  • Constructor Summary

    Constructors
    Constructor
    Description
    StreamingDataHandler(Object o, String s)
     
    StreamingDataHandler(URL url)
     
    StreamingDataHandler(javax.activation.DataSource dataSource)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    abstract void
    close()
    Releases any resources associated with this DataHandler.
    String
    getHrefCid()
     
    abstract void
    moveTo(File dst)
    Obtains the BLOB into a specified file.
    abstract InputStream
    readOnce()
    Works like DataHandler.getInputStream() except that this method can be invoked only once.
    void
    setHrefCid(String cid)
     

    Methods inherited from class javax.activation.DataHandler

    getAllCommands, getBean, getCommand, getContent, getContentType, getDataSource, getInputStream, getName, getOutputStream, getPreferredCommands, getTransferData, getTransferDataFlavors, isDataFlavorSupported, setCommandMap, setDataContentHandlerFactory, writeTo

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • StreamingDataHandler

      public StreamingDataHandler(Object o, String s)

    • StreamingDataHandler

      public StreamingDataHandler(URL url)

    • StreamingDataHandler

      public StreamingDataHandler(javax.activation.DataSource dataSource)

  • Method Details

    • readOnce

      public abstract InputStream readOnce() throws IOException
      Works like DataHandler.getInputStream() except that this method can be invoked only once.

      This is used as a signal from the caller that there will be no further DataHandler.getInputStream() invocation nor readOnce() invocation on this object (which would result in IOException.)

      When DataHandler is backed by a streaming BLOB (such as an attachment in a web service read from the network), this allows the callee to avoid unnecessary buffering.

      Note that it is legal to call DataHandler.getInputStream() multiple times and then call readOnce() afterward. Streams created such a way can be read in any order — there's no requirement that streams created earlier must be read first.

      Returns:
      always non-null. Represents the content of this BLOB. The returned stream is generally not buffered, so for better performance read in a big batch or wrap this into BufferedInputStream.
      Throws:
      IOException - if any i/o error

    • moveTo

      public abstract void moveTo(File dst) throws IOException
      Obtains the BLOB into a specified file.

      Semantically, this method is roughly equivalent to the following code, except that the actual implementation is likely to be a lot faster. 

       InputStream i = getInputStream();
 OutputStream o = new FileOutputStream(dst);
 int ch;
 while((ch=i.read())!=-1)  o.write(ch);
 i.close();
 o.close();

      The main motivation behind this method is that often DataHandler that reads data from a streaming source will use a temporary file as a data store to hold data (think of commons-fileupload.) In such case this method can be as fast as calling File.renameTo(File).

      This method shouldn't be called when there are any open streams.

      After this method is invoked, readOnce() and DataHandler.getInputStream() will simply open the destination file you've specified as an argument. So if you further move the file or delete this file, those methods will behave in undefined fashion. For a simliar reason, calling this method multiple times will cause undefined behavior.

      Throws:
      IOException

    • close

      public abstract void close() throws IOException
      Releases any resources associated with this DataHandler. (such as an attachment in a web service read from a temp file will be deleted.) After calling this method, it is illegal to call any other methods.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException

    • getHrefCid

      public String getHrefCid()

    • setHrefCid

      public void setHrefCid(String cid)