Java Doc for StreamingDataHandler.java in  » XML » stax-ex » org » jvnet » staxex » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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

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, StreamingDataHandler.readOnce() and StreamingDataHandler.getInputStream() will simply open the destination file you've specified as an argument.

This is used as a signal from the caller that there will be no further StreamingDataHandler.getInputStream() invocation nor StreamingDataHandler.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 StreamingDataHandler.getInputStream() multiple times and then call StreamingDataHandler.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. always non-null.

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, StreamingDataHandler.readOnce() and StreamingDataHandler.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.

This is used as a signal from the caller that there will be no further StreamingDataHandler.getInputStream() invocation nor StreamingDataHandler.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 StreamingDataHandler.getInputStream() multiple times and then call StreamingDataHandler.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. always non-null. Represents the content of this BLOB.The returned stream is generally not buffered, so forbetter performance read in a big batch or wrap this intoBufferedInputStream.
throws:
  IOException - if any i/o error