BlobBuffer (jTDS API)
Keywords: net.sourceforge.jtds.util.BlobBuffer class

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Generated on December 30 2009