Top Description Fields Constructors Methods
org.apache.derby.impl.jdbc

pack-priv final Class LOBStreamControl

extends Object
Class Inheritance
Imports
java.io.EOFException, .IOException, .InputStream, .OutputStream, .UTFDataFormatException, org.apache.derby.shared.common.error.StandardException, .ExceptionUtil, org.apache.derby.shared.common.reference.Property, .SQLState, .MessageId, org.apache.derby.shared.common.i18n.MessageService, org.apache.derby.iapi.services.monitor.Monitor, org.apache.derby.iapi.store.raw.data.DataFactory, org.apache.derby.io.StorageFile
This class acts as a layer of blob/clob repository (in memory or file). The max bytes of data stored in memory depends on the way this class is created. If the class is created with initial data, the buffer size is set to the size of the byte array supplied, but no larger than MAX_BUF_SIZE. If no initial data is supplied, or if the initial data size is less than DEFAULT_BUF_SIZE, the buffer size is set to DEFAULT_BUF_SIZE. When write increases the data beyond this value a temporary file is created and data is moved into that. If truncate reduces the size of the file below initial buffer size, the data is moved into memory. This class also creates InputStream and OutputStream which can be used to access blob data irrespective of if its in memory or in file.

Field Summary

Modifier and TypeField and Description
private final int
bufferSize

private final EmbedConnection
conn

private byte[]
dataBytes

private static final int
DEFAULT_BUF_SIZE

private boolean
isBytes

private static final int
MAX_BUF_SIZE

private LOBFile
tmpFile

private long
updateCount

Constructor Summary

AccessConstructor and Description
pack-priv
LOBStreamControl(EmbedConnection
Connection for this lob
conn)

Creates an empty LOBStreamControl.

pack-priv
LOBStreamControl(EmbedConnection
Connection for this lob
conn, byte[]
initial value
data)

Creates a LOBStreamControl and initializes with a bytes array.

Method Summary

Modifier and TypeMethod and Description
pack-priv synchronized void
copyData(InputStream
the stream to copy from
inStream, long
number of bytes to be copied, or Long.MAX_VALUE to copy everything until EOF is reached
length)

Copies bytes from stream to local storage.

pack-priv synchronized long

Returns:

The number of characters copied.
copyUtf8Data(final InputStream
the stream to copy from
utf8Stream, final long
number of chars to be copied, or Long.MAX_VALUE to copy everything until EOF is reached
charLength)

Copies UTF-8 encoded chars from a stream to local storage.

private void
deleteFile(final StorageFile file)

protected void
finalize()

Overrides java.lang.Object.finalize.

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.

private static Object
findService(final String factoryInterface, final String serviceName)

Must be private so that user code can't call this entry point.

private static Object
findServiceModule(final Object serviceModule, final String factoryInterface)

Must be private so that user code can't call this entry point.

pack-priv void
free()

Invalidates all the variables and closes file handle if open.

pack-priv InputStream

Returns:

InputStream
getInputStream(long
initial postion
pos)

returns input stream linked with this object.

pack-priv long

Returns:

length
getLength()

Returns length of data.

pack-priv OutputStream

Returns:

OutputStream
getOutputStream(long
initial postion
pos)

returns output stream linked with this object

pack-priv long

Returns:

The current update sequence number.
getUpdateCount()

Returns the running sequence number to check if the lob is updated since last access.

private void
init(byte[] b, long len)

private void
isValidOffset(int off, int length)

private void
isValidPostion(long pos)

pack-priv synchronized int

Returns:

byte
read(long
position from where to read
pos)

Reads one byte.

pack-priv synchronized int

Returns:

number new position
read(byte[]
array into the bytes will be copied
buff, int
offset from where the array has to be populated
off, int
number of bytes to read
len, long
initial position before reading
pos)

Reads bytes starting from 'position' into bytes array.

private int
readBytes(byte[] b, int off, int len, long pos)

private void
releaseTempFile(LOBFile
the temporary file
file)

Close and release all resources held by a temporary file.

pack-priv synchronized long

Returns:

Current position after write.
replaceBytes(byte[]
byte array which will be written inplace of old block
buf, long
inclusive starting position of current block
stPos, long
exclusive end position of current block
endPos)

Replaces a block of bytes in the middle of the LOB with a another block of bytes, which may be of a different size.

pack-priv synchronized void
truncate(long
new size should be smaller than existing size
size)

