Class StoreStreamClob

  • All Implemented Interfaces:
    InternalClob

    final class StoreStreamClob
    extends java.lang.Object
    implements InternalClob
    A read-only Clob representation operating on streams out of the Derby store module.

    Note that the streams from the store are expected to have the following properties:

    1. The first few bytes are used for length encoding. Currently the number of bytes is either 2 or 5.
    2. A Derby-specific end-of-stream marker at the end of the stream can be present. The marker is expected to be 0xe0 0x00 0x00
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      private void checkIfValid()
      Makes sure the Clob has not been released.
      long getCharLength()
      Returns the number of characters in the Clob.
      long getCharLengthIfKnown()
      Returns the cached character count for the Clob, if any.
      java.io.Reader getInternalReader​(long characterPosition)
      Returns an internal reader for the Clob, initialized at the specified character position.
      java.io.InputStream getRawByteStream()
      Returns a stream serving the raw bytes of this Clob.
      java.io.Reader getReader​(long pos)
      Returns a reader for the Clob, initialized at the specified character position.
      long getUpdateCount()
      Returns the update count of this Clob.
      java.io.Writer getWriter​(long pos)
      Not supported.
      long insertString​(java.lang.String str, long pos)
      Not supported.
      boolean isReleased()
      Tells if this Clob has been released.
      boolean isWritable()
      Tells if this Clob can be modified.
      private static java.sql.SQLException noStateChangeLOB​(java.lang.Throwable t)
      Wrap real exception in a SQLException to avoid changing the state of the connection child by cleaning it up.
      void release()
      Releases resources associated with this Clob.
      void truncate​(long newLength)
      Not supported.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • released

        private volatile boolean released
        Tells whether this Clob has been released or not.
      • positionedStoreStream

        private final PositionedStoreStream positionedStoreStream
        The stream from store, used to read bytes from the database.

        To be able to support the requirements, the stream must implement Resetable.

      • conChild

        private final ConnectionChild conChild
        The connection (child) this Clob belongs to.
      • synchronizationObject

        private final java.lang.Object synchronizationObject
        Object used for synchronizing access to the store stream.
      • internalReader

        private UTF8Reader internalReader
        Shared internal reader, closed when the Clob is released. This is a performance optimization, and the stream is shared between "one time" operations, for instance getSubString calls. Often a subset, or the whole, of the Clob is read subsequently and then this optimization avoids repositioning costs (the store does not support random access for LOBs). NOTE: Do not publish this reader to the end-user.
      • unclosableInternalReader

        private java.io.FilterReader unclosableInternalReader
        The internal reader wrapped so that it cannot be closed.
    • Constructor Detail

      • StoreStreamClob

        public StoreStreamClob​(CharacterStreamDescriptor csd,
                               ConnectionChild conChild)
                        throws StandardException
        Creates a new Clob based on a stream from store.

        The stream used as a source for this Clob has to implement the interface Resetable, as the stream interface from store only allows for movement forwards. If the stream has been advanced too far with regards to the user request, the stream must be reset and we start from the beginning.

        Parameters:
        csd - descriptor for the source stream, including a reference to it
        conChild - the connection (child) this Clob belongs to
        Throws:
        StandardException
    • Method Detail

      • release

        public void release()
        Releases resources associated with this Clob.
        Specified by:
        release in interface InternalClob
      • getCharLength

        public long getCharLength()
                           throws java.sql.SQLException
        Returns the number of characters in the Clob.
        Specified by:
        getCharLength in interface InternalClob
        Returns:
        Number of characters in the Clob.
        Throws:
        java.sql.SQLException - if any kind of error is encountered, be it related to I/O or something else
      • getCharLengthIfKnown

        public long getCharLengthIfKnown()
        Returns the cached character count for the Clob, if any.
        Specified by:
        getCharLengthIfKnown in interface InternalClob
        Returns:
        The number of characters in the Clob, or -1 if unknown.
      • getRawByteStream

        public java.io.InputStream getRawByteStream()
                                             throws java.io.IOException,
                                                    java.sql.SQLException
        Returns a stream serving the raw bytes of this Clob.

        Note that the stream returned is an internal stream, and it should not be pulished to end users.

        Specified by:
        getRawByteStream in interface InternalClob
        Returns:
        A stream serving the bytes of this Clob, initialized at byte 0 of the data. The buffer must be assumed to be unbuffered, but no such guarantee is made.
        Throws:
        java.io.IOException - if accessing the I/O resources fail
        java.sql.SQLException - if accessing the store resources fail
      • getReader

        public java.io.Reader getReader​(long pos)
                                 throws java.io.IOException,
                                        java.sql.SQLException
        Returns a reader for the Clob, initialized at the specified character position.
        Specified by:
        getReader in interface InternalClob
        Parameters:
        pos - character position. The first character is at position 1.
        Returns:
        A reader initialized at the specified position.
        Throws:
        java.io.EOFException - if the positions is larger than the Clob
        java.io.IOException - if accessing the I/O resources fail
        java.sql.SQLException - if accessing the store resources fail
      • getInternalReader

        public java.io.Reader getInternalReader​(long characterPosition)
                                         throws java.io.IOException,
                                                java.sql.SQLException
        Returns an internal reader for the Clob, initialized at the specified character position.
        Specified by:
        getInternalReader in interface InternalClob
        Parameters:
        characterPosition - 1-based character position.
        Returns:
        A reader initialized at the specified position.
        Throws:
        java.io.EOFException - if the positions is larger than the Clob
        java.io.IOException - if accessing the I/O resources fail
        java.sql.SQLException - if accessing the store resources fail
      • getUpdateCount

        public long getUpdateCount()
        Returns the update count of this Clob.

        Always returns zero, as this Clob cannot be updated.

        Specified by:
        getUpdateCount in interface InternalClob
        Returns:
        Zero (read-only Clob).
      • getWriter

        public java.io.Writer getWriter​(long pos)
        Not supported.
        Specified by:
        getWriter in interface InternalClob
        Parameters:
        pos - the starting character position. The first character is at position 1.
        Returns:
        A writer initialized at the specified character position.
        See Also:
        InternalClob.getWriter(long)
      • insertString

        public long insertString​(java.lang.String str,
                                 long pos)
        Not supported.
        Specified by:
        insertString in interface InternalClob
        Parameters:
        str - the string to insert
        pos - the character position the string will be inserted at. Must be between 1 and clob.length() +1, inclusive.
        Returns:
        The number of characters inserted.
        See Also:
        InternalClob.insertString(java.lang.String, long)
      • isReleased

        public boolean isReleased()
        Tells if this Clob has been released.
        Specified by:
        isReleased in interface InternalClob
        Returns:
        true if released, false if not.
      • isWritable

        public boolean isWritable()
        Tells if this Clob can be modified.
        Specified by:
        isWritable in interface InternalClob
        Returns:
        false, this Clob is read-only.
      • noStateChangeLOB

        private static java.sql.SQLException noStateChangeLOB​(java.lang.Throwable t)
        Wrap real exception in a SQLException to avoid changing the state of the connection child by cleaning it up.
        Parameters:
        t - real cause of error that we want to "ignore" with respect to transaction context cleanup
        Returns:
        A SQLException wrapped around the real cause of the error
      • checkIfValid

        private void checkIfValid()
        Makes sure the Clob has not been released.

        All operations are invalid on a released Clob.

        Throws:
        java.lang.IllegalStateException - if the Clob has been released