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

All Methods Instance Methods Abstract Methods Default Methods
`void` `close()` 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 a empty blob.
`boolean` `isOpen()` 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.
`void` `open​(LargeObjectAccessMode mode)` Open a BLOB in the indicated mode.
`default Flow.Publisher<byte[]>` `publisherOracle​(long position)` Returns a `Publisher` that publishes the content of this `Blob` beginning at the specified position.
`default Flow.Subscriber<byte[]>` `subscriberOracle​(long position)` 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)` Returns a `Subscriber` that will append the published bytes to this `Blob` beginning at the specified position.
`SQLXML` `toSQLXML()` Returns an object which impements java.sql.SQLXML with content take from this Clob.
`SQLXML` `toSQLXML​(int csid)` Returns an object which impements 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 Detail

#### open

    void open​(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:
  8.2.0

#### close

    void close()
        throws SQLException

Close a previously opened BLOB.

Throws:
  `SQLException`
Since:
  8.2.0

#### isOpen

    boolean isOpen()
            throws SQLException

Check whether the BLOB is opened.

Returns:
  true if the LOB is opened.
Throws:
  `SQLException`
Since:
  8.2.0

#### 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 had 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 a empty blob. False if it does not.

Returns:
  true if the lob locator points to a 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:
  a 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 impements 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 impements java.sql.SQLXML with content taken from this Blob.

Returns:
  the new SQLXML object
Throws:
  `SQLException`
Since:
  12.2

#### publisherOracle

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

Asynchronous tasks initiated by this method will execute under the current `AccessControlContext` of the calling thread.

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:
  20

#### subscriberOracle

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

Asynchronous tasks initiated by this method will execute under the current `AccessControlContext` of the calling thread.

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:
  20

#### subscriberOracle

    default 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`.

Asynchronous tasks initiated by this method will execute under the current `AccessControlContext` of the calling thread.

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:
  20

#### 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`.

Asynchronous tasks initiated by this method will execute under the current `AccessControlContext` of the calling thread.

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