JDXA^TM Introduction

JDXA™ Introduction

This is a brief introduction to the JDXA ORM product (a.k.a. JDX for Android). JDXA can be used to 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 sample code and 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.

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.

• Overview

• Installation

• Using JDXA in your Android project

• Simple Example Code

• Sample Projects

Overview

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, JDX provides fast, flexible, lightweight, and easy-to-use ORM functionality.  

JDX bridges the gap between the worlds of objects and relations with a simple and flexible solution. Some of the prominent features of JDX include:

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 typical ORM-related structure of Android applications, ORM specification files, usage of Android-specific utility classes, and JDX API calls.

The following discussions provide some details about installing and using JDXA ORM SDK for Android app development.

The terms JDX, JDX for Android, and JDXA are used synonymously throughout this document.

Installation

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 libs directory has the jar file JDXAndroid-nn.n.jar containing compiled code of JDXA ORM and associated utilities where nn.n denotes the version of JDXA. For example, JDXAndroid-01.5.jar denotes JDXA version 01.5 and JDXAndroid-02.0.jar denotes JDXA version 02.0.

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).

Using JDXA in your Android project

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,

After setting up these jar files as external libraries, you can start using JDX APIs in your Android project.

Simple Example Code

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)

JDX 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 JDX. 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 JDX APIs

The following code gives an example of how the core and utility JDX 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 {
       JDXSetup jdxSetup = 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;
       }
   }

Sample Projects

The JDXA ORM for Android SDK ships with many sample Eclipse projects of working Android applications, which use JDXA ORM for data integration. These projects provide examples of many different features of the JDXA ORM technology 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.

All the sample projects are provided as Eclipse IDE projects. However, an X in the Available as Android Studio Project column means that the SDK also contains that sample project for Android Studio IDE (in the directory examples/ AndroidStudioJDXAProjects).