Package org.apache.derby.impl.jdbc

Class TemporaryClob

  • All Implemented Interfaces:
    InternalClob
    final class TemporaryClob
extends java.lang.Object
implements InternalClob
    A Clob representation where the Clob is stored either in memory or on disk.

    Character positions given as input to methods in this class are always 1-based. Byte positions are always 0-based.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      private static class  TemporaryClob.CharToBytePositionCache
      A simple class to hold the byte position for a character position.

    • Constructor Summary

      Constructors 
      Constructor Description
      TemporaryClob​(java.lang.String data, ConnectionChild conChild)
      Constructs a TemporaryClob object and initializes with a initial String.
      TemporaryClob​(ConnectionChild conChild)
      Constructs a TemporaryClob object used to perform operations on a CLOB value.

    • 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.
      (package private) static InternalClob cloneClobContent​(java.lang.String dbName, ConnectionChild conChild, InternalClob clob)
      Clones the content of another internal Clob.
      (package private) static InternalClob cloneClobContent​(java.lang.String dbName, ConnectionChild conChild, InternalClob clob, long length)
      Clones the content of another internal Clob.
      private void copyClobContent​(InternalClob clob)
      Copies the content of another Clob into this one.
      private void copyClobContent​(InternalClob clob, long charLength)
      Copies the content of another Clob into this one.
      private byte[] getByteFromString​(java.lang.String str)
      Converts a string into the modified UTF-8 byte encoding.
      long getByteLength()
      Returns the size of the Clob in bytes.
      private long getBytePosition​(long charPos)
      Finds the corresponding byte position for the given UTF-8 character position, starting from the byte position startPos.
      long getCharLength()
      Returns number of characters in the Clob.
      long getCharLengthIfKnown()
      Returns the cached character count for the Clob, if any.
      private CharacterStreamDescriptor getCSD()
      Returns a character stream descriptor for the stream.
      java.io.Reader getInternalReader​(long characterPosition)
      Returns an internal reader for the Clob content, 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)
      Constructs and returns a Reader.
      long getUpdateCount()
      Returns the update count of this Clob.
      java.io.Writer getWriter​(long pos)
      Constructs and returns a Writer for the CLOB value.
      long insertString​(java.lang.String str, long insertionPoint)
      Inserts a string at the given position.
      boolean isReleased()
      Tells if this Clob has been released.
      boolean isWritable()
      Tells if this Clob is intended to be writable.
      void release()
      Releases this Clob by freeing assoicated resources.
      void truncate​(long newCharLength)
      Truncate the Clob to the specifiec size.
      private void updateInternalState​(long charChangePosition)
      Updates the internal state after a modification has been performed on the Clob content.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • conChild

        private ConnectionChild conChild
        Connection child assoicated with this Clob.

        Currently only used for synchronization in *some* streams associated with the Clob. This suggests something is off wrt. synchronization.

      • bytes

        private final LOBStreamControl bytes
        Underlying structure holding this Clobs raw bytes.

      • released

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

      • cachedCharLength

        private long cachedCharLength
        Cached character length of the Clob.

        A value of 0 is interpreted as unknown length, even though it is a valid value. If the length is requested and the value is zero, an attempt to obtain the length is made by draining the source.

      • 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

      • TemporaryClob

        TemporaryClob​(ConnectionChild conChild)
        Constructs a TemporaryClob object used to perform operations on a CLOB value.
        Parameters:
        conChild - connection object used to obtain synchronization object
        Throws:
        java.lang.NullPointerException - if conChild is null

      • TemporaryClob

        TemporaryClob​(java.lang.String data,
              ConnectionChild conChild)
       throws java.io.IOException,
              StandardException
        Constructs a TemporaryClob object and initializes with a initial String.
        Parameters:
        data - initial value in String
        conChild - connection object used to obtain synchronization object
        Throws:
        java.io.IOException
        StandardException

    • Method Detail

      • cloneClobContent

        static InternalClob cloneClobContent​(java.lang.String dbName,
                                     ConnectionChild conChild,
                                     InternalClob clob)
                              throws java.io.IOException,
                                     java.sql.SQLException
        Clones the content of another internal Clob.
        Parameters:
        dbName - name of the assoicated database
        conChild - assoiated connection child
        clob - the Clob whose content to clone
        Returns:
        A read-write Clob.
        Throws:
        java.io.IOException - if accessing the I/O resources fail (read or write)
        java.sql.SQLException - if accessing underlying resources fail

      • cloneClobContent

        static InternalClob cloneClobContent​(java.lang.String dbName,
                                     ConnectionChild conChild,
                                     InternalClob clob,
                                     long length)
                              throws java.io.IOException,
                                     java.sql.SQLException
        Clones the content of another internal Clob.
        Parameters:
        dbName - name of the assoicated database
        conChild - assoiated connection child
        clob - the Clob whose content to clone
        length - number of chars in new InternalClob
        Returns:
        A read-write Clob.
        Throws:
        java.io.IOException - if accessing the I/O resources fail (read or write)
        java.sql.SQLException - if accessing underlying resources fail

      • release

        public void release()
             throws java.io.IOException
        Releases this Clob by freeing assoicated resources.
        Specified by:
        release in interface InternalClob
        Throws:
        java.io.IOException - if accessing underlying I/O resources fail

      • getRawByteStream

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

        The stream is managed by the underlying byte store, and can serve bytes both from memory and from a file on disk.

        Specified by:
        getRawByteStream in interface InternalClob
        Returns:
        A stream serving the raw bytes of the stream, initialized at byte position 0.
        Throws:
        java.io.IOException - if obtaining the stream fails

      • getBytePosition

        private long getBytePosition​(long charPos)
                      throws java.io.IOException
        Finds the corresponding byte position for the given UTF-8 character position, starting from the byte position startPos. See comments in SQLChar.readExternal for more notes on processing the UTF8 format.
        Parameters:
        charPos - character position
        Returns:
        Stream position in bytes for the given character position.
        Throws:
        java.io.EOFException - if the character position specified is greater than the Clob length +1
        java.io.IOException - if accessing underlying I/O resources fail

      • getUpdateCount

        public long getUpdateCount()
        Returns the update count of this Clob.
        Specified by:
        getUpdateCount in interface InternalClob
        Returns:
        Update count.

      • getWriter

        public java.io.Writer getWriter​(long pos)
                         throws java.io.IOException,
                                java.sql.SQLException
        Constructs and returns a Writer for the CLOB value.
        Specified by:
        getWriter in interface InternalClob
        Parameters:
        pos - the initial position in bytes for the Writer
        Returns:
        A Writer to write to the CLOB value.
        Throws:
        java.io.IOException
        java.sql.SQLException - if the specified position is invalid

      • getReader

        public java.io.Reader getReader​(long pos)
                         throws java.io.IOException,
                                java.sql.SQLException
        Constructs and returns a Reader.
        Specified by:
        getReader in interface InternalClob
        Parameters:
        pos - initial position of the returned Reader in number of characters. Expected to be non-negative. The first character is at position 0.
        Returns:
        A Reader with the underlying CLOB value as source.
        Throws:
        java.io.IOException
        java.sql.SQLException - if the specified position is too big

      • getInternalReader

        public java.io.Reader getInternalReader​(long characterPosition)
                                 throws java.io.IOException,
                                        java.sql.SQLException
        Description copied from interface: InternalClob
        Returns an internal reader for the Clob content, initialized at the specified character position.

        This method can return a shared reader object, avoiding instantiation and repositioning costs for internal operations where the stream itself is not published to the end-user. One such example is Clob.getSubString.

        Specified by:
        getInternalReader in interface InternalClob
        Parameters:
        characterPosition - character position. The first character is at position 1.
        Returns:
        A Reader serving the content of the Clob.
        Throws:
        java.io.IOException - if accessing underlying I/O resources fail
        java.sql.SQLException - if accessing underlying resources fail
        See Also:
        getReader(long)

      • getCharLength

        public long getCharLength()
                   throws java.io.IOException
        Returns number of characters in the Clob.
        Specified by:
        getCharLength in interface InternalClob
        Returns:
        The length of the Clob in number of characters.
        Throws:
        java.io.IOException - if accessing the underlying I/O resources fail

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

      • getByteLength

        public long getByteLength()
                   throws java.io.IOException
        Returns the size of the Clob in bytes.
        Returns:
        Number of bytes in the CLOB value.
        Throws:
        java.io.IOException - if accessing the underlying I/O resources fail

      • insertString

        public long insertString​(java.lang.String str,
                         long insertionPoint)
                  throws java.io.IOException,
                         java.sql.SQLException
        Inserts a string at the given position.
        Specified by:
        insertString in interface InternalClob
        Parameters:
        str - the string to insert
        insertionPoint - the character position to insert the string at
        Returns:
        Number of characters inserted.
        Throws:
        java.io.EOFException - if the position is larger than the Clob length +1
        java.io.IOException - if accessing the underlying I/O resources fail
        java.sql.SQLException - if accessing the underlying resources fail

      • 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 is intended to be writable.
        Specified by:
        isWritable in interface InternalClob
        Returns:
        true

      • truncate

        public void truncate​(long newCharLength)
              throws java.io.IOException,
                     java.sql.SQLException
        Truncate the Clob to the specifiec size.
        Specified by:
        truncate in interface InternalClob
        Parameters:
        newCharLength - the new length, in characters, of the Clob
        Throws:
        java.io.IOException - if accessing the underlying I/O resources fails
        java.sql.SQLException - if accessing underlying resources fail

      • getByteFromString

        private byte[] getByteFromString​(java.lang.String str)
        Converts a string into the modified UTF-8 byte encoding.
        Parameters:
        str - string to represent with modified UTF-8 encoding
        Returns:
        Byte array representing the string in modified UTF-8 encoding.

      • copyClobContent

        private void copyClobContent​(InternalClob clob)
                      throws java.io.IOException,
                             java.sql.SQLException
        Copies the content of another Clob into this one.
        Parameters:
        clob - the Clob to copy from
        Throws:
        java.io.IOException - if accessing I/O resources fail (both read and write)
        java.sql.SQLException - if accessing underlying resources fail

      • copyClobContent

        private void copyClobContent​(InternalClob clob,
                             long charLength)
                      throws java.io.IOException,
                             java.sql.SQLException
        Copies the content of another Clob into this one.
        Parameters:
        clob - the Clob to copy from
        charLength - number of chars to copy
        Throws:
        java.io.EOFException - if the length of the stream is shorter than the specified length
        java.io.IOException - if accessing I/O resources fail (both read and write)
        java.sql.SQLException - if accessing underlying resources fail

      • checkIfValid

        private final 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

      • updateInternalState

        private final void updateInternalState​(long charChangePosition)
        Updates the internal state after a modification has been performed on the Clob content.

        Currently the state update consists of dicarding the internal reader to stop it from delivering stale data, to reset the byte/char position cache if necessary, and to reset the cached length.

        Parameters:
        charChangePosition - the position where the Clob change started

      • getCSD

        private final CharacterStreamDescriptor getCSD()
                                        throws java.io.IOException
        Returns a character stream descriptor for the stream.

        All streams from the underlying source (LOBStreamControl) are position aware and can be moved to a specific byte position cheaply. The maximum length is not really needed, nor known, at the moment, so the maximum allowed Clob length in Derby is used.

        Returns:
        A character stream descriptor.
        Throws:
        java.io.IOException - if obtaining the length of the stream fails