Added support for BFILE in thin mode.

anthony-tuininga · anthony-tuininga · commit f24399e8aef6 · 2024-06-10T16:18:29.000-06:00
diff --git a/doc/src/api_manual/module.rst b/doc/src/api_manual/module.rst
@@ -3016,10 +3016,6 @@ Also see the table :ref:`supporteddbtypes`.
     Describes columns, attributes or array elements in a database that are of
     type BFILE. It will compare equal to the DB API type :data:`BINARY`.
 
-    .. note::
-
-        DB_TYPE_BFILE database type is only supported in the python-oracledb
-        Thick mode.  See :ref:`enablingthick`.
 
 .. data:: DB_TYPE_BINARY_DOUBLE
 
diff --git a/doc/src/release_notes.rst b/doc/src/release_notes.rst
@@ -18,6 +18,7 @@ Thin Mode Changes
 +++++++++++++++++
 
 #)  Added support for :ref:`two-phase commits <tpc>`.
+#)  Added support for data of type :data:`~oracledb.DB_TYPE_BFILE`.
 #)  When calling :meth:`ConnectionPool.acquire()` or
     :meth:`AsyncConnectionPool.acquire()`, the connection pool ``mode``
     :data:`oracledb.POOL_GETMODE_TIMEDWAIT` now always honors the
@@ -55,6 +56,10 @@ Common Changes
 #)  Error ``DPY-2050: invalid flags for tpc_end()`` is now raised when invalid
     flags are passed to :meth:`Connection.tpc_end()`. Previously, ``TypeError``
     or ``DPI-1002: invalid OCI handle`` was raised instead.
+#)  Error ``DPY-3025: operation is not supported on BFILE LOBs`` is now raised
+    when operations are attempted on BFILE LOBs that are not permitted.
+    Previously, ``ORA-22275: invalid LOB locator specified`` was raised
+    instead.
 #)  Error ``DPY-4005: timed out waiting for the connection pool to return a
     connection`` is now raised consistently when using get mode
     :data:`oracledb.POOL_GETMODE_TIMEDWAIT` and the timeout expires.
diff --git a/doc/src/user_guide/appendix_a.rst b/doc/src/user_guide/appendix_a.rst
@@ -454,7 +454,7 @@ values.
       - :ref:`oracledb.LOB <lobobj>`, bytes, str
     * - BFILE
       - :data:`~oracledb.DB_TYPE_BFILE`
-      - Not supported in python-oracledb Thin mode.
+      - No relevant notes
       - Cannot be set
     * - JSON
       - :data:`~oracledb.DB_TYPE_JSON`
diff --git a/doc/src/user_guide/lob_data.rst b/doc/src/user_guide/lob_data.rst
@@ -5,10 +5,11 @@ Using CLOB and BLOB Data
 ************************
 
 Oracle Database uses :ref:`LOB objects <lobobj>` to store large data such as text, images,
-videos, and other multimedia formats.  The maximum size of a LOB is limited to
+videos, and other multimedia formats.  The maximum size of a LOB (large object) is limited to
 the size of the tablespace storing it.
 
-There are four types of LOB (large object):
+There are `four types of LOBs <https://www.oracle.com/pls/topic/lookup?ctx=
+dblatest&id=GUID-0A692C1B-1C95-4121-8F95-25BE465B87F6>`__:
 
     * BLOB - Binary Large Object, used for storing binary data. python-oracledb uses
       the type :attr:`oracledb.DB_TYPE_BLOB`.
@@ -18,9 +19,12 @@ There are four types of LOB (large object):
     * NCLOB - National Character Large Object, used for string strings in the
       national character set format. python-oracledb uses the type
       :attr:`oracledb.DB_TYPE_NCLOB`.
