Package oracle.jdbc

Interface OracleBlob

All Superinterfaces:
Blob
All Known Implementing Classes:
BLOB
public interface OracleBlob extends Blob
This interface defines the Oracle extensions to the standard JDBC interface Blob .

Generally any new code should avoid the direct use of the class BLOB. For variable declarations use the interface Blob or this interface as required. Instead of the static methods BLOB.createTemporary(java.sql.Connection, boolean, int) and BLOB.empty_lob() please use Connection.createBlob() and BLOB.getEmptyBLOB() respectively.

Since:
11.2.0.3

  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    close()
    Deprecated, for removal: This API element is subject to removal in a future version.
    The name of this method is anticipated to conflict with a future version of the JDBC Specification.
    void
    closeLob()
    Close a previously opened BLOB.
    default Flow.Publisher<Void>
    freeAsyncOracle()
    Returns a Publisher that publishes the result of freeing the Blob object and the resources that it holds.
    InputStream
    getBinaryStream(long pos)
    Read from the BLOB as a stream at the requested position.
    int
    getBytes(long pos, int length, byte[] buf)
    Oracle extension.
    boolean
    isEmptyLob()
    Return true if the lob locator points to an empty blob.
    default boolean
    isOpen()
    Deprecated, for removal: This API element is subject to removal in a future version.
    The name of this method is anticipated to conflict with a future version of the JDBC Specification.
    boolean
    isOpenLob()
    Check whether the BLOB is opened.
    boolean
    isSecureFile()
    Returns true if this is a SecureFile (LOBs with the STORE AS SECUREFILE option, which were introduced in Oracle Database 11g Release 1).
    boolean
    isTemporary()
    Return true if the lob locator points to a temporary blob.
    default void
    open(LargeObjectAccessMode mode)
    Deprecated, for removal: This API element is subject to removal in a future version.
    The name of this method is anticipated to conflict with a future version of the JDBC Specification.
    void
    openLob(LargeObjectAccessMode mode)
    Open a BLOB in the indicated mode.
    Flow.Publisher<byte[]>
    publisherOracle(long position)
    Returns a Publisher that publishes the content of this Blob beginning at the specified position.
    default Flow.Publisher<byte[]>
    publisherOracle(long position, ErrorSet continueOnErrorSet)
    Returns a Publisher that publishes the content of this Blob beginning at the specified position.
    Flow.Subscriber<byte[]>
    subscriberOracle(long position)
    Returns a Subscriber that will append the published bytes to this Blob beginning at the specified position.
    Flow.Subscriber<byte[]>
    subscriberOracle(long position, Flow.Subscriber<Long> outcomeSubscriber)
    Returns a Subscriber that will append the published bytes to this Blob beginning at the specified position.
    default Flow.Subscriber<byte[]>
    subscriberOracle(long position, Flow.Subscriber<Long> outcomeSubscriber, ErrorSet continueOnErrorSet)
    Returns a Subscriber that will append the published bytes to this Blob beginning at the specified position.
    default Flow.Subscriber<byte[]>
    subscriberOracle(long position, ErrorSet continueOnErrorSet)
    Returns a Subscriber that will append the published bytes to this Blob beginning at the specified position.
    SQLXML
    toSQLXML()
    Returns an object which implements java.sql.SQLXML with content take from this Clob.
    SQLXML
    toSQLXML(int csid)
    Returns an object which implements java.sql.SQLXML with content taken from this Blob.

    Methods inherited from interface java.sql.Blob

    free, getBinaryStream, getBinaryStream, getBytes, length, position, position, setBinaryStream, setBytes, setBytes, truncate

  • Method Details

    • open

      @Deprecated(since="23.5", forRemoval=true) default void open(LargeObjectAccessMode mode) throws SQLException
      Deprecated, for removal: This API element is subject to removal in a future version.
      The name of this method is anticipated to conflict with a future version of the JDBC Specification. This method will be removed in a future version of the Oracle JDBC Driver. Any calls to this method should be replaced with a call to openLob(LargeObjectAccessMode), which provides the exact same behavior.
      Open a BLOB in the indicated mode. Valid modes include MODE_READONLY, and MODE_READWRITE. It is an error to open the same LOB twice.
      Throws:
      SQLException
      Since:
      8.2.0

    • openLob

      void openLob(LargeObjectAccessMode mode) throws SQLException
      Open a BLOB in the indicated mode. Valid modes include MODE_READONLY, and MODE_READWRITE. It is an error to open the same LOB twice.
      Throws:
      SQLException
      Since:
      23.5

    • close

      @Deprecated(since="23.5", forRemoval=true) default void close() throws SQLException
      Deprecated, for removal: This API element is subject to removal in a future version.
      The name of this method is anticipated to conflict with a future version of the JDBC Specification. This method will be removed in a future version of the Oracle JDBC Driver. Any calls to this method should be replaced with a call to closeLob(), which provides the exact same behavior.
      Close a previously opened BLOB.
      Throws:
      SQLException
      Since:
      8.2.0

    • closeLob

      void closeLob() throws SQLException
      Close a previously opened BLOB.
      Throws:
      SQLException
      Since:
      23.5

    • isOpen

      @Deprecated(since="23.5", forRemoval=true) default boolean isOpen() throws SQLException
      Deprecated, for removal: This API element is subject to removal in a future version.
      The name of this method is anticipated to conflict with a future version of the JDBC Specification. This method will be removed in a future version of the Oracle JDBC Driver. Any calls to this method should be replaced with a call to isOpenLob(), which provides the exact same behavior.
      Check whether the BLOB is opened.
      Returns:
      true if the LOB is opened.
      Throws:
      SQLException
      Since:
      8.2.0

    • isOpenLob

      boolean isOpenLob() throws SQLException
      Check whether the BLOB is opened.
      Returns:
      true if the LOB is opened.
      Throws:
      SQLException
      Since:
      23.5

    • getBytes

      int getBytes(long pos, int length, byte[] buf) throws SQLException
      Oracle extension. Copy the contents of the BLOB at the requested position to the supplied buffer.
      Parameters:
      pos - is the first byte of the blob to be extracted.
      length - is the number of consecutive bytes to be copied.
      buf - is the buffer to have the extracted bytes.
      Returns:
      a byte array containing a portion of the BLOB
      Throws:
      SQLException

    • isEmptyLob

      boolean isEmptyLob() throws SQLException
      Return true if the lob locator points to an empty blob. False if it does not.
      Returns:
      true if the lob locator points to an empty blob. False if it does not.
      Throws:
      SQLException
      Since:
      8.1.7

    • isSecureFile

      boolean isSecureFile() throws SQLException
      Returns true if this is a SecureFile (LOBs with the STORE AS SECUREFILE option, which were introduced in Oracle Database 11g Release 1).
      Returns:
      true if this is a SecureFile and false otherwise.
      Throws:
      SQLException

    • getBinaryStream

      InputStream getBinaryStream(long pos) throws SQLException
      Read from the BLOB as a stream at the requested position.
      Parameters:
      pos - is the position data to be read.
      Returns:
      an input stream to read data from the BLOB
      Throws:
      SQLException
      Since:
      8.2.0

    • isTemporary

      boolean isTemporary() throws SQLException
      Return true if the lob locator points to a temporary blob. False if it does not.
      Returns:
      true if the lob locator points to a temporary blob. False if it does not.
      Throws:
      SQLException
      Since:
      8.2.0

    • toSQLXML

      SQLXML toSQLXML() throws SQLException
      Returns an object which implements java.sql.SQLXML with content take from this Clob.
      Returns:
      the new SQLXML object
      Throws:
      SQLException
      Since:
      12.2

    • toSQLXML

      SQLXML toSQLXML(int csid) throws SQLException
      Returns an object which implements java.sql.SQLXML with content taken from this Blob.
      Returns:
      the new SQLXML object
      Throws:
      SQLException
      Since:
      12.2

    • publisherOracle

      Flow.Publisher<byte[]> publisherOracle(long position) throws SQLException
      Returns a Publisher that publishes the content of this Blob beginning at the specified position. The argument to each call to Subscriber.onNext will contain an implementation defined number of bytes.

      Calling any method of this Blob except isEmptyLob(), isSecureFile(), isTemporary(), or one defined by Object between the time this method is called and the time when the returned publisher terminates will block.

      The returned publisher terminates once all subscribers have received Subscriber.onComplete, received Subscriber.onError, or cancelled their subscription.

      An invocation of this method is equivalent to invoking publisherOracle(long, ErrorSet) with the ErrorSet configured by OracleCommonConnection.continueOnError(ErrorSet).

      Parameters:
      position - the position at which to start reading from the BLOB value that this Blob object represents; The first position is 1
      Returns:
      a Publisher of the content of this Blob
      Throws:
      SQLException - if a database error occurs, or if this method is called on a Blob that has been freed, or if position is less than 1
      Since:
      21

    • publisherOracle

      default Flow.Publisher<byte[]> publisherOracle(long position, ErrorSet continueOnErrorSet) throws SQLException
      Returns a Publisher that publishes the content of this Blob beginning at the specified position. The argument to each call to Subscriber.onNext will contain an implementation defined number of bytes.

      Calling any method of this Blob except isEmptyLob(), isSecureFile(), isTemporary(), or one defined by Object between the time this method is called and the time when the returned publisher terminates will block.

      The returned publisher terminates once all subscribers have received Subscriber.onComplete, received Subscriber.onError, or cancelled their subscription.

      Upon signalling demand to the returned Publisher, LOB read operations will enter into the execution pipeline of this LOB's connection. If an operation fails with an error not in the continueOnErrorSet, the pipeline will abort all subsequent asynchronous operations, up to the next #resume().

      Parameters:
      position - the position at which to start reading from the BLOB value that this Blob object represents; The first position is 1
      continueOnErrorSet - Set of errors which do not cause subsequent operations to be aborted. Not null.
      Returns:
      a Publisher of the content of this Blob
      Throws:
      SQLException - if a database error occurs, or if this method is called on a Blob that has been freed, or if position is less than 1
      NullPointerException - if the continueOnErrorSet is null
      IllegalArgumentException - if the continueOnErrorSet is not supported. At a minimum, all drivers must support ErrorSet.NO_ERRORS and ErrorSet.ALL_ERRORS
      Since:
      23

    • subscriberOracle

      Flow.Subscriber<byte[]> subscriberOracle(long position) throws SQLException
      Returns a Subscriber that will append the published bytes to this Blob beginning at the specified position.

      Calling any method of this Blob except isEmptyLob(), isSecureFile(), isTemporary(), or one defined by Object between the time this method is called and the time when the returned Subscriber terminates will block.

      The returned Subscriber terminates once Subscriber.onComplete is received, Subscriber.onError is received, or its subscription is cancelled.

      An invocation of this method is equivalent to invoking subscriberOracle(long, ErrorSet) with the ErrorSet configured by OracleCommonConnection.continueOnError(ErrorSet).

      Parameters:
      position - the position at which to start reading from the BLOB value that this Blob object represents; The first position is 1
      Returns:
      a Subscriber that appends bytes to this Blob
      Throws:
      SQLException - if a database error occurs, or if this method is called on a Blob that has been freed, or if position is less than 1
      Since:
      21

    • subscriberOracle

      default Flow.Subscriber<byte[]> subscriberOracle(long position, ErrorSet continueOnErrorSet) throws SQLException
      Returns a Subscriber that will append the published bytes to this Blob beginning at the specified position.

      Calling any method of this Blob except isEmptyLob(), isSecureFile(), isTemporary(), or one defined by Object between the time this method is called and the time when the returned Subscriber terminates will block.

      The returned Subscriber terminates once Subscriber.onComplete is received, Subscriber.onError is received, or its subscription is cancelled.

      Upon receiving bytes from an upstream Publisher, LOB write operations will enter into the execution pipeline of this LOB's connection. If an operation fails with an error not in the continueOnErrorSet, the pipeline will abort all subsequent asynchronous operations, up to the next #resume().

      Parameters:
      position - the position at which to start reading from the BLOB value that this Blob object represents; The first position is 1
      continueOnErrorSet - Set of errors which do not cause subsequent operations to be aborted. Not null.
      Returns:
      a Subscriber that appends bytes to this Blob
      Throws:
      SQLException - if a database error occurs, or if this method is called on a Blob that has been freed, or if position is less than 1
      Since:
      21

    • subscriberOracle

      Flow.Subscriber<byte[]> subscriberOracle(long position, Flow.Subscriber<Long> outcomeSubscriber) throws SQLException
      Returns a Subscriber that will append the published bytes to this Blob beginning at the specified position.

      Calling any method of this Blob except isEmptyLob(), isSecureFile(), isTemporary(), or one defined by Object between the time this method is called and the time when the returned Subscriber terminates will block.

      The returned Subscriber terminates once Subscriber.onComplete is received, Subscriber.onError is received, or its subscription is cancelled.

      The outcome of writing published bytes to the BLOB value that this Blob object represents is published to the outcomeSubscriber:

      • The outcomeSubscriber receives an onNext signal each time a write to the BLOB value is successful. The number of bytes transferred in each successful write is the argument to each invocation of onNext.
      • The outcomeSubscriber receives an onComplete signal after the last published byte has been written successfully.
      • The outcomeSubscriber receives an onError signal with a SQLException if a failure occurs when writing published bytes.

      The outcomeSubscriber must signal demand in order to receive any of the signals listed above. If more than Flow.defaultBufferSize() writes have succeeded without demand from the outcomeSubscriber, then the returned subscriber will not signal further demand until the outcomeSubscriber has also signalled demand.

      The number of writes used to transfer published bytes to the BLOB value is implementation defined, and may be different from the number of byte arrays published to the returned Subscriber.

      An invocation of this method is equivalent to invoking subscriberOracle(long, Subscriber, ErrorSet) with the ErrorSet configured by OracleCommonConnection.continueOnError(ErrorSet).

      Parameters:
      position - the position at which to start reading from the BLOB value that this Blob object represents; The first position is 1
      outcomeSubscriber - a Subscriber of write outcomes.
      Returns:
      a Subscriber that appends bytes to this Blob
      Throws:
      SQLException - if a database error occurs, or if this method is called on a Blob that has been freed, or if position is less than 1
      NullPointerException - if the outcomeSubscriber argument is null.
      Since:
      21

    • subscriberOracle

      default Flow.Subscriber<byte[]> subscriberOracle(long position, Flow.Subscriber<Long> outcomeSubscriber, ErrorSet continueOnErrorSet) throws SQLException
      Returns a Subscriber that will append the published bytes to this Blob beginning at the specified position.

      Calling any method of this Blob except isEmptyLob(), isSecureFile(), isTemporary(), or one defined by Object between the time this method is called and the time when the returned Subscriber terminates will block.

      The returned Subscriber terminates once Subscriber.onComplete is received, Subscriber.onError is received, or its subscription is cancelled.

      The outcome of writing published bytes to the BLOB value that this Blob object represents is published to the outcomeSubscriber:

      • The outcomeSubscriber receives an onNext signal each time a write to the BLOB value is successful. The number of bytes transferred in each successful write is the argument to each invocation of onNext.
      • The outcomeSubscriber receives an onComplete signal after the last published byte has been written successfully.
      • The outcomeSubscriber receives an onError signal with a SQLException if a failure occurs when writing published bytes.

      The outcomeSubscriber must signal demand in order to receive any of the signals listed above. If more than Flow.defaultBufferSize() writes have succeeded without demand from the outcomeSubscriber, then the returned subscriber will not signal further demand until the outcomeSubscriber has also signalled demand.

      The number of writes used to transfer published bytes to the BLOB value is implementation defined, and may be different from the number of byte arrays published to the returned Subscriber.

      Upon receiving bytes from an upstream Publisher, LOB write operations will enter into the execution pipeline of this LOB's connection. If an operation fails with an error not in the continueOnErrorSet, the pipeline will abort all subsequent asynchronous operations, up to the next #resume().

      Parameters:
      position - the position at which to start reading from the BLOB value that this Blob object represents; The first position is 1
      outcomeSubscriber - a Subscriber of write outcomes.
      continueOnErrorSet - Set of errors which do not cause subsequent operations to be aborted. Not null.
      Returns:
      a Subscriber that appends bytes to this Blob
      Throws:
      SQLException - if a database error occurs, or if this method is called on a Blob that has been freed, or if position is less than 1
      NullPointerException - if the outcomeSubscriber argument is null.
      Since:
      23

    • freeAsyncOracle

      default Flow.Publisher<Void> freeAsyncOracle() throws SQLException
      Returns a Publisher that publishes the result of freeing the Blob object and the resources that it holds. The object is invalid after the returned Publisher terminates with onComplete.

      After the returned Publisher terminates with onComplete, any attempt to invoke a method other than Blob.free() or freeAsyncOracle will result in an SQLException being thrown. Calling freeAsyncOracle on a Blob object that has already been freed is treated as a no-op.

      Calling any method of this Blob except isEmptyLob(), isSecureFile(), isTemporary(), or one defined by Object between the time this method is called and the time when the returned Subscriber terminates will block.

      The returned publisher terminates once all subscribers have received Subscriber.onComplete, received Subscriber.onError, or cancelled their subscription.

      The returned publisher will only emit onComplete or onError; No items are emitted to onNext.

      Returns:
      a Publisher of the result of freeing this Blob
      Throws:
      SQLException - if a database error occurs
      Since:
      21