public abstract class StreamingDataHandler extends 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.
Constructor and Description |
---|
StreamingDataHandler(DataSource dataSource) |
StreamingDataHandler(Object o,
String s) |
StreamingDataHandler(URL url) |
Modifier and Type | Method and 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) |
getAllCommands, getBean, getCommand, getContent, getContentType, getDataSource, getInputStream, getName, getOutputStream, getPreferredCommands, getTransferData, getTransferDataFlavors, isDataFlavorSupported, setCommandMap, setDataContentHandlerFactory, writeTo
public StreamingDataHandler(URL url)
public StreamingDataHandler(DataSource dataSource)
public abstract InputStream readOnce() throws IOException
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.
BufferedInputStream
.IOException
- if any i/o errorpublic abstract void moveTo(File dst) throws IOException
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.
IOException
public abstract void close() throws IOException
close
in interface Closeable
close
in interface AutoCloseable
IOException
public String getHrefCid()
public void setHrefCid(String cid)
Copyright © 2021 JBoss by Red Hat. All rights reserved.