org.gcube.contentmanagement.baselayer
Class BaseLayerStream

java.lang.Object
  extended by org.gcube.contentmanagement.baselayer.BaseLayerStream
Direct Known Subclasses:
BlobStream, InMemoryContentStream, SubstringStream

public class BaseLayerStream
extends java.lang.Object

This class provides a wrapper for arbitrary input streams. The intention here is to provide streams of known length, since some of the implementations of RawFileContentManager need this property. This version also provides some very basic support to determine the length of a stream by reading it into memory.


Field Summary
static int END_OF_STREAM
          Value that will be returned, when the stream end of the stream is reached and next byte was requested, e.g.
static long NO_LIMIT
          Defines that there is no limit set, on how many bytes to read at most from this stream.
static long STREAM_LENGTH_IMPLICITE
          Defines that the stream has no size, that is known before, so the length is given implicitely by reading until the END_OF_STREAM occurs.
static int URL_CONNECTION_LENGTH_UNKNOWN
          Defines the constant used by java.net.URLConnection to indicate, that the length of the content is unknown
 
Constructor Summary
BaseLayerStream(java.io.InputStream istream)
          Convenience constructor, if length is unknown.
BaseLayerStream(java.io.InputStream istream, long length)
          Contructor for a stream with a given length
 
Method Summary
 void dispose()
          Closes the BaseLayerStream which implies that all bound resources should be freed.
 java.io.InputStream getBufferedStream()
          Returns a buffered stream for the wrapped stream
 int getBufferSize()
          Return the number of bytes used for buffering
static int getDefaultBufferSize()
          Returns the default buffer size, which should be used in order to have buffers in similar size and therefore reduce overhead because calls for read(byte[]) will almost everytime fill the array entirely.
 long getLength()
          Returns the defined length of the stream
 long getLimit()
          Returns the limit
 java.io.InputStream getStream()
          Returns the wrapped input stream
 void handleStartOffset(BasicStorageHints hints)
          Evaluates whether a start offset has been requested by a hint and if so, performs the requested action.
 boolean hasImpliciteLength()
          Returns whether the stream has an implicite length
 boolean isBuffered()
          tells whether the stream is known to be buffered or not.
 boolean needsLimitTreatment()
          A limit has been set for this stream
 void setBuffered(boolean isBuffered)
          Sets if the stream is known to use some sort of internal buffering or is decorated by a BufferedInputStream already.
 void setBufferSize(int size)
          Sets the size of the buffer used by this stream, initially set to getDefaultBufferSize()
static void setDefaultBufferSize(int size)
          Sets the default buffer size, which should be used in order to have buffers in similar size and therefore reduce overhead because calls for read(byte[]) will almost everytime fill the array entirely.
 void setLimit(BasicStorageHints hints)
          Sets the limit iff this has been requested within the hints.
 void setLimit(long maximumLength)
          Defines a maximum number of bytes that should be read from this stream.
 BaseLayerStream toFixedLengthStream()
          Generic solution to determine stream length.
 long writeToStreamRespectingLimit(java.io.OutputStream out)
          Writes the content of this stream to a output stream.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

URL_CONNECTION_LENGTH_UNKNOWN

public static final int URL_CONNECTION_LENGTH_UNKNOWN
Defines the constant used by java.net.URLConnection to indicate, that the length of the content is unknown

See Also:
URLConnection.getContentLength(), Constant Field Values

STREAM_LENGTH_IMPLICITE

public static final long STREAM_LENGTH_IMPLICITE
Defines that the stream has no size, that is known before, so the length is given implicitely by reading until the END_OF_STREAM occurs.

See Also:
Constant Field Values

NO_LIMIT

public static final long NO_LIMIT
Defines that there is no limit set, on how many bytes to read at most from this stream.

See Also:
Constant Field Values

END_OF_STREAM

public static final int END_OF_STREAM
Value that will be returned, when the stream end of the stream is reached and next byte was requested, e.g. with read().
It's value have been set to -1 to be consistend with many of the InputStream implementations in the java.io -Package.

See Also:
InputStream.read(), InputStream.read(byte[]), FileInputStream.read(), Constant Field Values
Constructor Detail

BaseLayerStream

public BaseLayerStream(java.io.InputStream istream)
Convenience constructor, if length is unknown.

WARNING: May harmful to execution speed. Prefer setting the length if known.

Parameters:
istream - the stream that should be wrapped

