net.sourceforge.jtds.util
Class BlobBuffer

java.lang.Object
  net.sourceforge.jtds.util.BlobBuffer

public class BlobBuffer

extends java.lang.Object

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:

1. 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 the PAGE_MASK and BYTE_MASK fields are also adjusted to match.
2. 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.
3. 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.
4. 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

private class	BlobBuffer.AsciiInputStream An ASCII InputStream over the CLOB buffer.
private class	BlobBuffer.AsciiOutputStream Implements an ASCII OutputStream for CLOB data.
private class	BlobBuffer.BlobInputStream An InputStream over the BLOB buffer.
private class	BlobBuffer.BlobOutputStream Implements an OutputStream for BLOB data.
private class	BlobBuffer.UnicodeInputStream A Big Endian Unicode InputStream over the CLOB buffer.

Field Summary

private java.io.File	blobFile The name of the temporary BLOB disk file.
private byte[]	buffer The BLOB buffer or the current page buffer.
private java.io.File	bufferDir The directory to buffer data to.
private boolean	bufferDirty Indicates page in memory must be saved.
private static int	BYTE_MASK Mask for page offset component of R/W pointer.
private int	currentPage The number of the current page in memory.
private static byte[]	EMPTY_BUFFER Default zero length buffer.
private static int	INVALID_PAGE Invalid page marker.
private boolean	isMemOnly True if attempts to create a BLOB file have failed.
private int	length The total length of the valid data in buffer.
private static int	MAX_BUF_INC Maximum buffer increment.
private int	maxMemSize The maximum size of an in memory buffer.
private int	openCount Count of callers that have opened the BLOB file.
private static int	PAGE_MASK Mask for page component of read/write pointer.
private static int	PAGE_SIZE Default page size (must be power of 2).
private java.io.RandomAccessFile	raFile The RA file object reference or null if closed.

Constructor Summary

BlobBuffer(java.io.File bufferDir, long maxMemSize)
Creates a blob buffer.

Method Summary

void	close() Logically closes the file or physically close it if the open count is now zero.
void	createBlobFile() 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.
java.io.InputStream	getBinaryStream(boolean ascii) Retrieve the BLOB data as an InputStream.
byte[]	getBytes(long pos, int len) Returns the BLOB data as a byte array.
long	getLength() Retrieves the length of this BLOB buffer in bytes.
java.io.InputStream	getUnicodeStream() Retrieve the BLOB data as an Big Endian Unicode InputStream.
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.
java.io.OutputStream	setBinaryStream(long pos, boolean ascii) Creates an OutputStream 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.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

EMPTY_BUFFER

private static final byte[] EMPTY_BUFFER

Default zero length buffer.

PAGE_SIZE

private static final int PAGE_SIZE

Default page size (must be power of 2).

See Also:

Constant Field Values

PAGE_MASK

private static final int PAGE_MASK

Mask for page component of read/write pointer.

See Also:

Constant Field Values

BYTE_MASK

private static final int BYTE_MASK

Mask for page offset component of R/W pointer.

See Also:

Constant Field Values

MAX_BUF_INC

private static final int MAX_BUF_INC

Maximum buffer increment.

See Also:

Constant Field Values

INVALID_PAGE

private static final int INVALID_PAGE

Invalid page marker.

See Also:

Constant Field Values

buffer

private byte[] buffer

The BLOB buffer or the current page buffer.

length

private int length

The total length of the valid data in buffer.

currentPage

private int currentPage

The number of the current page in memory.

blobFile

private java.io.File blobFile

The name of the temporary BLOB disk file.

raFile

private java.io.RandomAccessFile raFile

The RA file object reference or null if closed.

bufferDirty

private boolean bufferDirty

Indicates page in memory must be saved.

openCount

private int openCount

Count of callers that have opened the BLOB file.

isMemOnly

private boolean isMemOnly

True if attempts to create a BLOB file have failed.

bufferDir

private final java.io.File bufferDir

The directory to buffer data to.

maxMemSize

private final int maxMemSize

The maximum size of an in memory buffer.

Constructor Detail

BlobBuffer

public BlobBuffer(java.io.File bufferDir,
                  long maxMemSize)