-    * BFILE - External Binary File, used for referencing a file stored on the
-      host operating system outside of the database. python-oracledb uses the type
-      :attr:`oracledb.DB_TYPE_BFILE`.
+    * BFILE - External Binary File, used
+      for referencing a file stored on the host operating system outside of
+      the database. python-oracledb uses the type
+      :attr:`oracledb.DB_TYPE_BFILE`. See `BFILEs <https://www.oracle.com/pls/
+      topic/lookup?ctx=dblatest&id=GUID-D4642C92-F343-4700-9F1F-
+      486F82249FB8>`__ for more information.
 
 LOBs can be streamed to, and from, Oracle Database.
 
diff --git a/src/oracledb/errors.py b/src/oracledb/errors.py
@@ -284,6 +284,7 @@ def _raise_not_supported(feature: str) -> None:
 ERR_NAMED_TIMEZONE_NOT_SUPPORTED = 3022
 ERR_VECTOR_VERSION_NOT_SUPPORTED = 3023
 ERR_VECTOR_FORMAT_NOT_SUPPORTED = 3024
+ERR_OPERATION_NOT_SUPPORTED_ON_BFILE = 3025
 
 # error numbers that result in DatabaseError
 ERR_TNS_ENTRY_NOT_FOUND = 4000
@@ -637,6 +638,9 @@ def _raise_not_supported(feature: str) -> None:
     ERR_NUMBER_WITH_EMPTY_EXPONENT: "invalid number: empty exponent",
     ERR_NUMBER_WITH_INVALID_EXPONENT: "invalid number: invalid exponent",
     ERR_OBJECT_IS_NOT_A_COLLECTION: "object {name} is not a collection",
+    ERR_OPERATION_NOT_SUPPORTED_ON_BFILE: (
+        "operation is not supported on BFILE LOBs"
+    ),
     ERR_ORACLE_NUMBER_NO_REPR: (
         "value cannot be represented as an Oracle number"
     ),
diff --git a/src/oracledb/impl/base/connection.pyx b/src/oracledb/impl/base/connection.pyx
@@ -95,7 +95,8 @@ cdef class BaseConnImpl:
                 return value
         elif db_type_num in (DB_TYPE_NUM_CLOB,
                              DB_TYPE_NUM_NCLOB,
-                             DB_TYPE_NUM_BLOB):
+                             DB_TYPE_NUM_BLOB,
+                             DB_TYPE_NUM_BFILE):
             if isinstance(value, (PY_TYPE_LOB, PY_TYPE_ASYNC_LOB)):
                 lob_impl = value._impl
                 if lob_impl.dbtype is not dbtype:
@@ -107,6 +108,7 @@ cdef class BaseConnImpl:
                                       expected_type_name=dbtype.name)
                 return value
             elif self._allow_bind_str_to_lob \
+                    and db_type_num != DB_TYPE_NUM_BFILE \
                     and isinstance(value, (bytes, str)):
                 if db_type_num == DB_TYPE_NUM_BLOB:
                     if isinstance(value, str):
