Class Lob

java.lang.Object
org.apache.derby.client.am.Lob
All Implemented Interfaces:
UnitOfWorkListener
Direct Known Subclasses:
ClientBlob, ClientClob

public abstract class Lob extends Object implements UnitOfWorkListener
  • Field Details

    • STRING

      static final int STRING
      See Also:
    • ASCII_STREAM

      static final int ASCII_STREAM
      See Also:
    • UNICODE_STREAM

      static final int UNICODE_STREAM
      See Also:
    • CHARACTER_STREAM

      static final int CHARACTER_STREAM
      See Also:
    • BINARY_STREAM

      static final int BINARY_STREAM
      See Also:
    • BINARY_STRING

      static final int BINARY_STRING
      See Also:
    • LOCATOR

      static final int LOCATOR
      See Also:
    • INVALID_LOCATOR

      public static final int INVALID_LOCATOR
      See Also:
    • agent_

      protected Agent agent_
    • dataType_

      protected int dataType_
    • locator_

      protected int locator_
    • sqlLength_

      private long sqlLength_
    • lengthObtained_

      private boolean lengthObtained_
    • isValid_

      protected boolean isValid_
      This boolean variable indicates whether the Lob object has been invalidated by calling free() on it
    • willBeLayerBStreamed_

      private final boolean willBeLayerBStreamed_
    • updateCount

      private long updateCount
    • transactionID_

      private int transactionID_
      This integer identifies which transaction the Lob is associated with
    • LOB_OBJECT_LENGTH_UNKNOWN_YET

      private static final ClientMessageId LOB_OBJECT_LENGTH_UNKNOWN_YET
  • Constructor Details

    • Lob

      protected Lob(Agent agent, boolean willBeLayerBStreamed)
  • Method Details

    • sqlLength

      long sqlLength() throws SqlException
      Return the length of the Lob value represented by this Lob object. If length is not already known, and Lob is locator based, length will be retrieved from the server. If not, locator based, Lob will first be materialized. NOTE: The caller needs to deal with synchronization.
      Returns:
      length of Lob value
      Throws:
      SqlException - on execution errors while materializing the stream, or if Layer B streaming is used and length not yet obtained.
    • setSqlLength

      void setSqlLength(long length)
      Update the registered length of the Lob value. To be called by methods that make changes to the length of the Lob. NOTE: The caller needs to deal with synchronization.
      Parameters:
      length - the new length of the Lob value
    • getLocatorLength

      long getLocatorLength() throws SqlException
      Get the length of locator based Lob from the server. This is a dummy implementation that is supposed to be overridden by subclasses. A stored procedure call will be made to get the length from the server.
      Returns:
      length of Lob
      Throws:
      SqlException
    • listenToUnitOfWork

      public void listenToUnitOfWork()
      Specified by:
      listenToUnitOfWork in interface UnitOfWorkListener
    • completeLocalCommit

      public void completeLocalCommit(Iterator listenerIterator)
      Specified by:
      completeLocalCommit in interface UnitOfWorkListener
    • completeLocalRollback

      public void completeLocalRollback(Iterator listenerIterator)
      Specified by:
      completeLocalRollback in interface UnitOfWorkListener
    • getAgent

      public Agent getAgent()
    • checkForClosedConnection

      void checkForClosedConnection() throws SqlException
      Throws:
      SqlException
    • materializeStream

      protected abstract void materializeStream() throws SqlException
      Method to be implemented by subclasses, so that #materializedStream(InputStream, String) can be called with subclass specific parameters and the result assigned to the right stream.
      Throws:
      SqlException
    • materializeStream

      protected InputStream materializeStream(InputStream is, String typeDesc) throws SqlException
      Materialize the given stream into memory and update the internal length variable.
      Parameters:
      is - stream to use for input
      typeDesc - description of the data type we are inserting, for instance java.sql.Clob
      Returns:
      a stream whose source is the materialized data
      Throws:
      SqlException - if the stream exceeds 2 GB, or an error happens while reading from the stream
    • length

      public abstract long length() throws SQLException
      Throws:
      SQLException
    • isLayerBStreamingPossible

      protected static boolean isLayerBStreamingPossible(Agent agent)
    • willBeLayerBStreamed

      public boolean willBeLayerBStreamed()
    • isLocator

      public boolean isLocator()
      Check whether this Lob is based on a locator
      Returns:
      true if Lob is based on locator, false otherwise
    • getLocator

      public int getLocator()
      Get locator for this Lob
      Returns:
      locator for this Lob, INVALID_LOCATOR if Lob is not based on locator
    • checkPosAndLength

      protected void checkPosAndLength(long pos, long length) throws SQLException
      Checks the pos and length.
      Parameters:
      pos - a long that contains the position that needs to be checked
      length - a long that contains the length that needs to be checked
      Throws:
      SQLException - if a) pos <= 0 b) pos > (length of LOB) c) length < 0 d) (pos -1) + length > (length of LOB)
    • incrementUpdateCount

      protected void incrementUpdateCount()
      Increments and returns the new updateCount of this Lob. The method needs to be synchronized since multiple updates can happen on this Lob simultaneously. It will be called from the 1) Locator Writers 2) Locator OutputStreams 3) From the update methods within the Lobs like setString, truncate. since all of the above acesses are inside the am package, this method will have default access. We do not need to worry about the non-locator streams since non-locator InputStreams would not depend on updateCount for invalidation
    • getUpdateCount

      long getUpdateCount()
      Returns the current updateCount of the Clob.
    • checkForLocatorValidity

      void checkForLocatorValidity() throws SqlException
      Calls SqlLength() to check if the Locator associated with the underlying Lob is valid. If it is not it throws an exception.
      Throws:
      SqlException
    • checkValidity

      protected void checkValidity() throws SQLException
      Checks if isValid is true and whether the transaction that created the Lob is still active. If any of which is not true throws a SQLException stating that a method has been called on an invalid LOB object.
      Throws:
      SQLException - if isValid is not true or the transaction that created the Lob is not active