Actian Zen Core Database for Android
Quick Start Guide – May 2018
This preview of the Zen Core embedded database is designed for Android developers. The .zip download archive for the preview includes the following items:
To build the TaskList application as an Android project, we recommend the configuration that was used to develop it:
The rest of this guide covers the following topics:
Building the TaskList Sample Application
The TaskList project provides an introduction to implementing applications that use the Zen Core database on Android devices. This sample application implements a simple task or to-do list. The user creates a task by entering its title. Tasks are stored in a Btrieve data file. The tasks are retrieved from the data file and displayed on the screen. The user can delete the tasks.
Package Details
The .zip download archive contains the following Android files:
These files are described in greater detail in the following topics.
Build.gradle
Android Studio uses Gradle for building applications. The file build.gradle is the build configuration file and is located in /TaskList/app. Build.gradle file has the following section:
// Zen DB interfaces.
sourceSets {
    main {
        // let gradle pack these libraries into apk
        jniLibs.srcDirs = ['libs']
    }
}
This section packages the binary files under app/libs with the application.
Binary Files Under app/libs
The TaskList/app/libs directory contains various binary files. Some are processor-specific and must be packaged with the application:
Zen Database Configuration File
The file zendb.config is located in /TaskList/app/src/main/assets. It is a configuration file used by the database engine and must be packaged with the application. On first execution after installation, the application extracts it from the assets and writes it to the file system of the Android device.
Sample Application
The TaskList application source files are found in /TaskList/app/src/main/java/com/actian/zen/tasklist.
Other Files
Other files are associated with the application, such as the .xml files describing the user interface layout, strings, and image files for the launcher icon. These are standard files found in Android applications.
Implementation Details
The database engine libraries have been built targeting a minimum API level of 21 (Android 5.0). They have been compiled against Android NDK version 16.
Tasks are represented by TaskRecord objects. TaskRecord.java contains the implementation of this class. Each task has a title and an ID which is a unique number identifying the task. The tasks are stored in a simple database file where each record is comprised of the ID and the title.
Initialization
Initialization code resides in the onCreate method of the TaskListActivity class. ZenDBHelper.Initialize method is called on startup. This function extracts the zendb.config file from the application assets and places it in the files folder. This extraction is needed only once after installation. Then the function also calls the DbManager.Initialize() method to initialize the database engine. The location of the configuration file is passed as an argument. Note that the ZenDbHelper class is also loading the JNI interface libbtrievecppjni.so. After initialization, the TaskTable object is constructed. The complete path of the database file is needed to create and open it. The TaskTable constructor is given this path.
User Interface
The user interface for the application is implemented in TaskListActivity.java.
Listing Tasks
TaskListActivity.updateUI performs the task of displaying a list of tasks. The tasks are read from the database file using a TaskRecordIterator object. The constructed list of tasks is then handed off to an Android Listview object. A custom adapter (TaskListAdapter) is used here. The adapter enables switching from the user interface view object to a TaskRecord object using a setTag/getTag mechanism provided by Android.
Adding New Tasks
Tapping the plus button at top right in the application calls the dialog code in the TaskListActivity.onOptionsItemSelected method. This method calls the TaskCursor.insert method to insert the newly created TaskRecord object.
Deleting Tasks
Each task is displayed with a Delete button. Tapping this Delete button calls the method TaskListActivity.deleteTask with the view argument corresponding to the user interface element associated with the button. Since the view has been tagged with the task ID, it is possible to retrieve this ID using the getTag method. The ID is used to invoke the TaskCursor.deleteById method.
TaskTable Class
TaskTable encapsulates the record layout. Each record is comprised of a 4-byte ID field and a 32-byte Title field. The task title is stored as a null terminated UTF-8 encoded string. There is an index on the auto-incrementing ID field. The creation of the database file is done by the createIfNeeded method. The putRecord method packs a TaskRecord object into an array of bytes. The getRecord method constructs a TaskRecord from the raw bytes read from the database table.
As used in the sample program, all clients of the single TaskTable object share a single BtrieveClient object. If it is necessary for different clients to perform transactions and be isolated from each other, then multiple BtrieveClient objects can be used.
TaskCursor Class
A BtrieveFile object is needed to perform operations on the database file. It provides a cursor or handle interface to the database file. TaskCursor is a wrapper around the BtrieveFile object. In the TaskList sample program, TaskCursors and associated BtrieveFile objects are opened as needed and immediately closed after performing database operations, which works well if a database file is not being extensively used. For light database operations by short-lived applications, best practice is to close the database file handles as soon as possible. Closing ensures that pending writes to the database file are flushed by the engine. For heavy database operations by background applications, it may be desirable to keep the handle opened for a longer period.
In the deleteById method, there is an example of using the BtrieveFile.Retrieve method to look up a record using a key.
TaskRecordIterator Class
The TaskRecordIterator class uses the RetrieveFirst and RetrieveNext methods of BtrieveFile to scan the database file.
Frequently Asked Questions
If you have problems with your installation, you can get help online from the Zen/PSQL community forum or the knowledge base at the Actian website. The following are common questions after installation:
What is Btrieve?
Btrieve is a transactional database engine that supports CRUD operations on records stored in indexed sequential access method (ISAM) files. The Btrieve file format consists of pages of data that move between memory and storage when the engine performs I/O operations. For more information, see the Wikipedia articles for the Architecture of Btrieve and Btrieve, as well as the Zen/PSQL documentation at docs.actian.com.
What is the Btrieve 2 API?
Btrieve 2 is a new Btrieve interface for C and C++ developers of database applications. The Btrieve 2 API offers a simplified, more intuitive alternative for sending the full set of Btrieve calls to the database engine. PSQL developers can make use of the performance and flexibility of Btrieve without having to learn and manage the complexity of the original Btrieve API. To learn more, see Getting Started with the Btrieve C++ and C API.
What is the relationship between Actian Zen Core and Actian PSQL?
Actian Zen Core is a new offering created from the Actian PSQL database family to provide zero DBA, embeddable database technology for Android developers. Zen Core is based on the PSQL database engine.
Where can I find the Zen Core documentation?
You may use the documentation installed with other Actian Zen/PSQL editions or at docs.actian.com. Throughout the Zen/PSQL documentation, all references to PSQL databases also apply to Actian Zen databases.
Community Forums and Technical Support
You can find information and obtain help from several online options at the Actian website:
Community Forums. Join the technical discussion under Actian Zen (PSQL).
Knowledge Base. Search articles for answers and solutions others have found useful.
Technical Support. Open a help ticket, submit a defect, or purchase services.
Disclaimer
ACTIAN CORPORATION LICENSES THE SOFTWARE AND DOCUMENTATION PRODUCT TO YOU OR YOUR COMPANY SOLELY ON AN "AS IS" BASIS AND SOLELY IN ACCORDANCE WITH THE TERMS AND CONDITIONS OF THE ACCOMPANYING LICENSE AGREEMENT.
Copyright © 2018 Actian Corporation. All Rights Reserved.