Resets the size.

private long
updateData(byte[] bytes, int offset, int len, long pos)

pack-priv synchronized long

Returns:

new position
write(int
byte
b, long pos)

Writes one byte.

pack-priv synchronized long

Returns:

The position after the bytes have been written to the LOB.
write(byte[]
byte array
b, int
offset from where to read from the byte array
off, int
number of bytes to be written
len, long
starting position
pos)

Writes len bytes from the specified byte array to the LOB.

Inherited from java.lang.Object:
cloneequalsgetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

bufferSizeback to summary
private final int bufferSize
connback to summary
private final EmbedConnection conn
dataBytesback to summary
private byte[] dataBytes
DEFAULT_BUF_SIZEback to summary
private static final int DEFAULT_BUF_SIZE
isBytesback to summary
private boolean isBytes
MAX_BUF_SIZEback to summary
private static final int MAX_BUF_SIZE
tmpFileback to summary
private LOBFile tmpFile
updateCountback to summary
private long updateCount

Constructor Detail

LOBStreamControlback to summary
pack-priv LOBStreamControl(EmbedConnection conn)

Creates an empty LOBStreamControl.

Parameters
conn:EmbedConnection

Connection for this lob

LOBStreamControlback to summary
pack-priv LOBStreamControl(EmbedConnection conn, byte[] data) throws IOException, StandardException

Creates a LOBStreamControl and initializes with a bytes array.

Parameters
conn:EmbedConnection

Connection for this lob

data:byte[]

initial value

Method Detail

copyDataback to summary
pack-priv synchronized void copyData(InputStream inStream, long length) throws IOException, StandardException

Copies bytes from stream to local storage.

Note that specifying the length as Long.MAX_VALUE results in reading data from the stream until EOF is reached, but no length checking will be performed.

Parameters
inStream:InputStream

the stream to copy from

length:long

number of bytes to be copied, or Long.MAX_VALUE to copy everything until EOF is reached

Exceptions
IOException:
if reading or writing a LOB file fails
StandardException:
if encrypting or decrypting a LOB file fails
copyUtf8Databack to summary
pack-priv synchronized long copyUtf8Data(final InputStream utf8Stream, final long charLength) throws IOException, StandardException

Copies UTF-8 encoded chars from a stream to local storage.

Note that specifying the length as Long.MAX_VALUE results in reading data from the stream until EOF is reached, but no length checking will be performed.

Parameters
utf8Stream:InputStream

the stream to copy from

charLength:long

number of chars to be copied, or Long.MAX_VALUE to copy everything until EOF is reached

Returns:long

The number of characters copied.

Exceptions
IOException:
thrown on a number of error conditions
StandardException:
if reading, writing or truncating the LOBStreamControl-object fails
EOFException:
if EOF is reached prematurely
UTFDataFormatException:
if an invalid UTF-8 encoding is detected
deleteFileback to summary
private void deleteFile(final StorageFile file)
finalizeback to summary
protected void finalize() throws Throwable

Overrides java.lang.Object.finalize.

Doc from java.lang.Object.finalize.

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. A subclass overrides the finalize method to dispose of system resources or to perform other cleanup.

When running in a Java virtual machine in which finalization has been disabled or removed, the garbage collector will never call finalize(). In a Java virtual machine in which finalization is enabled, the garbage collector might call finalize only after an indefinite delay.

The general contract of finalize is that it is invoked if and when the Java virtual machine has determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, except as a result of an action taken by the finalization of some other object or class which is ready to be finalized. The finalize method may take any action, including making this object available again to other threads; the usual purpose of finalize, however, is to perform cleanup actions before the object is irrevocably discarded. For example, the finalize method for an object that represents an input/output connection might perform explicit I/O transactions to break the connection before the object is permanently discarded.

The finalize method of class Object performs no special action; it simply returns normally. Subclasses of Object may override this definition.

The Java programming language does not guarantee which thread will invoke the finalize method for any given object. It is guaranteed, however, that the thread that invokes finalize will not be holding any user-visible synchronization locks when finalize is invoked. If an uncaught exception is thrown by the finalize method, the exception is ignored and finalization of that object terminates.

After the finalize method has been invoked for an object, no further action is taken until the Java virtual machine has again determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, including possible actions by other objects or classes which are ready to be finalized, at which point the object may be discarded.

