Class TemporaryClob

java.lang.Object
org.apache.derby.impl.jdbc.TemporaryClob
All Implemented Interfaces:
InternalClob
final class TemporaryClob extends 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.

  • Field Details

    • 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 FilterReader unclosableInternalReader
      The internal reader wrapped so that it cannot be closed.

    • posCache

      private final TemporaryClob.CharToBytePositionCache posCache
      Simple one-entry cache for character-byte position.

  • Constructor Details

    • 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:
      NullPointerException - if conChild is null

    • TemporaryClob

      TemporaryClob(String data, ConnectionChild conChild) throws 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:
      IOException
      StandardException

  • Method Details

    • cloneClobContent

      static InternalClob cloneClobContent(String dbName, ConnectionChild conChild, InternalClob clob) throws IOException, 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:
      IOException - if accessing the I/O resources fail (read or write)
      SQLException - if accessing underlying resources fail

    • cloneClobContent

      static InternalClob cloneClobContent(String dbName, ConnectionChild conChild, InternalClob clob, long length) throws IOException, 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:
      IOException - if accessing the I/O resources fail (read or write)
      SQLException - if accessing underlying resources fail

    • release

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

    • getRawByteStream

      public InputStream getRawByteStream() throws 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:
      IOException - if obtaining the stream fails

    • getBytePosition

      private long getBytePosition(long charPos) throws 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:
      EOFException - if the character position specified is greater than the Clob length +1
      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 Writer getWriter(long pos) throws IOException, 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:
      IOException
      SQLException - if the specified position is invalid

    • getReader

      public Reader getReader(long pos) throws IOException, 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:
      IOException
      SQLException - if the specified position is too big

    • getInternalReader

      public Reader getInternalReader(long characterPosition) throws IOException, 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:
      IOException
      SQLException
      See Also:

    • getCharLength

      public long getCharLength() throws 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:
      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 IOException
      Returns the size of the Clob in bytes.
      Returns:
      Number of bytes in the CLOB value.
      Throws:
      IOException - if accessing the underlying I/O resources fail

    • insertString

      public long insertString(String str, long insertionPoint) throws IOException, 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:
      EOFException - if the position is larger than the Clob length +1
      IOException - if accessing the underlying I/O resources fail
      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 IOException, 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:
      IOException - if accessing the underlying I/O resources fails
      SQLException - if accessing underlying resources fail

    • getByteFromString

      private byte[] getByteFromString(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 IOException, SQLException
      Copies the content of another Clob into this one.
      Parameters:
      clob - the Clob to copy from
      Throws:
      IOException - if accessing I/O resources fail (both read and write)
      SQLException - if accessing underlying resources fail

    • copyClobContent

      private void copyClobContent(InternalClob clob, long charLength) throws IOException, SQLException
      Copies the content of another Clob into this one.
      Parameters:
      clob - the Clob to copy from
      charLength - number of chars to copy
      Throws:
      EOFException - if the length of the stream is shorter than the specified length
      IOException - if accessing I/O resources fail (both read and write)
      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:
      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 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:
      IOException - if obtaining the length of the stream fails