Note: This file is written in Markdown and is best viewed with a Markdown viewer (e.g., GitHub, GitLab, VS Code, or a dedicated Markdown reader). Viewing it in a plain text editor may not render the formatting as intended.

Copyright (c) 2026 Software Tree

JDX_JSONExample

Overview

This project demonstrates how JDX ORM can persist and retrieve JSON-based domain objects directly to and from a relational database — without requiring traditional Java POJOs with explicit getter/setter fields.

Instead of a conventional Java class, the domain model is built on top of the JDX_JSONObject class, which serves as the foundational base class for handling persistence of domain-specific JSON objects. Application code defines a minimal subclass (e.g., JSON_Employee) with just two constructors.

The ORM mapping uses VIRTUAL_ATTRIB declarations to define the persistent JSON properties and their types declaratively, allowing JDX to bridge the dynamic JSON model to a fixed relational schema.

A JSON_Employee instance can be initialized in three convenient ways:

• Using the put(key, value) API to set attributes programmatically.
• From an existing JSONObject instance.
• From a JSON string (e.g., received from a web service).

---

Prerequisites

• Java JDK 8 or higher installed and on the system PATH.
• JDX ORM SDK installed. Set the environment variable JX_HOME to the SDK's top-level installation directory.
• A supported JDBC-compatible database (SQLite is pre-configured; a MySQL example is also included in the .jdx file).

---

Project Structure

JDX_JSONExample/
├── config/
│   └── json_example.jdx             # ORM mapping specification file
├── src/
│   └── com/softwaretree/jdxjsonexample/
│       ├── JSONExample.java          # Main application entry point
│       └── model/
│           └── JSON_Employee.java    # JSON-based Employee model class
├── bin/                              # Compiled .class files (generated)
├── sources.txt                       # List of Java source files for compilation
├── compile.cmd                       # Windows: compile the Java source files
├── compile.sh                        # Mac/Linux: compile the Java source files
├── setEnvironment.bat                # Windows: sets classpath environment variable
├── setEnvironment.sh                 # Mac/Linux: sets classpath environment variable
├── runJDXExample.bat                 # Windows: run the sample application
├── runJDXExample.sh                  # Mac/Linux: run the sample application
├── forward.bat                       # Windows: create/recreate the database schema
├── forward.sh                        # Mac/Linux: create/recreate the database schema
├── JDXDemo.bat                       # Windows: launch the JDXDemo GUI application
├── JDXDemo.sh                        # Mac/Linux: launch the JDXDemo GUI application
└── README.md                         # This file

---

Domain Model

JSON_Employee — JSON-Based Model Class

Unlike the other JDX examples that use traditional POJOs, JSON_Employee extends JDX_JSONObject and defines only two constructors. All attribute storage and retrieval is handled internally by the JSONObject key-value store.

The persistent properties of a JSON_Employee and how they map to the database are defined entirely in the .jdx mapping file using VIRTUAL_ATTRIB:

JSON Property	Java Type	DB Column	Notes
id	int	id	Primary key
name	String	name
exempt	boolean	exempt
compensation	double	salary	Column name remapped via SQLMAP
DOB	long	DOB	Stored as milliseconds; mapped to SQL DATE

---

Key Components

config/json_example.jdx — ORM Mapping File

This file is the central piece that makes the JSON-based model work with JDX ORM. Key elements:

• JDX_DATABASE and JDBC_DRIVER — database connection and driver settings. Pre-configured for SQLite; a commented-out MySQL example is also included.
• VIRTUAL_ATTRIB — declares each persistent JSON property and its Java type. Because JSONObject stores data dynamically (not in typed Java fields), JDX needs these declarations to know which keys to persist and how to map them to SQL column types.
• PRIMARY_KEY id — designates id as the primary key.
• SQLMAP FOR compensation COLUMN_NAME salary — maps the JSON property compensation to a database column named salary.
• SQLMAP FOR DOB SQLTYPE DATE — instructs JDX to use the SQL DATE type for the DOB value, which is stored in the JSONObject as a long (milliseconds since epoch).

Refer to the JDX Database & JDBC Driver Specification Guide for configuring other databases.

Note: Update JDX_DATABASE and JDBC_DRIVER to match your local database setup before running.

---

src/.../model/JSON_Employee.java — JSON-Based Model Class

