Class TempOutputStream
- All Implemented Interfaces:
Disposable
,Closeable
,Flushable
,AutoCloseable
ByteArrayOutputStream
. If the collected bytes
rise above a configured threshold, bytes are collected instead in a temporary file that is removed when the output stream is closed. No additional buffering
is performed, allowing buffered to be controlled at a higher level.
An input stream to the collected bytes can be requested at any time using getInputStream()
. Retrieving an input stream effectively closes the output
stream and any future writes will fail. Retrieving an input stream also calls dispose()
, regardless of the auto-dispose setting.
Once the stream is closed, if auto-dispose is turned on the underlying output stream is released and the temporary file, if any, is deleted. Thus if it is
not known exactly when the stream will be closed, either auto-dispose should be turned off and/or a subclass should be created that overrides
OutputStreamDecorator.beforeClose()
, at which point getInputStream()
can be called to retrieve the written bytes.
It is very important to properly close this output stream when finished using it; otherwise, orphaned temporary files may remain. It is similarly important to close any retrieved input stream for the same reason.
- Author:
- Garret Wilson
-
Field Summary
Modifier and TypeFieldDescriptionstatic final int
The default threshold number of bytes for switching from memory to a temporary file. -
Constructor Summary
ConstructorDescriptionDefault constructor with default threshold, automatically callingdispose()
when closed.TempOutputStream
(boolean autoDispose) Auto-dispose constructor with default threshold.TempOutputStream
(int threshold) Threshold constructor, automatically callingdispose()
when closed.TempOutputStream
(int threshold, boolean autoDispose) Threshold constructor. -
Method Summary
Modifier and TypeMethodDescriptionprotected void
beforeWrite
(int len) Called before any writes occur, passing the number of bytes that will be written.void
close
(boolean closeDecoratedStream) Closes this output stream and releases any system resources associated with the stream.protected static File
Creates a temporary file.void
dispose()
Uninitializes the object.Flushes and retrieves an input stream to the current data.int
The threshold number of bytes for switching from memory to a temporary file.void
write
(byte[] b) This version performs pre-write checks and updates.void
write
(byte[] b, int off, int len) This version performs pre-write checks and updates.void
write
(int b) This version performs pre-write checks and updates.Methods inherited from class com.globalmentor.io.OutputStreamDecorator
afterClose, beforeClose, checkOutputStream, close, finalize, flush, getOutputStream, setOutputStream
-
Field Details
-
DEFAULT_THRESHOLD
public static final int DEFAULT_THRESHOLDThe default threshold number of bytes for switching from memory to a temporary file.- See Also:
-
-
Constructor Details
-
TempOutputStream
public TempOutputStream()Default constructor with default threshold, automatically callingdispose()
when closed.- See Also:
-
TempOutputStream
public TempOutputStream(boolean autoDispose) Auto-dispose constructor with default threshold.- Parameters:
autoDispose
- Whether the temporary files, if any, should be deleted.- See Also:
-
TempOutputStream
public TempOutputStream(int threshold) Threshold constructor, automatically callingdispose()
when closed. If the threshold is set to zero, this output stream will always use a temporary file.- Parameters:
threshold
- The threshold number of bytes for switching from memory to a temporary file.- Throws:
IllegalArgumentException
- if the given threshold is negative.
-
TempOutputStream
public TempOutputStream(int threshold, boolean autoDispose) Threshold constructor. If the threshold is set to zero, this output stream will always use a temporary file.- Parameters:
threshold
- The threshold number of bytes for switching from memory to a temporary file.autoDispose
- Whether the temporary files, if any, should be deleted.- Throws:
IllegalArgumentException
- if the given threshold is negative.
-
-
Method Details
-
getThreshold
public int getThreshold()The threshold number of bytes for switching from memory to a temporary file. If set to zero, this output stream will always use a temporary file.- Returns:
- The threshold number of bytes for switching from memory to a temporary file.
-
getInputStream
Flushes and retrieves an input stream to the current data. This method effectively closes the output stream, and no further writes will be allowed. Transfer of responsibility of the temporary file, if any, is transferred to the input stream, making it important that the consumer close the input stream when finished to ensure the temporary file is deleted.This method unconditionally calls
dispose()
, regardless of the auto-dispose setting.- Returns:
- An input stream to the current data.
- Throws:
IOException
- if the output stream has already been closed.IOException
- if there is an error retrieving an input stream to the data.- See Also:
-
beforeWrite
Called before any writes occur, passing the number of bytes that will be written.Examines the number of bytes prepared to write and, if writing them would surpass the threshold, switches immediately to a temporary file and writes the so-far accumulated bytes to that file.
- Parameters:
len
- The number of bytes ready to be written.- Throws:
IOException
- if the output stream has already been closed.IOException
- if there is an error updating the streams.- See Also:
-
write
This version performs pre-write checks and updates.- Overrides:
write
in classOutputStreamDecorator<OutputStream>
- Throws:
IOException
- See Also:
-
write
This version performs pre-write checks and updates.- Overrides:
write
in classOutputStreamDecorator<OutputStream>
- Throws:
IOException
- See Also:
-
write
This version performs pre-write checks and updates.- Overrides:
write
in classOutputStreamDecorator<OutputStream>
- Throws:
IOException
- See Also:
-
close
Closes this output stream and releases any system resources associated with the stream. A closed stream cannot perform output operations and cannot be reopened. If auto-dispose is enabled,OutputStreamDecorator.dispose()
will be called if closing is successful. This version does not allow closing without closing the decorated stream.- Overrides:
close
in classOutputStreamDecorator<OutputStream>
- Parameters:
closeDecoratedStream
- Whether the decorated stream should also be closed.- Throws:
IllegalArgumentException
- if the close decorated stream flag isfalse
.IOException
- if an I/O error occurs.- See Also:
-
createTempFile
Creates a temporary file. The file will not be marked for automatic deletion.- Returns:
- A new file for temporarily storing data.
- Throws:
IOException
- if there is an error creating a temporary file.
-
dispose
public void dispose()Uninitializes the object. After calling this method, the object should not be used further. This method can be called multiple times without danger. All exceptions should be caught and dealt with in this method. Child classes must call the parent class version. This version deletes the temporary file, if any.- Specified by:
dispose
in interfaceDisposable
- Overrides:
dispose
in classOutputStreamDecorator<OutputStream>
-