Improve error handling for BFILE LOBs.

Author: anthony-tuininga

doc/src/release_notes.rst

@@ -80,6 +80,9 @@ Common Changes
     when operations are attempted on BFILE LOBs that are not permitted.
     Previously, ``ORA-22275: invalid LOB locator specified`` was raised
     instead.
+#)  Error ``DPY-3026: operation is only supported on BFILE LOBs`` is now raised
+    when operations are attempted on LOBs that are only supported by BFILE
+    LOBs. Previously, ``DPI-1002: invalid OCI handle`` 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.

src/oracledb/errors.py

@@ -285,6 +285,7 @@ def _raise_not_supported(feature: str) -> None:
 ERR_VECTOR_VERSION_NOT_SUPPORTED = 3023
 ERR_VECTOR_FORMAT_NOT_SUPPORTED = 3024
 ERR_OPERATION_NOT_SUPPORTED_ON_BFILE = 3025
+ERR_OPERATION_ONLY_SUPPORTED_ON_BFILE = 3026
 
 # error numbers that result in DatabaseError
 ERR_TNS_ENTRY_NOT_FOUND = 4000
@@ -643,6 +644,9 @@ def _raise_not_supported(feature: str) -> None:
     ERR_OPERATION_NOT_SUPPORTED_ON_BFILE: (
         "operation is not supported on BFILE LOBs"
     ),
+    ERR_OPERATION_ONLY_SUPPORTED_ON_BFILE: (
+        "operation is only supported on BFILE LOBs"
+    ),
     ERR_ORACLE_NUMBER_NO_REPR: (
         "value cannot be represented as an Oracle number"
     ),

src/oracledb/lob.py

@@ -41,6 +41,10 @@ class BaseLOB:
     def __del__(self):
         self._impl.free_lob()
 
+    def _check_is_bfile(self):
+        if self._impl.dbtype is not DB_TYPE_BFILE:
+            errors._raise_err(errors.ERR_OPERATION_ONLY_SUPPORTED_ON_BFILE)
+
     def _check_not_bfile(self):
         if self._impl.dbtype is DB_TYPE_BFILE:
             errors._raise_err(errors.ERR_OPERATION_NOT_SUPPORTED_ON_BFILE)
@@ -75,12 +79,14 @@ def getfilename(self) -> tuple:
         Return a two-tuple consisting of the directory alias and file name for
         a BFILE type LOB.
         """
+        self._check_is_bfile()
         return self._impl.get_file_name()
 
     def setfilename(self, dir_alias: str, name: str) -> None:
         """
         Set the directory alias and name of a BFILE type LOB.
         """
+        self._check_is_bfile()
         self._impl.set_file_name(dir_alias, name)
 
     @property
@@ -114,6 +120,7 @@ def fileexists(self) -> bool:
         Return a boolean indicating if the file referenced by a BFILE type LOB
         exists.
         """
+        self._check_is_bfile()
         return self._impl.file_exists()
 
     def getchunksize(self) -> int:
@@ -217,6 +224,7 @@ async def fileexists(self) -> bool:
         Return a boolean indicating if the file referenced by a BFILE type LOB
         exists.
         """
+        self._check_is_bfile()
         return await self._impl.file_exists()
 
     async def getchunksize(self) -> int:

tests/test_1900_lob_var.py

@@ -535,9 +535,10 @@ def test_1932(self):
 
     def test_1933(self):
         "1933 - test creating a lob with an invalid type"
-        self.assertRaises(
-            TypeError, self.conn.createlob, oracledb.DB_TYPE_NUMBER
-        )
+        with self.assertRaises(TypeError):
+            self.conn.createlob(oracledb.DB_TYPE_NUMBER)
+        with self.assertRaises(TypeError):
+            self.conn.createlob(oracledb.DB_TYPE_BFILE)
 
     def test_1934(self):
         "1934 - test creation of temporary LOBs with varying data"
@@ -571,6 +572,36 @@ def test_1935(self):
             with self.assertRaisesFullCode("DPY-1001"):
                 lob.write("x")
 
+    def test_1936(self):
+        "1936 - test reading a non-existent directory"
+        directory_name = "TEST_1936_MISSING_DIR"
+        file_name = "test_1936_missing_file.txt"
+        self.cursor.execute(
+            "select BFILENAME(:1, :2) from dual", [directory_name, file_name]
+        )
+        (bfile,) = self.cursor.fetchone()
+        self.assertEqual(bfile.getfilename(), (directory_name, file_name))
+        with self.assertRaisesFullCode("ORA-22285"):
+            bfile.fileexists()
+        with self.assertRaisesFullCode("ORA-22285"):
+            bfile.read()
+
+    def test_1937(self):
+        "1937 - test using BFILE methods on non-BFILE LOBs"
+        types = [
+            oracledb.DB_TYPE_BLOB,
+            oracledb.DB_TYPE_CLOB,
+            oracledb.DB_TYPE_NCLOB,
+        ]
+        for typ in types:
+            lob = self.conn.createlob(typ)
+            with self.assertRaisesFullCode("DPY-3026"):
+                lob.getfilename()
+            with self.assertRaisesFullCode("DPY-3026"):
+                lob.setfilename("not_relevant", "not_relevant")
+            with self.assertRaisesFullCode("DPY-3026"):
+                lob.fileexists()
+
 
 if __name__ == "__main__":
     test_env.run_test_cases()

tests/test_5700_lob_var_async.py

@@ -441,6 +441,8 @@ async def test_5723(self):
         "5723 - test creating a lob with an invalid type"
         with self.assertRaises(TypeError):
             await self.conn.createlob(oracledb.DB_TYPE_NUMBER)
+        with self.assertRaises(TypeError):
+            await self.conn.createlob(oracledb.DB_TYPE_BFILE)
 
     async def test_5724(self):
         "5724 - test creation of temporary LOBs with varying data"
@@ -458,6 +460,52 @@ async def test_5724(self):
                 await lob.write(additional_data, len(initial_data) + 1)
                 self.assertEqual(await lob.read(), expected_result)
 
+    async def test_5725(self):
+        "5725 - test reading and writing a LOB with a closed connection"
+        types = [
+            oracledb.DB_TYPE_BLOB,
+            oracledb.DB_TYPE_CLOB,
+            oracledb.DB_TYPE_NCLOB,
+        ]
+        for typ in types:
+            conn = await test_env.get_connection(use_async=True)
+            lob = await conn.createlob(typ, "Temp LOB")
+            await conn.close()
+            with self.assertRaisesFullCode("DPY-1001"):
+                await lob.read()
+            with self.assertRaisesFullCode("DPY-1001"):
+                await lob.write("x")
+
+    async def test_5726(self):
+        "5726 - test reading a non-existent directory"
+        directory_name = "TEST_5726_MISSING_DIR"
+        file_name = "test_5726_missing_file.txt"
+        await self.cursor.execute(
+            "select BFILENAME(:1, :2) from dual", [directory_name, file_name]
+        )
+        (bfile,) = await self.cursor.fetchone()
+        self.assertEqual(bfile.getfilename(), (directory_name, file_name))
+        with self.assertRaisesFullCode("ORA-22285"):
+            await bfile.fileexists()
+        with self.assertRaisesFullCode("ORA-22285"):
+            await bfile.read()
+
+    async def test_5727(self):
+        "5727 - test using BFILE methods on non-BFILE LOBs"
+        types = [
+            oracledb.DB_TYPE_BLOB,
+            oracledb.DB_TYPE_CLOB,
+            oracledb.DB_TYPE_NCLOB,
+        ]
+        for typ in types:
+            lob = await self.conn.createlob(typ)
+            with self.assertRaisesFullCode("DPY-3026"):
+                lob.getfilename()
+            with self.assertRaisesFullCode("DPY-3026"):
+                lob.setfilename("not_relevant", "not_relevant")
+            with self.assertRaisesFullCode("DPY-3026"):
+                await lob.fileexists()
+
 
 if __name__ == "__main__":
     test_env.run_test_cases()