BaseLayerStream

public BaseLayerStream(java.io.InputStream istream,
                       long length)
Contructor for a stream with a given length

Parameters:
istream - the stream that should be wrapped
length - the length in bytes of the stream
Method Detail

setDefaultBufferSize

public static void setDefaultBufferSize(int size)
Sets the default buffer size, which should be used in order to have buffers in similar size and therefore reduce overhead because calls for read(byte[]) will almost everytime fill the array entirely.

Parameters:
size - the size a buffer should use
See Also:
InputStream.read(byte[])

getDefaultBufferSize

public static int getDefaultBufferSize()
Returns the default buffer size, which should be used in order to have buffers in similar size and therefore reduce overhead because calls for read(byte[]) will almost everytime fill the array entirely.

Returns:
the default size for buffers
See Also:
InputStream.read(byte[])

setBufferSize

public void setBufferSize(int size)
Sets the size of the buffer used by this stream, initially set to getDefaultBufferSize()

Parameters:
size - number of bytes to use for buffering

getBufferSize

public int getBufferSize()
Return the number of bytes used for buffering

Returns:
number of bytes to use for buffering

getStream

public java.io.InputStream getStream()
Returns the wrapped input stream

Returns:
the input stream (as is)

getBufferedStream

public java.io.InputStream getBufferedStream()
Returns a buffered stream for the wrapped stream

Returns:
the stream as is, if it is buffered itself; otherwise a buffered version will be returend
See Also:
isBuffered()

isBuffered

public boolean isBuffered()
tells whether the stream is known to be buffered or not.

Returns:
if true, the stream is already buffered somehow; if false, it might be beneficial for the performance to decorate it with a java.io.BufferedInputStream
See Also:
BufferedInputStream

setBuffered

public void setBuffered(boolean isBuffered)
Sets if the stream is known to use some sort of internal buffering or is decorated by a BufferedInputStream already.

Parameters:
isBuffered - true, if the wrapped stream is buffered itself

getLength

public long getLength()
Returns the defined length of the stream

Returns:
the length of the stream or STREAM_LENGTH_IMPLICITE, if no length has been set

hasImpliciteLength

public boolean hasImpliciteLength()
Returns whether the stream has an implicite length

Returns:
false, if explicite length has been set; true otherwise

setLimit

public void setLimit(long maximumLength)
Defines a maximum number of bytes that should be read from this stream.

If this number has been read, it should be considered as if stream ended there. The number can exceed the actual number of bytes that the stream contains, in other words, the end of stream still needs to be checked.

Parameters:
maximumLength - the number of bytes

needsLimitTreatment

public boolean needsLimitTreatment()
A limit has been set for this stream

Returns:
true, if there is a limit on how many bytes should be read at most

getLimit

public long getLimit()
Returns the limit

Returns:
the limit of bytes that should be read at most

setLimit

public void setLimit(BasicStorageHints hints)
              throws ValueNotValidException
Sets the limit iff this has been requested within the hints.

Implicitely handles also a start offste (if set), because otherwise the result will be false.

Parameters:
hints - the hints that should be used to determine limit
Throws:
ValueNotValidException - if something goes wrong
See Also:
BasicStorageHints#HINT_NAME_LIMIT_CONTENT_LENGTH_READ

handleStartOffset

public void handleStartOffset(BasicStorageHints hints)
                       throws ValueNotValidException
Evaluates whether a start offset has been requested by a hint and if so, performs the requested action.

Parameters:
hints - the hints where this may get requested
Throws:
BaseLayerException - if something goes wrong
ValueNotValidException

writeToStreamRespectingLimit

public long writeToStreamRespectingLimit(java.io.OutputStream out)
                                  throws BaseLayerException
Writes the content of this stream to a output stream.

While doing this, any imposed limit on the bytes to transfer is taken care of.

Parameters:
out - the stream to which the content should be written
Returns:
the number of bytes actually written
Throws:
BaseLayerException - if something goes wrong

dispose

public void dispose()
             throws BaseLayerException
Closes the BaseLayerStream which implies that all bound resources should be freed.

Throws:
BaseLayerException - if something goes wrong

toFixedLengthStream

public BaseLayerStream toFixedLengthStream()
                                    throws BaseLayerException
Generic solution to determine stream length. If stream length is known, nothing happens. If stream length is unknown,

Returns:
a stream for which the length property has been determined
Throws:
BaseLayerException - if something goes wrong