Package oracle.jdbc

## Interface OracleClob

All Superinterfaces:
  `java.sql.Clob`

All Known Subinterfaces:
  `OracleNClob`

All Known Implementing Classes:
  `CLOB`, `NCLOB`

    public interface OracleClob
    extends java.sql.Clob

This interface extends the standard JDBC interface `Clob` and defines methods for Oracle specific Clob .

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

Since:
  11.2.0.3

### Method Summary

All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods
`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 CLOB.
`default java.util.concurrent.Flow.Publisher<java.lang.Void>` `freeAsyncOracle()` Returns a `Publisher` that publishes the result of freeing the `Clob` object and the resources that it holds.
`boolean` `isEmptyLob()` Return true if this is an empty lob.
`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 CLOB 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 clob.
`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 CLOB in the indicated mode.
`java.util.concurrent.Flow.Publisher<java.lang.String>` `publisherOracle​(long position)` Returns a `Publisher` that publishes the content of this `Clob` beginning at the specified position.
`default java.util.concurrent.Flow.Publisher<java.lang.String>` `publisherOracle​(long position, ErrorSet continueOnErrorSet)` Returns a `Publisher` that publishes the content of this `Clob` beginning at the specified position.
`java.util.concurrent.Flow.Subscriber<java.lang.String>` `subscriberOracle​(long position)` Returns a `Subscriber` that will append the published characters to this `Clob` beginning at the specified position.
`java.util.concurrent.Flow.Subscriber<java.lang.String>` `subscriberOracle​(long position, java.util.concurrent.Flow.Subscriber<java.lang.Long> outcomeSubscriber)` Returns a `Subscriber` that will append the published characters to this `Clob` beginning at the specified position.
`default java.util.concurrent.Flow.Subscriber<java.lang.String>` `subscriberOracle​(long position, java.util.concurrent.Flow.Subscriber<java.lang.Long> outcomeSubscriber, ErrorSet continueOnErrorSet)` Returns a `Subscriber` that will append the published characters to this `Clob` beginning at the specified position.
`default java.util.concurrent.Flow.Subscriber<java.lang.String>` `subscriberOracle​(long position, ErrorSet continueOnErrorSet)` Returns a `Subscriber` that will append the published characters to this `Clob` beginning at the specified position.
`java.sql.SQLXML` `toSQLXML()` Returns an object which implements java.sql.SQLXML with content taken from this Clob.
`java.sql.SQLXML` `toSQLXML​(java.lang.String schemaURL)` Returns an object which implements java.sql.SQLXML with content taken from this Clob.

### Methods inherited from interface java.sql.Clob

`free, getAsciiStream, getCharacterStream, getCharacterStream, getSubString, length, position, position, setAsciiStream, setCharacterStream, setString, setString, truncate`

### Method Detail

#### open

    @Deprecated(since="23.5",
                forRemoval=true)
    default void open​(LargeObjectAccessMode mode)
               throws java.sql.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 CLOB in the indicated mode. Valid modes include MODE_READONLY, and MODE_READWRITE. It is an error to open the same LOB twice.

Throws:
  `java.sql.SQLException`
Since:
  8.2.0

#### openLob

    void openLob​(LargeObjectAccessMode mode)
          throws java.sql.SQLException

Open a CLOB in the indicated mode. Valid modes include MODE_READONLY, and MODE_READWRITE. It is an error to open the same LOB twice.

Throws:
  `java.sql.SQLException`
Since:
  23.5

#### close

    @Deprecated(since="23.5",
                forRemoval=true)
    default void close()
                throws java.sql.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 CLOB.

Throws:
  `java.sql.SQLException`
Since:
  8.2.0

#### closeLob

    void closeLob()
           throws java.sql.SQLException

Close a previously opened CLOB.

Throws:
  `java.sql.SQLException`
Since:
  23.5

#### isOpen

    @Deprecated(since="23.5",
                forRemoval=true)
    default boolean isOpen()
                    throws java.sql.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 CLOB is opened.

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

#### isOpenLob

    boolean isOpenLob()
               throws java.sql.SQLException

Check whether the CLOB is opened.

Returns:
  true if the LOB is opened.
Throws:
  `java.sql.SQLException`
Since:
  23.5

#### isTemporary

    boolean isTemporary()
                 throws java.sql.SQLException

Return true if the lob locator points to a temporary clob. False if it does not.

Returns:
  true if the lob locator points to a temporary clob. False if it does not.
Throws:
  `java.sql.SQLException`
Since:
  8.2.0

#### isEmptyLob

    boolean isEmptyLob()
                throws java.sql.SQLException

Return true if this is an empty lob.

Returns:
  true if this is an empty lob.
Throws:
  `java.sql.SQLException`
Since:
  8.1.7

#### isSecureFile

    boolean isSecureFile()
                  throws java.sql.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:
  `java.sql.SQLException`

#### toSQLXML

    java.sql.SQLXML toSQLXML()
                      throws java.sql.SQLException

Returns an object which implements java.sql.SQLXML with content taken from this Clob.

Returns:
  the new SQLXML object
Throws:
  `java.sql.SQLException`
Since:
  12.2

#### toSQLXML

    java.sql.SQLXML toSQLXML​(java.lang.String schemaURL)
                      throws java.sql.SQLException

Returns an object which implements java.sql.SQLXML with content taken from this Clob.

Returns:
  the new SQLXML object
Throws:
  `java.sql.SQLException`
Since:
  12.2

#### publisherOracle

    java.util.concurrent.Flow.Publisher<java.lang.String> publisherOracle​(long position)
                                                                   throws java.sql.SQLException

Returns a `Publisher` that publishes the content of this `Clob` beginning at the specified position. The argument to each call to `Subscriber.onNext` will contain an implementation defined number of characters.

Calling any method of this `Clob` 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 writing to the CLOB value that this `Clob` object represents; The first position is 1
Returns:
  a `Publisher` of the content of this `Clob`
Throws:
  `java.sql.SQLException` - if a database error occurs, or if this method is called on a `Clob` that has been freed, or if `position` is less than 1
Since:
  21

#### publisherOracle

    default java.util.concurrent.Flow.Publisher<java.lang.String> publisherOracle​(long position,
                                                                                  ErrorSet continueOnErrorSet)
                                                                           throws java.sql.SQLException

Returns a `Publisher` that publishes the content of this `Clob` beginning at the specified position. The argument to each call to `Subscriber.onNext` will contain an implementation defined number of characters.

Calling any method of this `Clob` 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 `OracleCommonConnection.resume()`.

Parameters:
  `position` - the position at which to start writing to the CLOB value that this `Clob` 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 `Clob`
Throws:
  `java.sql.SQLException` - if a database error occurs, or if this method is called on a `Clob` that has been freed, or if `position` is less than 1
  `java.lang.NullPointerException` - if the `continueOnErrorSet` is null
  `java.lang.IllegalArgumentException` - if the `continueOnErrorSet` is not supported. At a minimum, all drivers must support `ErrorSet.NO_ERRORS` and `ErrorSet.ALL_ERRORS`
Since:
  23

#### subscriberOracle

    java.util.concurrent.Flow.Subscriber<java.lang.String> subscriberOracle​(long position)
                                                                     throws java.sql.SQLException

Returns a `Subscriber` that will append the published characters to this `Clob` beginning at the specified position.

Calling any method of this `Clob` 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 writing to the CLOB value that this `Clob` object represents; The first position is 1
Returns:
  a `Subscriber` that appends characters to this `Clob`
Throws:
  `java.sql.SQLException` - if a database error occurs, or if this method is called on a `Clob` that has been freed, or if `position` is less than 1
Since:
  21

#### subscriberOracle

    default java.util.concurrent.Flow.Subscriber<java.lang.String> subscriberOracle​(long position,
                                                                                    ErrorSet continueOnErrorSet)
                                                                             throws java.sql.SQLException

Returns a `Subscriber` that will append the published characters to this `Clob` beginning at the specified position.

Calling any method of this `Clob` 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 characters 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 `OracleCommonConnection.resume()`.

Parameters:
  `position` - the position at which to start writing to the CLOB value that this `Clob` 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 characters to this `Clob`
Throws:
  `java.sql.SQLException` - if a database error occurs, or if this method is called on a `Clob` that has been freed, or if `position` is less than 1
Since:
  23

#### subscriberOracle

    java.util.concurrent.Flow.Subscriber<java.lang.String> subscriberOracle​(long position,
                                                                            java.util.concurrent.Flow.Subscriber<java.lang.Long> outcomeSubscriber)
                                                                     throws java.sql.SQLException

Returns a `Subscriber` that will append the published characters to this `Clob` beginning at the specified position.

Calling any method of this `Clob` 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 characters to the CLOB value that this Clob object represents is published to the `outcomeSubscriber`:

- The `outcomeSubscriber` receives an `onNext` signal each time a write to the CLOB value is successful. The number of characters transferred by each successful write is delivered with each invocation of `onNext`.
- The `outcomeSubscriber` receives an `onComplete` signal after the last published character has been written successfully.
- The `outcomeSubscriber` receives an `onError` signal with a `SQLException` if a failure occurs when writing published characters.

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 characters to the CLOB value is implementation defined, and may be different from the number of Strings 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 writing to the CLOB value that this `Clob` object represents; The first position is 1
  `outcomeSubscriber` - a `Subscriber` of write outcomes.
Returns:
  a `Subscriber` that appends characters to this `Clob`
Throws:
  `java.sql.SQLException` - if a database error occurs, or if this method is called on a `Clob` that has been freed, or if `position` is less than 1
  `java.lang.NullPointerException` - if the `outcomeSubscriber` argument is null.
Since:
  21

#### subscriberOracle

    default java.util.concurrent.Flow.Subscriber<java.lang.String> subscriberOracle​(long position,
                                                                                    java.util.concurrent.Flow.Subscriber<java.lang.Long> outcomeSubscriber,
                                                                                    ErrorSet continueOnErrorSet)
                                                                             throws java.sql.SQLException

Returns a `Subscriber` that will append the published characters to this `Clob` beginning at the specified position.

Calling any method of this `Clob` 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 characters to the CLOB value that this Clob object represents is published to the `outcomeSubscriber`:

- The `outcomeSubscriber` receives an `onNext` signal each time a write to the CLOB value is successful. The number of characters transferred by each successful write is delivered with each invocation of `onNext`.
- The `outcomeSubscriber` receives an `onComplete` signal after the last published character has been written successfully.
- The `outcomeSubscriber` receives an `onError` signal with a `SQLException` if a failure occurs when writing published characters.

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 characters to the CLOB value is implementation defined, and may be different from the number of Strings published to the returned `Subscriber`.

Upon receiving characters 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 `OracleCommonConnection.resume()`.

Parameters:
  `position` - the position at which to start writing to the CLOB value that this `Clob` 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 characters to this `Clob`
Throws:
  `java.sql.SQLException` - if a database error occurs, or if this method is called on a `Clob` that has been freed, or if `position` is less than 1
  `java.lang.NullPointerException` - if the `outcomeSubscriber` argument is null.
Since:
  23

#### freeAsyncOracle

    default java.util.concurrent.Flow.Publisher<java.lang.Void> freeAsyncOracle()
                                                                         throws java.sql.SQLException

Returns a `Publisher` that publishes the result of freeing the `Clob` 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 `Clob.free()` or `freeAsyncOracle` will result in an SQLException being thrown. Calling `freeAsyncOracle` on a `Clob` object that has already been freed is treated as a no-op.

Calling any method of this `Clob` 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 `Clob`
Throws:
  `java.sql.SQLException` - if a database error occurs
Since:
  21