diff --git a/src/oracledb/impl/base/types.pyx b/src/oracledb/impl/base/types.pyx
@@ -110,7 +110,7 @@ cdef class DbType:
 
 # database types
 DB_TYPE_BFILE = DbType(DB_TYPE_NUM_BFILE, "DB_TYPE_BFILE", "BFILE",
-                       NATIVE_TYPE_NUM_LOB, 114)
+                       NATIVE_TYPE_NUM_LOB, 114, buffer_size_factor=4000)
 DB_TYPE_BINARY_DOUBLE = DbType(DB_TYPE_NUM_BINARY_DOUBLE,
                                "DB_TYPE_BINARY_DOUBLE", "BINARY_DOUBLE",
                                NATIVE_TYPE_NUM_DOUBLE, 101,
diff --git a/src/oracledb/impl/thick/utils.pyx b/src/oracledb/impl/thick/utils.pyx
@@ -190,7 +190,8 @@ cdef int _convert_from_python(object value, DbType dbtype,
             dbvalue.asObject = obj_impl._handle
     elif oracle_type == DPI_ORACLE_TYPE_CLOB \
             or oracle_type == DPI_ORACLE_TYPE_BLOB \
-            or oracle_type == DPI_ORACLE_TYPE_NCLOB:
+            or oracle_type == DPI_ORACLE_TYPE_NCLOB \
+            or oracle_type == DPI_ORACLE_TYPE_BFILE:
         if isinstance(value, PY_TYPE_LOB):
             lob_impl = value._impl
             if var_impl is not None:
diff --git a/src/oracledb/impl/thin/constants.pxi b/src/oracledb/impl/thin/constants.pxi
@@ -528,13 +528,18 @@ cdef enum:
     TNS_LOB_OP_CLOSE = 0x10000
     TNS_LOB_OP_IS_OPEN = 0x11000
     TNS_LOB_OP_ARRAY = 0x80000
+    TNS_LOB_OP_FILE_EXISTS = 0x0800
+    TNS_LOB_OP_FILE_OPEN = 0x0100
+    TNS_LOB_OP_FILE_CLOSE = 0x0200
+    TNS_LOB_OP_FILE_ISOPEN = 0x0400
 
 # LOB locator constants
 cdef enum:
     TNS_LOB_LOC_OFFSET_FLAG_1 = 4
     TNS_LOB_LOC_OFFSET_FLAG_3 = 6
     TNS_LOB_LOC_OFFSET_FLAG_4 = 7
     TNS_LOB_QLOCATOR_VERSION = 4
+    TNS_LOB_LOC_FIXED_OFFSET = 16
 
 # LOB locator flags (byte 1)
 cdef enum:
@@ -554,6 +559,7 @@ cdef enum:
 # other LOB constants
 cdef enum:
     TNS_LOB_OPEN_READ_WRITE = 2
+    TNS_LOB_OPEN_READ_ONLY = 11
     TNS_LOB_PREFETCH_FLAG = 0x2000000
 
 # end-to-end metrics
diff --git a/src/oracledb/impl/thin/dbobject.pyx b/src/oracledb/impl/thin/dbobject.pyx
@@ -385,7 +385,9 @@ cdef class ThinDbObjectImpl(BaseDbObjectImpl):
                               TNS_DATA_TYPE_TIMESTAMP_LTZ,
                               TNS_DATA_TYPE_TIMESTAMP_TZ):
             return buf.read_date()
-        elif ora_type_num in (TNS_DATA_TYPE_CLOB, TNS_DATA_TYPE_BLOB):
+        elif ora_type_num in (TNS_DATA_TYPE_CLOB,
+                              TNS_DATA_TYPE_BLOB,
+                              TNS_DATA_TYPE_BFILE):
             conn_impl = self.type._conn_impl
             locator = buf.read_bytes()
             if locator is None:
diff --git a/src/oracledb/impl/thin/lob.pyx b/src/oracledb/impl/thin/lob.pyx
@@ -155,6 +155,48 @@ cdef class BaseThinLobImpl(BaseLobImpl):
             message.data = (<str> value).encode(self._get_encoding())
         return message
 
+    cdef LobOpMessage _create_file_exists_message(self):
+        """
+        Create a message needed to return if BFILE exists.
+        """
+        cdef LobOpMessage message
+        message = self._conn_impl._create_message(LobOpMessage)
+        message.operation = TNS_LOB_OP_FILE_EXISTS
+        message.source_lob_impl = self
+        return message
+
+    cdef LobOpMessage _create_file_close_message(self):
+        """
+        Create a message needed to close a file
+        """
+        cdef LobOpMessage message
+        message = self._conn_impl._create_message(LobOpMessage)
+        message.operation = TNS_LOB_OP_FILE_CLOSE
+        message.source_lob_impl = self
+        return message
+
+    cdef LobOpMessage _create_file_open_message(self):
+        """
+        Create a message needed to open a file
+        """
+        cdef LobOpMessage message
+        message = self._conn_impl._create_message(LobOpMessage)
+        message.operation = TNS_LOB_OP_FILE_OPEN
+        message.source_lob_impl = self
+        message.amount = TNS_LOB_OPEN_READ_ONLY
+        message.send_amount = True
+        return message
+
+    cdef LobOpMessage _create_get_file_is_open_message(self):
+        """
+        Create a message needed to return if a file is open
+        """
+        cdef LobOpMessage message
+        message = self._conn_impl._create_message(LobOpMessage)
+        message.operation = TNS_LOB_OP_FILE_ISOPEN
+        message.source_lob_impl = self
+        return message
+
     cdef const char* _get_encoding(self):
         """
         Return the encoding used by the LOB.
@@ -186,6 +228,38 @@ cdef class BaseThinLobImpl(BaseLobImpl):
         """
         return 2**32 - 1
 
+    def get_file_name(self):
+        """
+        Internal method for returning a 2-tuple constaining the directory.
+        """
+        cdef:
+            const char_type *ptr = self._locator
+            uint16_t dir_name_offset, file_name_offset
+            uint16_t dir_name_len, file_name_len
+        dir_name_offset = TNS_LOB_LOC_FIXED_OFFSET + 2
+        dir_name_len = unpack_uint16(&ptr[TNS_LOB_LOC_FIXED_OFFSET],
+                                     BYTE_ORDER_MSB)
+        file_name_offset = dir_name_offset + dir_name_len + 2
+        file_name_len = unpack_uint16(&ptr[dir_name_offset + dir_name_len],
+                                      BYTE_ORDER_MSB)
+        return (
+            ptr[dir_name_offset:dir_name_offset + dir_name_len].decode(),
+            ptr[file_name_offset:file_name_offset + file_name_len].decode()
+        )
+
+    def set_file_name(self, str dir_alias, str name):
+        """
+        Internal method for setting the directory alias and file name
+        associated with a BFILE LOB.
+        """
+        cdef char_type dir_length[2]
+        cdef char_type name_length[2]
+        pack_uint16(dir_length, len(dir_alias), BYTE_ORDER_MSB)
+        pack_uint16(name_length, len(name), BYTE_ORDER_MSB)
+        self._locator = self._locator[:TNS_LOB_LOC_FIXED_OFFSET] + \
+                dir_length[:2] + dir_alias.encode() + name_length[:2] + \
+                name.encode()
+
 
 cdef class ThinLobImpl(BaseThinLobImpl):
 
@@ -200,14 +274,27 @@ cdef class ThinLobImpl(BaseThinLobImpl):
         """
         Internal method for closing a LOB that was opened earlier.
         """
-        self._process_message(self._create_close_message())
+        if self.dbtype._ora_type_num == TNS_DATA_TYPE_BFILE:
+            self._process_message(self._create_file_close_message())
+        else:
+            self._process_message(self._create_close_message())
 
     def create_temp(self):
         """
         Internal method for creating a temporary LOB.
         """
         self._process_message(self._create_create_temp_message())
 
+    def file_exists(self):
+        """
+        Internal method for returning whether the file referenced by a BFILE
+        exists.
+        """
+        cdef LobOpMessage message
+        message = self._create_file_exists_message()
+        self._process_message(message)
+        return message.bool_flag
+
     def get_chunk_size(self):
         """
         Internal method for returning the chunk size of the LOB.
@@ -224,7 +311,10 @@ cdef class ThinLobImpl(BaseThinLobImpl):
         Internal method for returning whether the LOB is open or not.
         """
         cdef LobOpMessage message
-        message = self._create_get_is_open_message()
+        if self.dbtype._ora_type_num == TNS_DATA_TYPE_BFILE:
+            message = self._create_get_file_is_open_message()
+        else:
+            message = self._create_get_is_open_message()
         self._process_message(message)
         return message.bool_flag
 
@@ -243,17 +333,29 @@ cdef class ThinLobImpl(BaseThinLobImpl):
         """
         Internal method for opening a LOB.
         """
-        self._process_message(self._create_open_message())
+        if self.dbtype._ora_type_num == TNS_DATA_TYPE_BFILE:
+            self._process_message(self._create_file_open_message())
+        else:
+            self._process_message(self._create_open_message())
 
     def read(self, uint64_t offset, uint64_t amount):
         """
         Internal method for reading a portion (or all) of the data in the LOB.
         """
-        cdef LobOpMessage message
+        cdef:
+            bint should_close = False
+            LobOpMessage message
+        if self.dbtype._ora_type_num == TNS_DATA_TYPE_BFILE:
+            if not self.get_is_open():
+                should_close = True
+                self.open()
         message = self._create_read_message(offset, amount)
         self._process_message(message)
+        if should_close:
+            self.close()
         if message.data is None:
-            if self.dbtype._ora_type_num == TNS_DATA_TYPE_BLOB:
+            if self.dbtype._ora_type_num in (TNS_DATA_TYPE_BLOB,
+                                             TNS_DATA_TYPE_BFILE):
                 return b""
             return ""
         return message.data
@@ -287,7 +389,10 @@ cdef class AsyncThinLobImpl(BaseThinLobImpl):
         """
         Internal method for closing a LOB that was opened earlier.
         """
-        await self._process_message(self._create_close_message())
+        if self.dbtype._ora_type_num == TNS_DATA_TYPE_BFILE:
+            await self._process_message(self._create_file_close_message())
+        else:
+            await self._process_message(self._create_close_message())
 
     async def create_temp(self):
         """
@@ -306,12 +411,25 @@ cdef class AsyncThinLobImpl(BaseThinLobImpl):
         await self._process_message(message)
         return message.amount
 
+    async def file_exists(self):
+        """
+        Internal method returning a boolean indicating if file referenced by a
+        BFILE exists.
+        """
+        cdef LobOpMessage message
+        message = self._create_file_exists_message()
+        await self._process_message(message)
+        return message.bool_flag
+
     async def get_is_open(self):
         """
         Internal method for returning whether the LOB is open or not.
         """
         cdef LobOpMessage message
-        message = self._create_get_is_open_message()
+        if self.dbtype._ora_type_num == TNS_DATA_TYPE_BFILE:
+            message = self._create_get_file_is_open_message()
+        else:
+            message = self._create_get_is_open_message()
         await self._process_message(message)
         return message.bool_flag
 
@@ -330,17 +448,29 @@ cdef class AsyncThinLobImpl(BaseThinLobImpl):
         """
         Internal method for opening a LOB.
         """
-        await self._process_message(self._create_open_message())
+        if self.dbtype._ora_type_num == TNS_DATA_TYPE_BFILE:
+            await self._process_message(self._create_file_open_message())
+        else:
+            await self._process_message(self._create_open_message())
 
     async def read(self, uint64_t offset, uint64_t amount):
         """
         Internal method for reading a portion (or all) of the data in the LOB.
         """
-        cdef LobOpMessage message
+        cdef:
+            bint should_close = False
+            LobOpMessage message
+        if self.dbtype._ora_type_num == TNS_DATA_TYPE_BFILE:
+            if not await self.get_is_open():
+                should_close = True
+                await self.open()
         message = self._create_read_message(offset, amount)
         await self._process_message(message)
+        if should_close:
+            await self.close()
         if message.data is None:
-            if self.dbtype._ora_type_num == TNS_DATA_TYPE_BLOB:
+            if self.dbtype._ora_type_num in (TNS_DATA_TYPE_BLOB,
+                                             TNS_DATA_TYPE_BFILE):
                 return b""
             return ""
         return message.data
diff --git a/src/oracledb/impl/thin/messages.pyx b/src/oracledb/impl/thin/messages.pyx
diff --git a/src/oracledb/impl/thin/packet.pyx b/src/oracledb/impl/thin/packet.pyx
diff --git a/src/oracledb/lob.py b/src/oracledb/lob.py
diff --git a/src/oracledb/thin_impl.pyx b/src/oracledb/thin_impl.pyx
diff --git a/tests/sql/create_schema.sql b/tests/sql/create_schema.sql