The finalize method is never invoked more than once by a Java virtual machine for any given object.

Any exception thrown by the finalize method causes the finalization of this object to be halted, but is otherwise ignored.

Annotations
@SuppressWarnings:deprecation, removal
Exceptions
Throwable:
the Exception raised by this method
findServiceback to summary
private static Object findService(final String factoryInterface, final String serviceName)

Must be private so that user code can't call this entry point.

findServiceModuleback to summary
private static Object findServiceModule(final Object serviceModule, final String factoryInterface) throws StandardException

Must be private so that user code can't call this entry point.

freeback to summary
pack-priv void free() throws IOException

Invalidates all the variables and closes file handle if open.

Exceptions
IOException:
if closing the file fails
getInputStreamback to summary
pack-priv InputStream getInputStream(long pos)

returns input stream linked with this object.

Parameters
pos:long

initial postion

Returns:InputStream

InputStream

getLengthback to summary
pack-priv long getLength() throws IOException

Returns length of data.

Returns:long

length

getOutputStreamback to summary
pack-priv OutputStream getOutputStream(long pos)

returns output stream linked with this object

Parameters
pos:long

initial postion

Returns:OutputStream

OutputStream

getUpdateCountback to summary
pack-priv long getUpdateCount()

Returns the running sequence number to check if the lob is updated since last access.

Returns:long

The current update sequence number.

initback to summary
private void init(byte[] b, long len) throws IOException, StandardException
isValidOffsetback to summary
private void isValidOffset(int off, int length) throws StandardException
isValidPostionback to summary
private void isValidPostion(long pos) throws IOException, StandardException
readback to summary
pack-priv synchronized int read(long pos) throws IOException, StandardException

Reads one byte.

Parameters
pos:long

position from where to read

Returns:int

byte

Exceptions
IOException:
if reading the LOB file fails
StandardException:
if decrypting an encrypted LOB file fails
readback to summary
pack-priv synchronized int read(byte[] buff, int off, int len, long pos) throws IOException, StandardException

Reads bytes starting from 'position' into bytes array. starting from 'offset'

Parameters
buff:byte[]

array into the bytes will be copied

off:int

offset from where the array has to be populated

len:int

number of bytes to read

pos:long

initial position before reading

Returns:int

number new position

Exceptions
IOException:
if reading the LOB file fails
StandardException:
if decrypting an encrypted LOB file fails
readBytesback to summary
private int readBytes(byte[] b, int off, int len, long pos)
releaseTempFileback to summary
private void releaseTempFile(LOBFile file) throws IOException

Close and release all resources held by a temporary file. The file will also be deleted from the file system and removed from the list of LOBFiles in EmbedConnection.

Parameters
file:LOBFile

the temporary file

Exceptions
IOException:
if the file cannot be closed or deleted
replaceBytesback to summary
pack-priv synchronized long replaceBytes(byte[] buf, long stPos, long endPos) throws IOException, StandardException

Replaces a block of bytes in the middle of the LOB with a another block of bytes, which may be of a different size.

The new byte array may not be be of same length as the original, thus it may result in resizing the total lob.

Parameters
buf:byte[]

byte array which will be written inplace of old block

stPos:long

inclusive starting position of current block

endPos:long

exclusive end position of current block

Returns:long

Current position after write.

Exceptions
IOException:
if writing to the temporary file fails
truncateback to summary
pack-priv synchronized void truncate(long size) throws IOException, StandardException

Resets the size.

Parameters
size:long

new size should be smaller than existing size

updateDataback to summary
private long updateData(byte[] bytes, int offset, int len, long pos) throws StandardException
writeback to summary
pack-priv synchronized long write(int b, long pos) throws IOException, StandardException

Writes one byte.

Parameters
b:int

byte

Returns:long

new position

Exceptions
IOException:
if writing to the LOB file fails
StandardException:
if encrypting/decrypting the LOB file fails
writeback to summary
pack-priv synchronized long write(byte[] b, int off, int len, long pos) throws IOException, StandardException

Writes len bytes from the specified byte array to the LOB.

Parameters
b:byte[]

byte array

off:int

offset from where to read from the byte array

len:int

number of bytes to be written

pos:long

starting position

Returns:long

The position after the bytes have been written to the LOB.

Exceptions
IOException:
if writing to the LOB fails
StandardException:
if writing to the LOB fails
IndexOutOfBoundsException:
if len is larger than b.length - off