Creates a blob buffer.

Parameters:

bufferDir -

maxMemSize - the maximum size of the in memory buffer

Method Detail

finalize

protected void finalize()
                 throws java.lang.Throwable

Finalizes this object by deleting any work files.

Throws:

java.lang.Throwable

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

public void open()
          throws java.io.IOException

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:

java.io.IOException - if an I/O error occurs

read

public int read(int readPtr)
         throws java.io.IOException

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:

java.io.IOException - if an I/O error occurs

read

public int read(int readPtr,
                byte[] bytes,
                int offset,
                int len)
         throws java.io.IOException

Reads bytes from the BLOB buffer at the specified location.

Parameters:

readPtr - the offset in the buffer of the required byte

bytes - the byte array to fill

offset - the start position in the byte array

len - the number of bytes to read

Returns:

the number of bytes read or -1 if at end of file

Throws:

java.io.IOException - if an I/O error occurs

write

public void write(int writePtr,
                  int b)
           throws java.io.IOException

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 byte

b - the byte value to write

Throws:

java.io.IOException - if an I/O error occurs

write

void write(int writePtr,
           byte[] bytes,
           int offset,
           int len)
     throws java.io.IOException

Inserts bytes into the buffer at the specified location.

Parameters:

writePtr - the offset in the buffer of the required byte

bytes - the byte array value to write

offset - the start position in the byte array

len - the number of bytes to write

Throws:

java.io.IOException - if an I/O error occurs

readPage

public void readPage(int page)
              throws java.io.IOException

Reads in the specified page from the disk buffer.

Any existing dirty page is first saved to disk.

Parameters:

page - the page number

Throws:

java.io.IOException - if an I/O error occurs

writePage

public void writePage(int page)
               throws java.io.IOException

Writes the specified page to the disk buffer.

Parameters:

page - the page number

Throws:

java.io.IOException - if an I/O error occurs

close

public void close()
           throws java.io.IOException

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:

java.io.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 data

copy - true if a local copy of the data is required

getBytes

public byte[] getBytes(long pos,
                       int len)
                throws java.sql.SQLException

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:

java.sql.SQLException

getBinaryStream

public java.io.InputStream getBinaryStream(boolean ascii)
                                    throws java.sql.SQLException

Retrieve the BLOB data as an InputStream.

Parameters:

ascii - true if an ASCII input stream should be returned

Returns:

the InputStream built over the BLOB data

Throws:

java.sql.SQLException - if an error occurs

getUnicodeStream

public java.io.InputStream getUnicodeStream()
                                     throws java.sql.SQLException

Retrieve the BLOB data as an Big Endian Unicode InputStream.

Returns:

the InputStream built over the BLOB data

Throws:

java.sql.SQLException - if an error occurs

setBinaryStream

public java.io.OutputStream setBinaryStream(long pos,
                                            boolean ascii)
                                     throws java.sql.SQLException

Creates an OutputStream 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:

java.sql.SQLException - if an error occurs

setBytes

public int setBytes(long pos,
                    byte[] bytes,
                    int offset,
                    int len,
                    boolean copy)
             throws java.sql.SQLException

Sets the content of the BLOB to the supplied byte array value.

If the following conditions are met:

1. The start position is 1
2. The existing BLOB length is smaller or the same as the length of the new data
3. The new data length does not exceed the in memory limit

then the new data is buffered entirely in memory, otherwise a disk file is created.

Parameters:

pos - the start position in the buffer (from 1)

bytes - the byte array containing the data to copy

offset - the start position in the byte array (from 0)

len - the number of bytes to copy

copy - true if a local copy of the byte array is required

Returns:

the number of bytes copied

Throws:

java.sql.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

public void truncate(long len)
              throws java.sql.SQLException

Truncates the BLOB buffer to the specified size.

Parameters:

len - the required length

Throws:

java.sql.SQLException - if an error occurs

position

public int position(byte[] pattern,
                    long start)
             throws java.sql.SQLException

Provides support for pattern searching methods.

Parameters:

pattern - the byte array containg the search pattern

start - 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:

java.sql.SQLException - if an error occurs