JAXB OSGI 4.0.9 · org.jvnet.staxex.StreamingDataHandler

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.

Modifier and Type	Field and Description
private String	hrefCid

Constructor Summary

Access	Constructor and Description
public	StreamingDataHandler(Object o, String s)
public	StreamingDataHandler(URL url)
public	StreamingDataHandler(DataSource dataSource)

Method Summary

Modifier and Type	Method and Description
public abstract void	close() Redeclares java.io.Closeable.close. Releases any resources associated with this DataHandler.
public String	getHrefCid()
public abstract void	moveTo(File dst) Obtains the BLOB into a specified file.
public abstract InputStream	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`. readOnce() Works like `getInputStream()` except that this method can be invoked only once.
public void	setHrefCid(final String cid)

Inherited from jakarta.activation.DataHandler:: getAllCommands getBean getCommand getContent getContentType getDataSource getInputStream getName getOutputStream getPreferredCommands getTransferData getTransferDataFlavors isDataFlavorSupported setCommandMap setDataContentHandlerFactory writeTo

Field Detail

hrefCid	back to summary
private String hrefCid

Constructor Detail

StreamingDataHandler	back to summary
public StreamingDataHandler(Object o, String s)

StreamingDataHandler	back to summary
public StreamingDataHandler(URL url)

StreamingDataHandler	back to summary
public StreamingDataHandler(DataSource dataSource)

Method Detail

close	back to summary
public abstract void close() throws IOException Redeclares java.io.Closeable.close. 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. Annotations @Override Exceptions IOException: for errors

back to summary

public abstract void close() throws IOException

Redeclares java.io.Closeable.close.

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.

Annotations

@Override

Exceptions

IOException:: for errors

getHrefCid	back to summary
public String getHrefCid()

moveTo back to summary

moveTo	back to summary
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 `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. Exceptions IOException: for errors

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 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.

Exceptions

IOException:: for errors

readOnce back to summary

readOnce	back to summary
public abstract InputStream readOnce() throws IOException Works like `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 `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 `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:InputStream 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`. Exceptions IOException: if any i/o error

public abstract InputStream readOnce() throws IOException

Works like 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 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 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:InputStream

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.

Exceptions

IOException:: if any i/o error

setHrefCid	back to summary
public void setHrefCid(final String cid)

public abstract Class StreamingDataHandler

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail