Package com.mckoi.database

Class BlobStore

  • All Implemented Interfaces:
    BlobStoreInterface
    final class BlobStore
extends java.lang.Object
implements BlobStoreInterface
    A structure inside an Area that maintains the storage of any number of large binary objects. A blob store allows for the easy allocation of areas for storing blob data and for reading and writing blob information via BlobRef objects.

    A BlobStore can be broken down to the following simplistic functions;

    1) Allocation of an area to store a new blob.
    2) Reading the information in a Blob given a Blob reference identifier.
    3) Reference counting to a particular Blob.
    4) Cleaning up a Blob when no static references are left.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      private class  BlobStore.AbstractRef
      An abstract implementation of a Ref object for referencing large objects in this blob store.
      private class  BlobStore.BLOBInputStream
      An InputStream implementation that reads from the underlying blob data as fixed size pages.
      private class  BlobStore.BlobRefImpl
      An implementation of BlobRef used to represent a blob reference inside this blob store.
      private class  BlobStore.ClobRefImpl
      An implementation of ClobRef used to represent a reference to a large character object inside this blob store.
      private static class  BlobStore.CopyBlobInfo
      Simple structure used when copying blob information.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private long first_delete_chain_record
      The first delete chain element.
      private FixedRecordList fixed_list
      The FixedRecordList structure that maintains a list of fixed size records for blob reference counting.
      private static int MAGIC
      The magic value for fixed record list structures.
      private Store store
      The outer Store object that is to contain the blob store.

    • Constructor Summary

      Constructors 
      Constructor Description
      BlobStore​(Store store)
      Constructs the BlobStore on the given Area object.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      private long addToRecordList​(long record_p)
      Finds a free place to add a record and returns an index to the record here.
      (package private) Ref allocateLargeObject​(byte type, long size)
      Allocates an area in the store for a large binary object to be stored.
      (package private) void completeBlob​(BlobStore.AbstractRef ref)
      Call this to complete a blob in the store after a blob has been completely written.
      (package private) void copyFrom​(StoreSystem store_system, BlobStore src_blob_store)
      Copies all the blob data from the given BlobStore into this blob store.
      (package private) long create()
      Creates the blob store and returns a pointer in the store to the header information.
      void establishReference​(long blob_reference_id)
      Tells the BlobStore that a static reference has been established in a table to the blob referenced by the given id.
      Ref getLargeObject​(long reference_id)
      Returns a Ref object that allows read-only access to a large object in this blob store.
      (package private) void init​(long blob_store_p)
      Initializes the blob store given a pointer to the blob store pointer header (the value previously returned by the 'create' method).
      (package private) BlobRef putByteLongObjectInBlobStore​(ByteLongObject blob)
      Convenience method that converts the given ByteLongObject into a BlobRef object and pushes it into the given BlobStore object.
      (package private) ClobRef putStringInBlobStore​(java.lang.String str)
      Convenience method that converts the given String into a ClobRef object and pushes it into the given BlobStore object.
      private void readBlobByteArray​(long reference_id, long offset, byte[] buf, int off, int length)
      Reads a section of the blob referenced by the given id, offset and length into the byte array.
      void releaseReference​(long blob_reference_id)
      Tells the BlobStore that a static reference has been released to the given blob.
      private void writeBlobByteArray​(long reference_id, long offset, byte[] buf, int length)
      Writes a section of the blob referenced by the given id, offset and length to the byte array.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • MAGIC

        private static final int MAGIC
        The magic value for fixed record list structures.
        See Also:
        Constant Field Values

      • store

        private Store store
        The outer Store object that is to contain the blob store.

      • fixed_list

        private FixedRecordList fixed_list
        The FixedRecordList structure that maintains a list of fixed size records for blob reference counting.

      • first_delete_chain_record

        private long first_delete_chain_record
        The first delete chain element.

    • Constructor Detail

      • BlobStore

        BlobStore​(Store store)
        Constructs the BlobStore on the given Area object.

    • Method Detail

      • create

        long create()
     throws java.io.IOException
        Creates the blob store and returns a pointer in the store to the header information. This value is later used to initialize the store.
        Throws:
        java.io.IOException

      • init

        void init​(long blob_store_p)
   throws java.io.IOException
        Initializes the blob store given a pointer to the blob store pointer header (the value previously returned by the 'create' method).
        Throws:
        java.io.IOException

      • copyFrom

        void copyFrom​(StoreSystem store_system,
              BlobStore src_blob_store)
       throws java.io.IOException
        Copies all the blob data from the given BlobStore into this blob store. Any blob information that already exists within this BlobStore is deleted. We assume this method is called after the blob store is created or initialized.
        Throws:
        java.io.IOException

      • putStringInBlobStore

        ClobRef putStringInBlobStore​(java.lang.String str)
                      throws java.io.IOException
        Convenience method that converts the given String into a ClobRef object and pushes it into the given BlobStore object.
        Throws:
        java.io.IOException

      • putByteLongObjectInBlobStore

        BlobRef putByteLongObjectInBlobStore​(ByteLongObject blob)
                              throws java.io.IOException
        Convenience method that converts the given ByteLongObject into a BlobRef object and pushes it into the given BlobStore object.
        Throws:
        java.io.IOException

      • addToRecordList

        private long addToRecordList​(long record_p)
                      throws java.io.IOException
        Finds a free place to add a record and returns an index to the record here. This may expand the record space as necessary if there are no free record slots to use.

        NOTE: Unfortunately this is cut-and-paste from the way V2MasterTableDataSource manages recycled elements.

        Throws:
        java.io.IOException

      • allocateLargeObject

        Ref allocateLargeObject​(byte type,
                        long size)
                 throws java.io.IOException
        Allocates an area in the store for a large binary object to be stored. After the blob area is allocated the blob may be written. This returns a BlobRef object for future access to the blob.

        A newly allocated blob is read and write enabled. A call to the 'completeBlob' method must be called to finalize the blob at which point the blob becomes a static read-only object.

        Throws:
        java.io.IOException

      • getLargeObject

        public Ref getLargeObject​(long reference_id)
                   throws java.io.IOException
        Returns a Ref object that allows read-only access to a large object in this blob store.
        Specified by:
        getLargeObject in interface BlobStoreInterface
        Throws:
        java.io.IOException

      • completeBlob

        void completeBlob​(BlobStore.AbstractRef ref)
           throws java.io.IOException
        Call this to complete a blob in the store after a blob has been completely written. Only BlobRef implementations returned by the 'allocateBlob' method are accepted.
        Throws:
        java.io.IOException

      • establishReference

        public void establishReference​(long blob_reference_id)
        Tells the BlobStore that a static reference has been established in a table to the blob referenced by the given id. This is used to count references to a blob, and possibly clean up a blob if there are no references remaining to it.

        NOTE: It is the responsibility of the callee to establish a 'lockForWrite' lock on the store before this is used.

        Specified by:
        establishReference in interface BlobStoreInterface

      • releaseReference

        public void releaseReference​(long blob_reference_id)
        Tells the BlobStore that a static reference has been released to the given blob. This would typically be called when the row in the database is removed.

        NOTE: It is the responsibility of the callee to establish a 'lockForWrite' lock on the store before this is used.

        Specified by:
        releaseReference in interface BlobStoreInterface

      • readBlobByteArray

        private void readBlobByteArray​(long reference_id,
                               long offset,
                               byte[] buf,
                               int off,
                               int length)
                        throws java.io.IOException
        Reads a section of the blob referenced by the given id, offset and length into the byte array.
        Throws:
        java.io.IOException

      • writeBlobByteArray

        private void writeBlobByteArray​(long reference_id,
                                long offset,
                                byte[] buf,
                                int length)
                         throws java.io.IOException
        Writes a section of the blob referenced by the given id, offset and length to the byte array. Note that this does not perform any checks on whether we are allowed to write to this blob.
        Throws:
        java.io.IOException