A minimal shell class that extends JDX_JSONObject. It defines only two constructors — a no-arg constructor and one that accepts a JSONObject — and inherits all persistence behavior from the superclass. No fields, getters, or setters are needed.

---

src/.../JSONExample.java — Main Application

The entry point of the sample application. It initializes JDX ORM and demonstrates the following:

1. Delete all existing JSON_Employee objects from the database.
2. Insert Mark — built using the put(key, value) API directly on a JSON_Employee instance.
3. Insert David — built from an explicitly constructed JSONObject instance passed to the JSON_Employee constructor.
4. Insert Steve — built by parsing a raw JSON string (simulating data arriving from a web service) into a JSONObject, then wrapping it in JSON_Employee.
5. Query all employees and print results.
6. Retrieve employee David (id=2) by object ID.
7. Extract the underlying JSONObject from the retrieved employee and print its string representation.

---

sources.txt — Source File List

Lists all .java source files to be compiled, one per line:

./src/com/softwaretree/jdxjsonexample/model/JSON_Employee.java
./src/com/softwaretree/jdxjsonexample/JSONExample.java

This file is passed to javac using the @sources.txt argument syntax.

---

compile.cmd / compile.sh — Compilation Scripts

Compiles all Java source files listed in sources.txt and outputs .class files into the bin/ directory.

• Requires JX_HOME to be set to the JDX ORM SDK installation directory.
• Links against jxclasses.jar (JDX ORM library) and json-20240303.jar (for JSONObject support).
• compile.cmd — Windows batch script (supports JDK 8; a commented line supports JDK 9+).
• compile.sh — Mac/Linux shell script equivalent.

Windows:

compile.cmd

Mac/Linux:

chmod +x compile.sh   # first time only
./compile.sh

---

setEnvironment.bat / setEnvironment.sh — Environment Setup

Sets the CLASSPATH environment variable to include the JDX ORM libraries, the org.json library, and the appropriate JDBC driver JAR. Edit this file to point to the correct JDBC driver for your database before running the application.

Note that json-20240303.jar is included here in addition to the other examples, as it is a runtime dependency for the JSON object model.

• setEnvironment.bat — Windows (uses ; as classpath separator).
• setEnvironment.sh — Mac/Linux (uses : as classpath separator; sourced via source ./setEnvironment.sh).

---

runJDXExample.bat / runJDXExample.sh — Run Script

Invokes the environment setup script to configure the classpath, then runs the JSONExample main class.

Windows:

runJDXExample.bat

Mac/Linux:

chmod +x runJDXExample.sh   # first time only
./runJDXExample.sh

---

forward.bat / forward.sh — Schema Generation

Creates (or recreates) the database schema based on the ORM specification in the .jdx file, without running the application.

Windows:

forward -create

Mac/Linux:

chmod +x forward.sh   # first time only
./forward.sh -create

---

JDXDemo.bat / JDXDemo.sh — JDXDemo GUI

Launches the JDXDemo desktop GUI application, which provides a graphical way to browse and interact with the database using the JDX ORM configuration.

Windows:

JDXDemo.bat

Mac/Linux:

chmod +x JDXDemo.sh   # first time only
./JDXDemo.sh

---

Getting Started

1. Set JX_HOME to the root of your JDX ORM SDK installation.

2. Configure the database by editing config/json_example.jdx:

   • Update JDX_DATABASE with the correct connection URL and credentials.
   • Update JDBC_DRIVER with the appropriate JDBC driver class.
   • Update setEnvironment.bat (Windows) or setEnvironment.sh (Mac/Linux) to include the JDBC driver JAR on the classpath.

3. Compile the source files:

   compile.cmd          # Windows
   ./compile.sh         # Mac/Linux

4. Run the sample application:

   runJDXExample.bat    # Windows
   ./runJDXExample.sh   # Mac/Linux

   The application will automatically create the database schema on first run (controlled by the forceCreateSchema flag in JSONExample.java).

Mac/Linux tip: Run chmod +x *.sh once in the project directory to make all shell scripts executable.

---

Importing into Eclipse

This project can be imported directly into the Eclipse IDE as an existing Java project using File → Import → Existing Projects into Workspace.

---

Additional Resources

• JDX Database & JDBC Driver Specification Guide
• JDX ORM SDK documentation (included in your SDK installation under JX_HOME)