|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectbb.io.StreamUtil
public final class StreamUtil
Provides miscellaneous static utility methods for dealing with streams.
This class is multithread safe: it is immutable (both its immediate state, as well as the deep state of its fields).
This class checks for thread interruption only before major blocking operations in order to achieve a reasonable balance between cancellation responsiveness and program performance (see Doug Lea Concurrent Programming in Java Second Edition p. 170).
Nested Class Summary | |
---|---|
private static class |
StreamUtil.Drainer
Solely used by the internal worker thread of the above drain method. |
private static class |
StreamUtil.TransferProgressReporter
Solely used for reporting progress of the transfer method. |
static class |
StreamUtil.UnitTest
See the Overview page of the project's javadocs for a general description of this unit test class. |
Field Summary | |
---|---|
private static int |
bufferSizeDrainMin
Used by drain(InputStream) when it calls calcBufferSize
to set a lower bound on the size of the buffer used by drain. |
private static int |
bufferSizeTransfer
|
private static Class[] |
classArray
Cached value used by close . |
private static Object[] |
parameterArray
Cached value used by close . |
Constructor Summary | |
---|---|
private |
StreamUtil()
This sole private constructor suppresses the default (public) constructor, ensuring non-instantiability outside of this class. |
Method Summary | |
---|---|
private static int |
calcBufferSize(InputStream in,
int lengthMax)
First checks that in.available <= lengthMax, throwing an IllegalStateException if that constraint is not obeyed, since if it is violated then drain cannot work. |
static void |
close(Closeable closeable)
Immediately returns if obj is null. |
static void |
close(Object obj)
Immediately returns if obj is null. |
static byte[] |
drain(InputStream in)
Returns drain (in, Integer.MAX_VALUE). |
static byte[] |
drain(InputStream in,
int lengthMax)
Attempts to read all the bytes from in until End Of Stream is reached. |
static byte[] |
drain(InputStream in,
int lengthMax,
long timeout)
Returns drain (in, lengthMax),
if that call executes within timeout, else throws a TimeoutException. |
static char[] |
drainAsciiToChars(InputStream in)
Passes in to the drain(InputStream) method. |
static String |
drainIntoString(InputStream in)
Passes in to the drain(InputStream) method. |
static String |
drainIntoString(InputStream in,
String charEncoding)
Passes in to the drain(InputStream) method. |
static void |
readFully(InputStream in,
byte[] bytes)
Fully reads into the entire supplied byte[]. |
static void |
readFully(InputStream in,
byte[] bytes,
int offset,
int length)
Tries to read exactly the requested length from in into bytes. |
static void |
readFully(Reader in,
char[] chars)
Fully reads into the entire supplied char[]. |
static void |
readFully(Reader in,
char[] chars,
int offset,
int length)
Tries to read exactly the requested length from in into chars. |
static void |
transfer(InputStream in,
OutputStream out)
Simply calls transfer(in, out, null) . |
static void |
transfer(InputStream in,
OutputStream out,
PrintWriter logger)
Transfers all the data from in to out, that is, reads bytes from in and writes them to out until End Of Stream with in is reached. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
private static final int bufferSizeDrainMin
drain(InputStream)
when it calls calcBufferSize
to set a lower bound on the size of the buffer used by drain.
The size of this value needs to balance creating buffers that are too small (which causes resizes inside drain) versus being too large and wasting memory when the stream has only a little data.
private static final int bufferSizeTransfer
private static final Class[] classArray
close
.
private static final Object[] parameterArray
close
.
Constructor Detail |
---|
private StreamUtil()
Method Detail |
---|
public static void readFully(InputStream in, byte[] bytes) throws IllegalArgumentException, EOFException, IOException
readFully(in, bytes, 0, bytes.length)
IllegalArgumentException
- if in or bytes == null
EOFException
- if Hit End Of Stream before reading all the requested bytes
IOException
- if an I/O problem occurspublic static void readFully(InputStream in, byte[] bytes, int offset, int length) throws IllegalArgumentException, EOFException, IOException
This method is required because InputStream.read(byte[], int, int)
does not guarantee that requested length will be read,
whereas this method does (unless an Exception is thrown first).
Note: this method does not close in when finished.
IllegalArgumentException
- if in or bytes == null, offset or length are negative,
or offset + length are greater than bytes.length
EOFException
- if Hit End Of Stream before reading all the requested bytes
IOException
- if an I/O problem occurspublic static void readFully(Reader in, char[] chars) throws IllegalArgumentException, EOFException, IOException
readFully(in, chars, 0, chars.length)
IllegalArgumentException
- if in or chars == null
EOFException
- if Hit End Of Stream before reading all the requested chars
IOException
- if an I/O problem occurspublic static void readFully(Reader in, char[] chars, int offset, int length) throws IllegalArgumentException, EOFException, IOException
This method is required because Reader.read(char[], int, int)
does not guarantee that requested length will be read,
whereas this method does (unless an Exception is thrown first).
Note: this method does not close in when finished.
IllegalArgumentException
- if in or chars == null, offset or length are negative,
or offset + length are greater than chars.length
EOFException
- if Hit End Of Stream before reading all the requested chars
IOException
- if an I/O problem occurspublic static byte[] drain(InputStream in) throws IllegalArgumentException, IllegalStateException, IOException
drain
(in, Integer.MAX_VALUE).
IllegalArgumentException
- if in == null
IllegalStateException
- if in holds more than Integer.MAX_VALUE
bytes (which cannot be held in a java array)
IOException
- if an I/O problem occurspublic static byte[] drain(InputStream in, int lengthMax) throws IllegalArgumentException, IllegalStateException, IOException
This method blocks for an unlimited time until End Of Stream is reached;
see drain(InputStream, int, long)
for a version with timeout.
Note: the final action is to close in.
Warning: be careful with using this method on large capacity streams (e.g. GB sized files), since could run out of memory.
An alternative to this method might be to use NIO's Channels and ByteBuffers (especially mapped ones); see this sample code.
IllegalArgumentException
- if in == null; lengthMax <= 0
IllegalStateException
- if in holds more than lengthMax bytes
IOException
- if an I/O problem occursprivate static int calcBufferSize(InputStream in, int lengthMax) throws IOException, IllegalStateException
Assuming those checks are passed, then returns Math.max(in.available(),
.
In other words, the result is normally the amount of data available on the stream
except when that value is too small, in which case a min value is returned instead.
bufferSizeDrainMin
)
The reason why the amount of data available on the stream should normally be returned
is to handle InputStreams where the length should static
and fully determinable by calling the InputStream's available method (e.g. InputStreams from files).
In this case, drain(InputStream)
should be extremely efficient
because only a single buffer need be used with no further allocations or copying.
The reason why you need bufferSizeDrainMin to establish a lower bound is because some InputStreams (e.g. from sockets) cannot return an accurate value for the eventual amount of data that will be read.
IOException
- if an I/O problem occurs
IllegalStateException
- if in.available() > lengthMaxpublic static byte[] drain(InputStream in, int lengthMax, long timeout) throws Throwable
drain
(in, lengthMax),
if that call executes within timeout, else throws a TimeoutException.
From the caller's perspective, this is a synchronous method call. Internally, however, a new worker thread is created that does the actual call to drain which enables the calling thread to detect timeout.
in
- an arbitrary InputStreamlengthMax
- the maximum number of bytes that the stream should containtimeout
- the length of time (in ms) to allow for draining to occur
Throwable
- (or some subclass) if any problem occurs; in particular, note that throws
public static char[] drainAsciiToChars(InputStream in) throws IllegalArgumentException, IllegalStateException, IOException
drain(InputStream)
method.
Converts the returned byte[] into a char[] (using StringUtil.asciiBytesToChars
),
and returns that char[].
The data inside in must solely consist of US-ASCII bytes (i.e. no negative values).
IllegalArgumentException
- if in == null; a non-ascii byte (i.e. a negative value) is encountered
IllegalStateException
- if in holds more than Integer.MAX_VALUE
bytes (which cannot be held in a java array)
IOException
- if an I/O problem occurspublic static String drainIntoString(InputStream in, String charEncoding) throws IllegalArgumentException, IllegalStateException, IOException, UnsupportedEncodingException
drain(InputStream)
method.
Converts the returned byte[] into a String using the spacified char encoding, and returns that String.
IllegalArgumentException
- if in == null
IllegalStateException
- if in holds more than Integer.MAX_VALUE
bytes (which cannot be held in a java array)
IOException
- if an I/O problem occurs
UnsupportedEncodingException
- if charEncoding is not supportedpublic static String drainIntoString(InputStream in) throws IllegalArgumentException, IllegalStateException, IOException
drain(InputStream)
method.
Converts the returned byte[] into a String using the platform's default char encoding, and returns that String.
IllegalArgumentException
- if in == null
IllegalStateException
- if in holds more than Integer.MAX_VALUE
bytes (which cannot be held in a java array)
IOException
- if an I/O problem occurspublic static void transfer(InputStream in, OutputStream out) throws IllegalArgumentException, IOException
transfer(in, out, null)
.
IllegalArgumentException
- if in == null or if out == null
IOException
- if an I/O problem occurspublic static void transfer(InputStream in, OutputStream out, PrintWriter logger) throws IllegalArgumentException, IOException
Warning: this method does not close the streams; that is the caller's responsibility.
IllegalArgumentException
- if in == null or if out == null
IOException
- if an I/O problem occurspublic static void close(Closeable closeable)
closeable.close
.
Contract: this method should never throw a Throwable.
Any Throwable that is raised is caught and logged robustly
to the default Logger
.
public static void close(Object obj)
ReflectUtil.callLogError(Object, String)
(obj, "close")
.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |