Package net.sourceforge.jtds.util
Class BlobBuffer
java.lang.Object
net.sourceforge.jtds.util.BlobBuffer
Manages a buffer (backed by optional disk storage) for use as a data store
by the CLOB and BLOB objects.
The data can be purely memory based until the size exceeds the value
dictated by the
lobBuffer
URL property after which it will be
written to disk. The disk array is accessed randomly one page (1024 bytes)
at a time.
This class is not synchronized and concurrent open input and output
streams can conflict.
Tuning hints:
- The
PAGE_SIZE
governs how much data is buffered when reading or writing data a byte at a time. 1024 bytes seems to work well but if very large objects are being written a byte at a time 4096 may be better. NB. ensure that thePAGE_MASK
andBYTE_MASK
fields are also adjusted to match. - Reading or writing byte arrays that are greater than or equal to the page size will go directly to or from the random access file cutting out an ArrayCopy operation.
- If BLOBs are being buffered exclusively in memory you may wish to
adjust the
MAX_BUF_INC
value. Every time the buffer is expanded the existing contents are copied and this may get expensive with very large BLOBs. - The BLOB file will be kept open for as long as there are open input or output streams. Therefore BLOB streams should be explicitly closed as soon as they are finished with.
- Version:
- $Id: BlobBuffer.java,v 1.4.2.1 2009-08-03 12:31:00 ickzon Exp $
- Author:
- Mike Hutchinson
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate class
An ASCIIInputStream
over the CLOB buffer.private class
Implements an ASCIIOutputStream
for CLOB data.private class
AnInputStream
over the BLOB buffer.private class
Implements anOutputStream
for BLOB data.private class
A Big Endian UnicodeInputStream
over the CLOB buffer. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate File
The name of the temporary BLOB disk file.private byte[]
The BLOB buffer or the current page buffer.private final File
The directory to buffer data to.private boolean
Indicates page in memory must be saved.private static final int
Mask for page offset component of R/W pointer.private int
The number of the current page in memory.private static final byte[]
Default zero length buffer.private static final int
Invalid page marker.private boolean
True if attempts to create a BLOB file have failed or the buffer is created without specifying a buffer directory.private int
The total length of the valid data in buffer.private static final int
Maximum buffer increment.private final int
The maximum size of an in memory buffer.private int
Count of callers that have opened the BLOB file.private static final int
Mask for page component of read/write pointer.private static final int
Default page size (must be power of 2).private RandomAccessFile
The RA file object reference or null if closed. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionvoid
close()
Logically closes the file or physically close it if the open count is now zero.void
Creates a random access disk file to use as backing storage for the LOB data.protected void
finalize()
Finalizes this object by deleting any work files.getBinaryStream
(boolean ascii) Retrieve the BLOB data as anInputStream
.byte[]
getBytes
(long pos, int len) Returns the BLOB data as a byte array.long
Retrieves the length of this BLOB buffer in bytes.Retrieve the BLOB data as an Big Endian UnicodeInputStream
.void
growBuffer
(int minSize) Increases the size of the in memory buffer for situations where disk storage of BLOB is not possible.void
open()
Opens the BLOB disk file.int
position
(byte[] pattern, long start) Provides support for pattern searching methods.int
read
(int readPtr) Reads byte from the BLOB buffer at the specified location.int
read
(int readPtr, byte[] bytes, int offset, int len) Reads bytes from the BLOB buffer at the specified location.void
readPage
(int page) Reads in the specified page from the disk buffer.setBinaryStream
(long pos, boolean ascii) Creates anOutputStream
that can be used to update the BLOB.void
setBuffer
(byte[] bytes, boolean copy) Sets the initial buffer to an existing byte array.int
setBytes
(long pos, byte[] bytes, int offset, int len, boolean copy) Sets the content of the BLOB to the supplied byte array value.void
setLength
(long length) Retrieves the length of the BLOB buffer (in memory version only).void
truncate
(long len) Truncates the BLOB buffer to the specified size.(package private) void
write
(int writePtr, byte[] bytes, int offset, int len) Inserts bytes into the buffer at the specified location.void
write
(int writePtr, int b) Inserts a byte into the buffer at the specified location.void
writePage
(int page) Writes the specified page to the disk buffer.
-
Field Details
-
EMPTY_BUFFER
private static final byte[] EMPTY_BUFFERDefault zero length buffer. -
PAGE_SIZE
private static final int PAGE_SIZEDefault page size (must be power of 2).- See Also:
-
PAGE_MASK
private static final int PAGE_MASKMask for page component of read/write pointer.- See Also:
-
BYTE_MASK
private static final int BYTE_MASKMask for page offset component of R/W pointer.- See Also:
-
MAX_BUF_INC
private static final int MAX_BUF_INCMaximum buffer increment.- See Also:
-
INVALID_PAGE
private static final int INVALID_PAGEInvalid page marker.- See Also:
-
buffer
private byte[] bufferThe BLOB buffer or the current page buffer. -
length
private int lengthThe total length of the valid data in buffer. -
currentPage
private int currentPageThe number of the current page in memory. -
blobFile
The name of the temporary BLOB disk file. -
raFile
The RA file object reference or null if closed. -
bufferDirty
private boolean bufferDirtyIndicates page in memory must be saved. -
openCount
private int openCountCount of callers that have opened the BLOB file. -
isMemOnly
private boolean isMemOnlyTrue if attempts to create a BLOB file have failed or the buffer is created without specifying a buffer directory. -
bufferDir
The directory to buffer data to. -
maxMemSize
private final int maxMemSizeThe maximum size of an in memory buffer.
-
-
Constructor Details
-
BlobBuffer
Creates a blob buffer.- Parameters:
bufferDir
-maxMemSize
- the maximum size of the in memory buffer
-
-
Method Details
-
finalize
Finalizes this object by deleting any work files. -
createBlobFile
public void createBlobFile()Creates a random access disk file to use as backing storage for the LOB data. This method may fail due to security exceptions or local disk problems, in which case the blob storage will remain entirely in memory. -
open
Opens the BLOB disk file. A count of open and close requests is kept so that the file may be closed when no longer required thus keeping the number of open files to a minimum.- Throws:
IOException
- if an I/O error occurs
-
read
Reads byte from the BLOB buffer at the specified location. The read pointer is partitioned into a page number and an offset within the page. This routine will read new pages as required. The page size must be a power of 2 and is currently set to 1024 bytes.- Parameters:
readPtr
- the offset in the buffer of the required byte- Returns:
- the byte value as an
int
or -1 if at EOF - Throws:
IOException
- if an I/O error occurs
-
read
Reads bytes from the BLOB buffer at the specified location.- Parameters:
readPtr
- the offset in the buffer of the required bytebytes
- the byte array to filloffset
- the start position in the byte arraylen
- the number of bytes to read- Returns:
- the number of bytes read or -1 if at end of file
- Throws:
IOException
- if an I/O error occurs
-
write
Inserts a byte into the buffer at the specified location. The write pointer is partitioned into a page number and an offset within the page. This routine will write new pages as required. The page size must be a power of 2 and is currently set to 1024 bytes.- Parameters:
writePtr
- the offset in the buffer of the required byteb
- the byte value to write- Throws:
IOException
- if an I/O error occurs
-
write
Inserts bytes into the buffer at the specified location.- Parameters:
writePtr
- the offset in the buffer of the required bytebytes
- the byte array value to writeoffset
- the start position in the byte arraylen
- the number of bytes to write- Throws:
IOException
- if an I/O error occurs
-
readPage
Reads in the specified page from the disk buffer. Any existing dirty page is first saved to disk.- Parameters:
page
- the page number- Throws:
IOException
- if an I/O error occurs
-
writePage
Writes the specified page to the disk buffer.- Parameters:
page
- the page number- Throws:
IOException
- if an I/O error occurs
-
close
Logically closes the file or physically close it if the open count is now zero. Any updated buffer in memory is flushed to disk before the file is closed.- Throws:
IOException
- if an I/O error occurs
-
growBuffer
public void growBuffer(int minSize) Increases the size of the in memory buffer for situations where disk storage of BLOB is not possible.- Parameters:
minSize
- the minimum size of buffer required
-
setBuffer
public void setBuffer(byte[] bytes, boolean copy) Sets the initial buffer to an existing byte array.- Parameters:
bytes
- the byte array containing the BLOB datacopy
- true if a local copy of the data is required
-
getBytes
Returns the BLOB data as a byte array.- Parameters:
pos
- the start position in the BLOB buffer (from 1)len
- the number of bytes to copy- Returns:
- the requested data as a
byte[]
- Throws:
SQLException
-
getBinaryStream
Retrieve the BLOB data as anInputStream
.- Parameters:
ascii
- true if an ASCII input stream should be returned- Returns:
- the
InputStream
built over the BLOB data - Throws:
SQLException
- if an error occurs
-
getUnicodeStream
Retrieve the BLOB data as an Big Endian UnicodeInputStream
.- Returns:
- the
InputStream
built over the BLOB data - Throws:
SQLException
- if an error occurs
-
setBinaryStream
Creates anOutputStream
that can be used to update the BLOB. Given that we cannot know the final size of a BLOB created by the caller of this method, we assume the worst and create a disk BLOB by default.- Parameters:
pos
- the start position in the buffer (from 1)ascii
- true if an ASCII output stream is required- Returns:
- the
OutputStream
to be used to update the BLOB - Throws:
SQLException
- if an error occurs
-
setBytes
Sets the content of the BLOB to the supplied byte array value. If the following conditions are met:- The start position is 1
- The existing BLOB length is smaller or the same as the length of the new data
- The new data length does not exceed the in memory limit
- Parameters:
pos
- the start position in the buffer (from 1)bytes
- the byte array containing the data to copyoffset
- the start position in the byte array (from 0)len
- the number of bytes to copycopy
- true if a local copy of the byte array is required- Returns:
- the number of bytes copied
- Throws:
SQLException
- if an error occurs
-
getLength
public long getLength()Retrieves the length of this BLOB buffer in bytes.- Returns:
- the length of the BLOB data in bytes
-
setLength
public void setLength(long length) Retrieves the length of the BLOB buffer (in memory version only).- Parameters:
length
- the length of the valid data in the buffer
-
truncate
Truncates the BLOB buffer to the specified size.- Parameters:
len
- the required length- Throws:
SQLException
- if an error occurs
-
position
Provides support for pattern searching methods.- Parameters:
pattern
- the byte array containg the search patternstart
- the start position in the BLOB (from 1)- Returns:
- the
int
start index for the pattern (from 1) or -1 if the pattern is not found. - Throws:
SQLException
- if an error occurs
-