We are introducing the ObjectBox Generator today to simplify ObjectBox development for more programming languages, starting with C/C++. Additionally, we are releasing a brand new C++ API that goes hand in hand with the new generator. Historically, our C API was rather low level as it was focused on providing the foundation for our Swift and Go APIs. With this release we want to provide C/C++ developers with ObjectBox convenience and ease of use.
ObjectBox Generator takes over the burden of writing the binding code and data model declaration. Based on a single input file, it generates the code for you, so you can focus on the actual application logic.
Generator Example
ObjectBox let’s you handle data as FlatBuffers. For example, you can put and get data objects as FlatBuffers encoded bytes. To work with FlatBuffers, you need to define a FlatBuffer schema file (.fbs). And this file is also the input for ObjectBox Generator. This way, everything is defined in a single location.
Let’s say we have a FlatBuffers schema file “task.fbs” with the following content:
| 1 2 3 4 5 6 | table Task { id: ulong; text: string; date_created: ulong; date_finished: ulong; } |
Now, we can tell ObjectBox Generator to use this file to generate C++ sources:
| 1 | ./objectbox-generator -cpp task.fbs |
This makes ObjectBox Generator to generate the following files:
- objectbox-model.h: source code to build the internal data model, that you need to pass when creating a store.
- objectbox-model.json: keeps track of internal schema IDs; you don’t need to worry about this except that you should put it in your source control.
- task-cpp.obx.h: the C++ value structs (data objects), binding code for FlatBuffers and the new Box class.
C++ API Example
Now, let’s use the previously generated code and the new C++ API around the Store and Box classes. A simple CRUD application boils down to a few lines:
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | #include "objectbox-cpp.h" #include "objectbox-model.h" // provides create_obx_model() #include "task-cpp.obx.h" // provides Task struct and bindings int main(int argc, char* args[]) { obx::Store store(create_obx_model()); obx::Box<Task> taskBox(store); obx_id id = box.put({.text = "Buy milk"}); // Create std::unique_ptr<Task> task = box.get(id); // Read if (task) { task->text += " & some bread"; box.put(*task); // Update ... box.remove(id); // Delete } ... } |
Note that the generated code is header-only and compatible with the existing ObjectBox C-API, allowing both to be used from the same application. The C and C++ APIs both have unique advantages: the C++ API uses RAII so you do not need to worry about cleaning up, while the C API has additional features, e.g. queries.
Open Source, Docs
ObjectBox Generator is open source and available on GitHub. The repository comes with a readme file that also serves as a documentation. Among other things, you will find ObjectBox specific annotations there, which are used in fbs files to express ObjectBox-specific concerns. For example, in the definition of Task above, we used ulong as a FlatBuffers type to store dates. However, FlatBuffers does not know what a date is and we use ObjectBox annotations to express this:
| 1 2 | /// objectbox: date date_created: ulong; |
For our initial release of ObjectBox Generator and the public C++ API we decided on labeling it as version 0.9. Although we are already very close to a 1.0 and we wanted to gather some feedback before our first major release. As we can still change the API or smooth out any rough edges you may find, we cannot stress enough how much we welcome and appreciate your feedback at this point. Thank you!
