This is a brief introduction to the JDXA Object Relational Mapping (ORM) product. JDXA (a.k.a. JDX for Android) can be used to easily develop mobile apps that require intuitive object-oriented access to device-local SQLite relational data on the Android platform. This document provides an overview of JDXA followed by brief instructions on how to install and use the product. It also provides a simple code example and descriptions of some Android-specific utility classes to simplify app development with JDXA.
This document also contains links to some illustrative code snippets for different mapping scenarios like one-to-one, one-to-many, and many-to-many relationships, and JSON object persistence. Finally, there is a list of many sample projects shipped with the product SDK that demonstrate how different features of JDXA may easily be used to simplify object modeling and data integration tasks for Android apps.
The SDK comes with a comprehensive user manual, javadocs, and many working sample apps.
Note: JDX is the core Object Relational Mapping (ORM) technology developed by Software Tree. This core ORM technology has been adapted for the Android platform and that adaptation is called JDXA. In the context of the Android platform, the terms JDX, JDXA, and JDX for Android may be used synonymously.
In Object Oriented Programming (OOP) languages (e.g. Java, C++, C#), a class encapsulates the structure and behavior of objects of a certain type. Business objects are easier to represent as instances of classes. A domain object model consists of various classes and their relationships comprising an application domain. Integration of domain object model data with relational data is a common need for most object-oriented applications. ORM has become the preferred and most popular paradigm for such integration. Our JDXA ORM product (a.k.a. JDX for Android) increases programmer productivity tremendously by presenting a more intuitive, object-oriented view of relational data and eliminating the need to write endless lines of complex low-level SQL code. Based on some well thought-out KISS (Keep It Simple and Straightforward) principles, JDXA provides fast, flexible, lightweight, and easy-to-use ORM functionality.
JDXA bridges the gap between the worlds of objects and relations with a simple and flexible solution. Some of the prominent features of JDXA include:
There are just 3 simple steps to use JDXA:
On top of the core ORM functionality of JDX, we have created many Android platform-specific utility classes to facilitate the easy and speedy development of mobile apps that need on-device access to SQLite relational database.
The JDXA SDK ships with plenty of documentation including the JDXA User Manual and Javadocs. The SDK also ships with many readymade sample application projects exemplifying the typicla ORM-related structure of Android applications, ORM specification files, usage of Android-specific utility classes, and JDXA API calls.
The following discussions provide some details about installing and using JDXA ORM SDK for Android app development.
Please unzip the JDXA ORM SDK distribution jar file in a new folder (for example, JDXForAndroid). You will see the following directory structure:
JDXForAndroid\
JDXForAndroid_Introduction.pdf
libs\
docs\
examples\
SQLDroidLocal\The docs directory contains the Javadocs on JDXA ORM and associated utilities from an application developer's point of view. This directory also contains the JDXA user manual.
The examples directory contains many sample Eclipse projects that exemplify the usage of JDXA ORM in Android applications.
The SQLDroidLocal directory has the JDBC driver (SQLDroid) library (SQLDroid\bin\sqldroid.jar) based on the open-source code available at GitHub. This library is provided under the terms of The MIT License (MIT).
To use JDXA in your Android project, just add the libraries JDXAndroid-nn.n.jar (shipped in the libs directory of the SDK) and sqldroid.jar (shipped in the SQLDroidLocal\SQLDroid\bin directory of the SDK) as external jars. For example,
compile files('libs/JDXAndroid-nn.n.jar')
After setting up these jar files as external libraries, you can start using JDXA APIs in your Android project.
Just to give you a flavor of coding simplicity achieved by using JDXA ORM, this section provides representative example code of an Android application accessing an on-device SQLite database. Any UI and exception handling code is not provided in these code excerpts. There are just 3 simple steps to use JDX:
1: Define domain object model (Java classes)
JDXA does not impose any restriction in terms of how a class should be defined. Instances of any POJO (Plain Old Java Object) can be persisted using JDXA. Here is an example of a class definition (com.mycompany.model.Employee)
package com.mycompany.model;
import java.util.Date;
public class Employee {
private int id;
private String name;
private Date DOB;
private boolean exempt;
private float**compensation;
// A no-arg constructor needed for JDX
public Employee() {
}
// Define other constructors, and setters/getters
}2. Define a declarative object-relational mapping specification textually
Here is an example of the mapping specification contained in a text file (say example.jdx), which should be located in the res/raw directory of the Android project.
JDX_DATABASE JDX:jdbc:sqldroid:/data/data/com.mycompany/databases/example.db;…
;
CLASS com.mycompany.model.Employee TABLE Employee
PRIMARY_KEY id
SQLMAP FOR compensation COLUMN_NAME Salary
;3: Develop applications using intuitive and powerful JDXA APIs
The following code gives an example of how the core and utility JDXA classes described earlier can be used to initialize an on-device SQLite database and the ORM system, and to interact with the database in an intuitive object-oriented way that does not involve writing any complex SQL code. The AppSpecificJDXSetup utility class (code not shown) is used to easily initialize the database (example.db) and the ORM system based on the mapping specification (example.jdx).
public class JDXAndroidExampleActivity extends Activity {
JDXSetupjdxSetup = null;
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout._main_);
try {
AppSpecificJDXSetup.initialize();
jdxSetup = AppSpecificJDXSetup._getInstance_(this);
useJDXORM(jdxSetup);
} catch (Exception ex) { // Handle exception
cleanup();
return;
}
}
private void cleanup() {
AppSpecificJDXSetup._cleanup_();
jdxSetup = null;
}
private void useJDXORM(JDXSetup jdxSetup) throws Exception {
JDXHelper jdxHelper = new JDXHelper(jdxSetup);
String employeeClassName = Employee.class.getName();
// First delete all existing employees from the database.
jdxHelper.delete2(employeeClassName, null);
// Create and save a new employee Mark
Employee emp = new Employee(1, "Mark", …);
jdxHelper.insert(emp, false);
// Create and save a new employee Bill
emp = new Employee(2, "Bill", …);
jdxHelper.insert(emp, false);
// Retrieve all the employees
List queryResults = jdxHelper.getObjects(employeeClassName, null);
// Retrieve employee Bill (id=2)
emp = (Employee) jdxHelper.getObjectById(employeeClassName, "id=2", ...)
// Change and update attributes of Bill
emp.setExempt(true);
jdxHelper.update(emp, false);
return;
}
}JDXA is shipped with many convenient utility classes (in the package com.softwaretree.jdxandroid) to simplify development of Android apps. These utilities interact with the Android platform-specific artifacts and with the JDXA ORM framework to present a convenient application development interface. An application can use those utilities alone or use those utilities along with JDX Core as per its needs. Here are brief descriptions of some of those utility classes:
JDXSetup
This class helps set up and interact with the JDXA ORM system on the Android platform.
BaseAppSpecificJDXSetup
This is a utility class whose subclass can be used to initialize the underlying database and to create, share, and cleanup a singleton JDXSetup object in an Android application across multiple activities.
JDXHelper
This class provides a useful facade (wrapper) for many of the JDXA ORM methods. You may use this class as is, subclass it to create a more exhaustive wrapper, or use the methods in this class as templates for your own code. Here are some of the methods in the JDXHelper class:
public List getObjects(String className, String predicate)
public int getObjectCount(String className, String attribName, String predicate)
public void insert(Object object, boolean deep)
public void update(Object object, boolean deep)
public void delete(Object object, boolean deep)
public long getNextSeq(String seqName, long increment)
public void setJDXLogging(String jdxLogFileName)SimpleObjectListAdapter
This is an adapter utility class to retrieve and view objects of a given class in ListActivity. Objects are retrieved using the JDXA ORM system. A subclass would implement the abstract methods to use the retrieved objects in appropriate views.
SimpleStreamingObjectsListAdapter
This is a utility object list adapter to retrieve and view a polymorphic stream of objects of a given class in ListActivity. Objects are fetched in chunks (stream) using the JDXA ORM. A subclass would implement the abstract methods to use the retrieved objects in appropriate views.
JDXSeqUtil
This is a utility class to easily mange persistently unique Named Sequence values.
JDX_JSONObject
This class serves as a base class for persisting JSONObject instances of a domain specific class which should be defined as a subclass of this class. The object relational mapping for that domain specific class is defined using VIRTUAL_ATTRIB specifications for each persistent attribute of the corresponding JSON object.
Utils
This class has some nifty utility methods that can be used by JDXA apps.
Here are links to some programming snippets to illustrate JDXA ORM mapping specifications and APIs for sample object models (class definitions). Each sample is named to signify a typical modeling or usage pattern.
In the interest of keeping our description short and to the point, we may not show different constructors and accessor (setter/getter) methods in a class definition. Similarly, although a mapping specification (provided in a text file) may contain mapping information for multiple classes used in a particular application, we might just show and concentrate on the mapping information for only one or a few classes. Also, we may not show any business logic or user interface (UI) related code.
This snippet shows how to define default mapping for a POJO (Plain Old Java Object) class. It also shows JDXA ORM programming code of how instances of such a class can easily be inserted, deleted, updated, and retrieved in an intuitive object oriented way.
We use a simple Employee class for illustration.
Similar to Simple Mapping 1, this snippet additionally shows how to specify a non-default table name, how to specify the table column names to be different than the class attribute names, and how to ignore some attributes for persistence.
Mapping One-To-One Relationships
This snippet shows how to define one-to-one relationships. It also shows example of deep and shallow operations involving related objects.
In the example object mode, an employee has an address and works in a department.
Mapping One-To-Many Relationships
This snippet shows how to define collection classes and one-to-many relationships. It also shows example of deep and shallow operations involving related objects.
In the example class model, a company has many departments.
Mapping Many-To-Many Relationships
This snippet shows how to define collection classes, join classes, and many-to-many relationships. An intermediate join class is used to hold the references for a many-to-many relationship. The snippet also shows examples of deep and shallow operations involving related objects. For a many-to-many relationship, the entities involved in the relationship are considered independent in the sense that insert, update, and delete operations don't go beyond the intermediate join class (table).
In the example object model, one user has many groups and one group has many users.
Mapping Auto-Increment Columns for Primary Key
This snippet shows how to define and use auto-increment columns for generating primary keys for objects of a class. JDXA does not set values of the corresponding columns through the INSERT and UPDATE statements used for storing or updating the instances of this class. However, the query operations do fetch the corresponding column values.
JDX also provides a named sequence generator facility that can alternatively be used to efficiently generate unique ids that you can assign to your objects before saving them in the database.
This snippet shows how to define classes and mapping specifications for persisting JSON objects in a database using JDXA ORM. It also shows JDXA ORM programming code of how JSON objects can easily be inserted, deleted, updated, and retrieved in an intuitive object oriented way.
Although this snippet shows how JDXA can help you with persistence of simple JSON objects, JDXA can also help you easily handle complex JSON objects having other nested JSON objects and arrays of JSON objects.
The JDXA ORM SDK ships with many sample projects of working Android applications, which use JDXA for data integration. These projects provide examples of many different features of the JDXA ORM product including how to specify mappings for domain model classes having one-to-one, one-to-many, and many-to-many relationships, how to use sequence generators for unique ids, how to use object-oriented list view classes, how to automatically create the underlying database schema (tables and constraints) as per the mapping specification, and how to leverage various JDX APIs to easily interact with a relational database in an object-oriented way.
These projects are conveniently located under the examples directory. You may have to adjust the build/library paths for these projects depending upon the location of your SDK installation. Many of these applications produce some illustrative output in either the LogCat panel of the Eclipse IDE (Window → Show View → Other, Android → LogCat) or on the screen.
High-level descriptions of some sample projects follow. Please see the actual code and the documentation for more details.
Some of these sample projects are also hosted on GitHub. The names of such projects are linked to the appropriate GitHub URL.
All the sample projects are provided as Eclipse IDE projects. However, an X in the Also Available as Android Studio Project column means that the SDK also contains that sample project for Android Studio IDE (in the directory examples/ AndroidStudioJDXAProjects).
| Sample Project | Brief Description | Also Available as Android Studio Project |
|---|---|---|
| JDXAndroidSimpleExample | Demonstrates how JDXA ORM and associated utilities can be used to easily develop an Android app that exchanges data of domain model objects with an SQLite database. | X |
| JDXAndroidSimpleExample2 | Demonstrates how a JDXHelper object can be used to interact with relational data using simpler methods. | X |
| JDXAndroidRelationshipsExample | Demonstrates using JDXA for an object model with one-to-one and one-to-many relationships. | X |
| JDXAndroidRelationships2Example | Demonstrates using JDXA for persisting an object model such that the attribute values of the related objects are stored in the same table (INLINE or EMBEDDED) where the attribute values of the parent object are stored. | X |
| JDXAndroidAutoIncrementExample | Demonstrates JDXA facilitating the use of an autoincrement column for a primary key attribute of an object. | X |
| JDXAndroidSimpleLoginExample | Demonstrates how to easily develop a user login/signup subsystem for an Android app. | X |
| JDXAndroidClassHierarchyExample | Demonstrates using JDXA for an object model with class hierarchies. Person is the superclass with BaseEmployee and Intern has its subclasses. BaseEmployee has further two subclasses - PermEmployee and TempEmployee. | X |
| JDXAndroidImagesExample | Demonstrates using JDX with image data. | X |
| JDXAndroidListExample1 | Demonstrates using a JDXA provided ListAdapter class to query a list of objects from the database and displaying them. | X |
| JDXAndroidListExample2 | Demonstrates using a JDX provided ListAdapter class to query a filtered list of objects from the database and displaying them. | X |
| JDXAndroidStreamingExample | Demonstrates use of streaming queries to retrieve a list of objects in separate chunks as needed. | X |
| JDXAndroidStreamingListExample | Demonstrates using a JDXA provided streaming ListAdapter class to query a list of objects from the database and displaying them iteratively on demand by fetching only a few objects from the database at a time. | |
| JDXAndroidSequencesExample | Demonstrates defining named sequences for generating persistently unique sequence numbers and using the JDXSeqUtility class to easily and efficiently create unique keys at runtime. | X |
| JDXAndroidManyToManyExample | Demonstrates using JDXA for an object model with many-to-many relationships. | X |
| JDXAndroidJSONExample | Demonstrates using JDXA for persistence of JSON objects. | X |
| JDXAndroidListWithHolderPatternExample | Demonstrates using JDXA for retrieving a list of objects from databases, employing a holder pattern to cache and use the references to widgets for displaying an object in a list view, and persisting an updated object back into the database. | X |
| JDXAndroidPrePostMethodsExample | Demonstrates using JDXPreInsert, JDXPresUpdate, and JDXPostQuery callback methods in a domain model class to automatically massage (for example, encode, decode, compress, and decompress) instance data (perhaps for security and saving disk space reasons) before saving it to the database and after retrieving it from the database. | X |
| JDXAndroidAsyncQueryExample | Demonstrates using JDXA for retrieving object(s) asynchronously in a background thread and then showing them in a UI (main) thread. | X |
| JDXAndroidCachingExample | Demonstrates how, with JDXA, in-memory caches may be established for particular classes such that the database need not be queried for previously cached objects. | X |
| JDXAndroidDBUpgradeV1Example JDXAndroidDBUpgradeV2Example | Demonstrate a strategy to facilitate easy migration of the existing data produced from an old version of an app for use in the new version of the app. In this strategy, any needed data from the old (existing) database is migrated to a new database, which is then used by the new version of the app. The old database remains unchanged and may be discarded or may be used as a backup resource. | X |
