Package oracle.jdbc

## Interface OracleBfile

All Known Implementing Classes:
  `BFILE`

    public interface OracleBfile

This interface defines methods for Oracle specific Bfile. BFILE is an Oracle proprietary data type that provides read-only access to data located outside the database tablespaces.

Since:
  11.2.0.3.0

### 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` `closeFile()` Close the FILE.
`void` `closeLob()` Close a previously opened external LOB.
`boolean` `fileExists()` Find out if a given BFILE (whose locator) points to a file that actually exists on the server's filesystem.
`java.io.InputStream` `getBinaryStream()` Retrieve the entire BFILE as a stream.
`java.io.InputStream` `getBinaryStream​(long pos)` Read from the external LOB as a stream at the requested position.
`byte[]` `getBytes​(long pos, int length)` Return a copy of the contents of the BFILE at the requested position.
`int` `getBytes​(long pos, int length, byte[] buf)` Copy the contents of the BFILE at the requested position to supplied buffer.
`java.lang.String` `getDirAlias()` Gets the Bfile's directory alias.
`java.lang.String` `getName()` Gets the Bfile's file name.
`boolean` `isFileOpen()` Find out whether a BFILE was opened
`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 external LOB is opened.
`long` `length()` The length of the BFILE in bytes.
`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` `openFile()` Open the FILE.
`void` `openLob​(LargeObjectAccessMode mode)` Open an external LOB in the indicated mode.
`long` `position​(byte[] pattern, long start)` Determine the byte position at which the given byte pattern
`long` `position​(OracleBfile pattern, long start)` Determine the byte position at which the given pattern
`java.util.concurrent.Flow.Publisher<byte[]>` `publisherOracle​(long position)` Returns a `Publisher` that publishes the content of this `BFile` beginning at the specified position.
`default java.util.concurrent.Flow.Publisher<byte[]>` `publisherOracle​(long position, ErrorSet continueOnErrorSet)` Returns a `Publisher` that publishes the content of this `BFile` beginning at the specified position.

### Method Detail

#### length

    long length()
         throws java.sql.SQLException

The length of the BFILE in bytes.

Returns:
  length of the BFILE in bytes
Throws:
  `java.sql.SQLException`

#### getBytes

    byte[] getBytes​(long pos,
                    int length)
             throws java.sql.SQLException

Return a copy of the contents of the BFILE at the requested position.

Parameters:
  `pos` - is the first byte of the bfile to be extracted.(1-based)
  `length` - is the number of consecutive bytes to be copied.
Returns:
  a byte array containing a portion of the BFILE
Throws:
  `java.sql.SQLException`

#### getBytes

    int getBytes​(long pos,
                 int length,
                 byte[] buf)
          throws java.sql.SQLException

Copy the contents of the BFILE at the requested position to supplied buffer.

Parameters:
  `pos` - is the first byte of the bfile to be extracted. (1-based)
  `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 BFILE
Throws:
  `java.sql.SQLException`

#### getBinaryStream

    java.io.InputStream getBinaryStream()
                                 throws java.sql.SQLException

Retrieve the entire BFILE as a stream.

Returns:
  a stream containing the BFILE data
Throws:
  `java.sql.SQLException`

#### getBinaryStream

    java.io.InputStream getBinaryStream​(long pos)
                                 throws java.sql.SQLException

Read from the external LOB as a stream at the requested position.

Parameters:
  `pos` - is the position of data to be read. The first position is 1.
Returns:
  an input stream to read data from the BFILE
Throws:
  `java.sql.SQLException`
Since:
  8.2.0

#### position

    long position​(byte[] pattern,
                  long start)
           throws java.sql.SQLException

Determine the byte position at which the given byte pattern

Parameters:
  `pattern` - is the pattern to search for.
  `start` - is the position at which to begin searching. (1-based)
Returns:
  the position at which the pattern appears, else -1.
Throws:
  `java.sql.SQLException`

#### position

    long position​(OracleBfile pattern,
                  long start)
           throws java.sql.SQLException

Determine the byte position at which the given pattern

Parameters:
  `pattern` - is the pattern to search for.
  `start` - is the position at which to begin searching. (1-based)
Returns:
  the position at which the pattern appears, else -1.
Throws:
  `java.sql.SQLException`

#### getName

    java.lang.String getName()
                      throws java.sql.SQLException

Gets the Bfile's file name.

Returns:
  The file name.
Throws:
  `java.sql.SQLException`

#### getDirAlias

    java.lang.String getDirAlias()
                          throws java.sql.SQLException

Gets the Bfile's directory alias.

Returns:
  The directory alias name.
Throws:
  `java.sql.SQLException`

#### openFile

    void openFile()
           throws java.sql.SQLException

Open the FILE.

Throws:
  `java.sql.SQLException`

#### isFileOpen

    boolean isFileOpen()
                throws java.sql.SQLException

Find out whether a BFILE was opened

Returns:
  true if the BFILE was opened, false if it was not opened.
Throws:
  `java.sql.SQLException`

#### fileExists

    boolean fileExists()
                throws java.sql.SQLException

Find out if a given BFILE (whose locator) points to a file that actually exists on the server's filesystem.

Returns:
  true if the physical file exists, false if it does not exist.
Throws:
  `java.sql.SQLException`

#### closeFile

    void closeFile()
            throws java.sql.SQLException

Close the FILE.

Throws:
  `java.sql.SQLException`

#### 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 an external LOB in the indicated mode. Valid modes include MODE_READONLY only. It is an error to open the same LOB twice.

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

#### openLob

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

Open an external LOB in the indicated mode. Valid modes include MODE_READONLY only. 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 external LOB.

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

#### closeLob

    void closeLob()
           throws java.sql.SQLException

Close a previously opened external LOB.

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 external LOB 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 external LOB is opened.

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

#### publisherOracle

    java.util.concurrent.Flow.Publisher<byte[]> publisherOracle​(long position)
                                                         throws java.sql.SQLException

Returns a `Publisher` that publishes the content of this `BFile` 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 `BFile` except `fileExists()`, `getDirAlias()`, `getName()`, 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 BFILE value that this `Bfile` object represents; The first position is 1
Returns:
  a `Publisher` of the content of this `BFile`
Throws:
  `java.sql.SQLException` - if a database error occurs or if `position` is less than 1
Since:
  21

#### publisherOracle

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

Returns a `Publisher` that publishes the content of this `BFile` 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 `BFile` except `fileExists()`, `getDirAlias()`, `getName()`, 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 BFILE value that this `Bfile` 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 `BFile`
Throws:
  `java.sql.SQLException` - if a database error occurs or if `position` is less than 1
Since:
  23