Merge branch '31-map-error-codes-to-exceptions' into 'main'

Map common OBX_ERROR codes to exceptions

Closes #31

See merge request objectbox/objectbox-dart!28

Author: greenrobot-team

objectbox/CHANGELOG.md

@@ -10,6 +10,11 @@
 * Allow `analyzer` with major version 5. #487
 * Generator not longer warns that it can not find the package source root if the output directory is
   the package root directory.
+* Add `StorageException` which is a `ObjectBoxException` with an `errorCode` (a `OBX_ERROR` code).
+* Throw `DbFullException` instead of `ObjectBoxException` with message `10101 Could not put` (error 
+  code `OBX_ERROR_DB_FULL`).
+* Change `Query.findUnique()` to throw `NonUniqueResultException` instead of 
+  `UniqueViolationException` if there is more than one result.
 
 ## 1.6.2 (2022-08-24)
 

objectbox/lib/src/common.dart

@@ -1,3 +1,5 @@
+import '../objectbox.dart';
+
 /// Wrapper for a semantic version information.
 class Version {
   /// Major version number.
@@ -28,13 +30,96 @@ class ObjectBoxException implements Exception {
   String toString() => 'ObjectBoxException: $message';
 }
 
+/// Thrown if a property query aggregate function (e.g. `sum()`) can not compute
+/// a result due to a number type overflowing.
+class NumericOverflowException extends ObjectBoxException {
+  /// See [NumericOverflowException].
+  NumericOverflowException(String message) : super(message);
+}
+
+/// ObjectBox database exception with an OBX_ERROR code.
+class StorageException extends ObjectBoxException {
+  /// OBX_ERROR code as defined in [objectbox.h of the C library](https://github.com/objectbox/objectbox-c/blob/main/include/objectbox.h).
+  final int errorCode;
+
+  /// Create with a message and OBX_ERROR code.
+  StorageException(String message, this.errorCode) : super(message);
+
+  @override
+  String toString() => 'StorageException: $message (OBX_ERROR code $errorCode)';
+}
+
+/// Thrown when applying a transaction (e.g. putting an object) would exceed the
+/// `maxDBSizeInKB` configured when calling [Store.new].
+class DbFullException extends StorageException {
+  /// See [DbFullException].
+  DbFullException(String message, int errorCode) : super(message, errorCode);
+}
+
+/// Thrown when the maximum amount of readers (read transactions) was exceeded.
+///
+/// Verify that your code only uses a reasonable amount of threads.
+///
+/// If a very high number of threads (>100) needs to be used, consider
+/// setting `maxReaders` when calling [Store.new].
+class DbMaxReadersExceededException extends StorageException {
+  /// See [DbMaxReadersExceededException].
+  DbMaxReadersExceededException(String message, int errorCode)
+      : super(message, errorCode);
+}
+
+/// Thrown when an error occurred that requires the store to be closed.
+///
+/// This may be an I/O error. Regular operations won't be possible. To handle
+/// this exit the app or try to reopen the store.
+class DbShutdownException extends StorageException {
+  /// See [DbShutdownException].
+  DbShutdownException(String message, int errorCode)
+      : super(message, errorCode);
+}
+
 /// A unique constraint would have been violated by this database operation.
 class UniqueViolationException extends ObjectBoxException {
   /// Create a new exception.
   UniqueViolationException(String message) : super(message);
 }
 
-/// Flags to enable debug options when creating a [Store].
+/// Thrown when there is an error with the data schema (data model).
+///
+/// Typically, there is a conflict between the data model defined in your code
+/// (using `@Entity` classes) and the data model of the existing database file.
+///
+/// Read the [meta model docs](https://docs.objectbox.io/advanced/meta-model-ids-and-uids#resolving-meta-model-conflicts)
+/// on why this can happen and how to resolve such conflicts.
+class SchemaException extends ObjectBoxException {
+  /// See [SchemaException].
+  SchemaException(String message) : super(message);
+}
+
+/// Errors were detected in a database file, e.g. illegal values or structural
+/// inconsistencies.
+class DbFileCorruptException extends StorageException {
+  /// See [DbFileCorruptException].
+  DbFileCorruptException(String message, int errorCode)
+      : super(message, errorCode);
+}
+
+/// Errors related to pages were detected in a database file, e.g. bad page refs
+/// outside of the file.
+class DbPagesCorruptException extends DbFileCorruptException {
+  /// See [DbPagesCorruptException].
+  DbPagesCorruptException(String message, int errorCode)
+      : super(message, errorCode);
+}
+
+/// Thrown if `Query.findUnique()` is called, but the query matches more than
+/// one object.
+class NonUniqueResultException extends ObjectBoxException {
+  /// See [NonUniqueResultException].
+  NonUniqueResultException(String message) : super(message);
+}
+
+/// Passed as `debugFlags` when calling [Store.new] to enable debug options.
 class DebugFlags {
   /// Log read transactions.
   static const int logTransactionsRead = 1;

objectbox/lib/src/native/bindings/helpers.dart

@@ -57,25 +57,41 @@ class ObjectBoxNativeError {
 
   ObjectBoxNativeError(this.code, this.message, this.context);
 
-  String get fullMessage =>
-      context == null ? '$code $message' : '$context: $code $message';
+  String get messageWithContext =>
+      context == null ? message : '$context: $message';
+
+  String get messageWithErrorCode => code == 0
+      ? messageWithContext
+      : '$messageWithContext (OBX_ERROR code $code)';
 
   Never throwMapped() {
     switch (code) {
       case OBX_ERROR_ILLEGAL_STATE:
-        throw StateError(fullMessage);
+        throw StateError(messageWithErrorCode);
       case OBX_ERROR_ILLEGAL_ARGUMENT:
-      case OBX_ERROR_STD_ILLEGAL_ARGUMENT:
-        throw ArgumentError(fullMessage);
+        throw ArgumentError(messageWithErrorCode);
       case OBX_ERROR_NUMERIC_OVERFLOW:
-      case OBX_ERROR_STD_OUT_OF_RANGE:
-      case OBX_ERROR_STD_RANGE:
-      case OBX_ERROR_STD_OVERFLOW:
-        throw RangeError(fullMessage);
+        throw NumericOverflowException(messageWithContext);
+      case OBX_ERROR_DB_FULL:
+        throw DbFullException(messageWithContext, code);
+      case OBX_ERROR_MAX_READERS_EXCEEDED:
+        throw DbMaxReadersExceededException(messageWithContext, code);
+      case OBX_ERROR_STORE_MUST_SHUTDOWN:
+        throw DbShutdownException(messageWithContext, code);
       case OBX_ERROR_UNIQUE_VIOLATED:
-        throw UniqueViolationException(fullMessage);
+        throw UniqueViolationException(messageWithContext);
+      case OBX_ERROR_SCHEMA:
+        throw SchemaException(messageWithContext);
+      case OBX_ERROR_FILE_CORRUPT:
+        throw DbFileCorruptException(messageWithContext, code);
+      case OBX_ERROR_FILE_PAGES_CORRUPT:
+        throw DbPagesCorruptException(messageWithContext, code);
       default:
-        throw ObjectBoxException(fullMessage);
+        if (code == 0) {
+          throw ObjectBoxException(messageWithContext);
+        } else {
+          throw StorageException(messageWithContext, code);
+        }
     }
   }
 }

objectbox/lib/src/native/query/query.dart

@@ -775,7 +775,8 @@ class Query<T> {
   }
 
   /// Finds the only object matching the query. Returns null if there are no
-  /// results or throws if there are multiple objects matching.
+  /// results or throws [NonUniqueResultException] if there are multiple objects
+  /// matching.
   ///
   /// Note: [offset] and [limit] are respected, if set. Because [limit] affects
   /// the number of matched objects, make sure you leave it at zero or set it
@@ -794,7 +795,7 @@ class Query<T> {
           return false;
         }
       } else {
-        error = UniqueViolationException(
+        error = NonUniqueResultException(
             'Query findUnique() matched more than one object');
         return false;
       }

objectbox/lib/src/native/store.dart

@@ -98,13 +98,16 @@ class Store {
   /// ## Maximum database size
   ///
   /// [maxDBSizeInKB] sets the maximum size the database file can grow to.
-  /// By default this is 1 GB, which should be sufficient for most applications.
-  /// The store will throw when trying to insert more data if the maximum size
-  /// is reached.
+  /// When applying a transaction (e.g. putting an object) would exceed it a
+  /// [DbFullException] is thrown.
   ///
+  /// By default, this is 1 GB, which should be sufficient for most applications.
   /// In general, a maximum size prevents the database from growing indefinitely
   /// when something goes wrong (for example data is put in an infinite loop).
   ///
+  /// This value can be changed, so increased or also decreased, each time when
+  /// opening a store.
+  ///
   /// ## File mode
   ///
   /// Specify [unix-style file permissions](https://en.wikipedia.org/wiki/File_system_permissions#Numeric_notation)
@@ -116,14 +119,14 @@ class Store {
   /// ## Maximum number of readers
   ///
   /// [maxReaders] sets the maximum number of concurrent readers. For most
-  /// applications, the default is fine (~ 126 readers).
+  /// applications, the default is fine (about 126 readers).
   ///
-  /// A "reader" is short for a thread involved in a read transaction.
+  /// A "reader" is short for a thread involved in a read transaction. If the
+  /// maximum is exceeded the store throws [DbMaxReadersExceededException]. In
+  /// this case check that your code only uses a reasonable amount of threads.
   ///
-  /// If the store throws OBX_ERROR_MAX_READERS_EXCEEDED, you should first worry
-  /// about the amount of threads your code is using.
-  /// For highly concurrent setups (e.g. using ObjectBox on the server side) it
-  /// may make sense to increase the number.
+  /// For highly concurrent setups (e.g. you are using ObjectBox on the server
+  /// side) it may make sense to increase the number.
   ///
   /// Note: Each thread that performed a read transaction and is still alive
   /// holds on to a reader slot. These slots only get vacated when the thread

objectbox/test/box_test.dart

@@ -660,7 +660,7 @@ void main() {
                   TxMode.write, () => box.putMany(param));
             }, simpleItems()),
         throwsA(predicate((StateError e) => e.toString().contains(
-            'Bad state: failed to create transaction: 10001 Cannot start a write transaction inside a read only transaction'))));
+            'Bad state: failed to create transaction: Cannot start a write transaction inside a read only transaction (OBX_ERROR code 10001)'))));
   }, skip: notAtLeastDart2_15_0());
 
   test('failing in recursive txn', () {

objectbox/test/query_test.dart

@@ -365,8 +365,8 @@ void main() {
 
     expect(
         () => query.findUnique(),
-        throwsA(predicate((UniqueViolationException e) =>
-            e.toString().contains('more than one'))));
+        throwsA(predicate((NonUniqueResultException e) =>
+            e.message == 'Query findUnique() matched more than one object')));
 
     query.param(TestEntity_.tString).value = 't2';
     expect(query.findUnique()!.tString, 't2');

objectbox/test/store_test.dart

@@ -234,6 +234,32 @@ void main() {
     Directory('store').deleteSync(recursive: true);
   });
 
+  test('store maxDBSizeInKB', () {
+    final testDir = Directory('db-size-test');
+    if (testDir.existsSync()) testDir.deleteSync(recursive: true);
+
+    // Empty file is around 24 KB, object below adds about 12 KB each.
+    var store =
+        Store(getObjectBoxModel(), directory: testDir.path, maxDBSizeInKB: 40);
+    var box = store.box<TestEntity>();
+    box.put(TestEntity.filled(id: 0));
+
+    final testEntity2 = TestEntity.filled(id: 0);
+    expect(
+        () => box.put(testEntity2),
+        throwsA(predicate((e) =>
+            e is DbFullException &&
+            e.errorCode == OBX_ERROR_DB_FULL &&
+            e.message == 'object put failed: Could not put')));
+
+    // Re-open with larger size.
+    store.close();
+    store =
+        Store(getObjectBoxModel(), directory: testDir.path, maxDBSizeInKB: 60);
+    testEntity2.id = 0; // Clear ID of object that failed to put.
+    store.box<TestEntity>().put(testEntity2);
+  });
+
   test('store open in unicode symbol path', () async {
     final parentDir = Directory('unicode-test');
     await parentDir.create();