Package net.sourceforge.jtds.util

Class BlobBuffer

java.lang.Object
net.sourceforge.jtds.util.BlobBuffer
public class BlobBuffer extends 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

    Nested Classes
    Modifier and Type
    Class
    Description
    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

    Fields
    Modifier and Type
    Field
    Description
    private File
    blobFile
    The name of the temporary BLOB disk file.
    private byte[]
    buffer
    The BLOB buffer or the current page buffer.
    private final File
    bufferDir
    The directory to buffer data to.
    private boolean
    bufferDirty
    Indicates page in memory must be saved.
    private static final 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 final byte[]
    EMPTY_BUFFER
    Default zero length buffer.
    private static final int
    INVALID_PAGE
    Invalid page marker.
    private boolean
    isMemOnly
    True if attempts to create a BLOB file have failed or the buffer is created without specifying a buffer directory.
    private int
    length
    The total length of the valid data in buffer.
    private static final int
    MAX_BUF_INC
    Maximum buffer increment.
    private final int
    maxMemSize
    The maximum size of an in memory buffer.
    private int
    openCount
    Count of callers that have opened the BLOB file.
    private static final int
    PAGE_MASK
    Mask for page component of read/write pointer.
    private static final int
    PAGE_SIZE
    Default page size (must be power of 2).
    private RandomAccessFile
    raFile
    The RA file object reference or null if closed.

  • Constructor Summary

    Constructors
    Constructor
    Description
    BlobBuffer(File bufferDir, long maxMemSize)
    Creates a blob buffer.

  • Method Summary

    Modifier and Type
    Method
    Description
    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.
    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.
    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.
    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 Details

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

    • PAGE_MASK

      private static final int PAGE_MASK
      Mask for page component of read/write pointer.
      See Also:

    • BYTE_MASK

      private static final int BYTE_MASK
      Mask for page offset component of R/W pointer.
      See Also:

    • MAX_BUF_INC

      private static final int MAX_BUF_INC
      Maximum buffer increment.
      See Also:

    • INVALID_PAGE

      private static final int INVALID_PAGE
      Invalid page marker.
      See Also:

    • 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 File blobFile
      The name of the temporary BLOB disk file.

    • raFile

      private 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 or the buffer is created without specifying a buffer directory.

    • bufferDir

      private final File bufferDir
      The directory to buffer data to.

    • maxMemSize

      private final int maxMemSize
      The maximum size of an in memory buffer.

  • Constructor Details

    • BlobBuffer

      public BlobBuffer(File bufferDir, long maxMemSize)
      Creates a blob buffer.
      Parameters:
      bufferDir -
      maxMemSize - the maximum size of the in memory buffer

  • Method Details

    • finalize

      protected void finalize() throws Throwable
      Finalizes this object by deleting any work files.
      Overrides:
      finalize in class Object
      Throws:
      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 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:
      IOException - if an I/O error occurs

    • read

      public int read(int readPtr) throws 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:
      IOException - if an I/O error occurs

    • read

      public int read(int readPtr, byte[] bytes, int offset, int len) throws 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:
      IOException - if an I/O error occurs

    • write

      public void write(int writePtr, int b) throws 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:
      IOException - if an I/O error occurs

    • write

      void write(int writePtr, byte[] bytes, int offset, int len) throws 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:
      IOException - if an I/O error occurs

    • readPage

      public void readPage(int page) throws 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:
      IOException - if an I/O error occurs

    • writePage

      public void writePage(int page) throws IOException
      Writes the specified page to the disk buffer.
      Parameters:
      page - the page number
      Throws:
      IOException - if an I/O error occurs

    • close

      public void close() throws 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:
      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 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:
      SQLException

    • getBinaryStream

      public InputStream getBinaryStream(boolean ascii) throws 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:
      SQLException - if an error occurs

    • getUnicodeStream

      public InputStream getUnicodeStream() throws SQLException
      Retrieve the BLOB data as an Big Endian Unicode InputStream.
      Returns:
      the InputStream built over the BLOB data
      Throws:
      SQLException - if an error occurs

    • setBinaryStream

      public OutputStream setBinaryStream(long pos, boolean ascii) throws 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:
      SQLException - if an error occurs

    • setBytes

      public int setBytes(long pos, byte[] bytes, int offset, int len, boolean copy) throws 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:
      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 SQLException
      Truncates the BLOB buffer to the specified size.
      Parameters:
      len - the required length
      Throws:
      SQLException - if an error occurs

    • position

      public int position(byte[] pattern, long start) throws 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:
      SQLException - if an error occurs