Skip to content

README.md

Latest commit

 

History

History
280 lines (197 loc) · 12.7 KB

README.md

File metadata and controls

280 lines (197 loc) · 12.7 KB

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_JSON2Example

Overview

This project extends the JSON-based persistence pattern (introduced in JDX_JSONExample) to demonstrate how JDX ORM can handle relationships between JSON-based domain objects — specifically one-to-one and one-to-many relationships — using JDX_JSONObject subclasses.

The domain model consists of three JSON-based classes:

  • A — has a one-to-one relationship with a B object, and a one-to-many relationship with an array of C objects.
  • B — a simple JSON object related to A.
  • C — a simple JSON object; zero or more C objects may be associated with one A.

All three classes are thin shell subclasses of JDX_JSONObject. Relationships are declared in the .jdx mapping file using RELATIONSHIP and COLLECTION_CLASS — the same mechanisms used for traditional POJO-based models. Application code works entirely at the JSON level (using put, get, JSONObject, JSONArray), while JDX ORM handles all relational persistence transparently.

The example also demonstrates getObjectModelSummary() — a JDX API that returns a summary of the loaded ORM object model — and shows how to extract the underlying JSONObject from a retrieved domain object to pass it to other parts of an application or over a network.

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 (MySQL is pre-configured; an SQLite example is also included in the .jdx file).

Project Structure

JDX_JSON2Example/
├── config/
│   └── json2_example.jdx            # ORM mapping specification file
├── src/
│   └── com/softwaretree/jdxjson2example/
│       ├── JSON2Example.java         # Main application entry point
│       └── model/
│           ├── A.java                # JSON-based class A (has B and array of C)
│           ├── B.java                # JSON-based class B
│           └── C.java                # JSON-based class C
├── 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

All three model classes are minimal shell subclasses of JDX_JSONObject, each defining only two constructors (no-arg and JSONObject). Their persistent JSON properties and relationships are declared entirely in the .jdx mapping file.

Class Table Primary Key Relationships
A A aId One B (one-to-one, BYVALUE); array of C (one-to-many, BYVALUE)
B B bId Belongs to A via aId (reference key parentId)
C C cId Belongs to A via aId

Persistent JSON properties per class

Class A:

Property Type Notes
aId int Primary key
aString String
aBoolean boolean
aFloat double Nullable
aDate long Stored as milliseconds

Class B:

Property Type Notes
bId int Primary key
aId int Foreign key to A; declared as parentId reference key
bInt int
bString String

Class C:

Property Type Notes
cId int Primary key
aId int Foreign key to A
cInt int
cString String

Special note on class A's relationship fields

Class A declares two public fields — aB (of type B) and aCs (of type C[]) — purely to support the JDX ORM mapping specification. These fields are not used directly in application logic. All manipulation of A's related objects is done at the JSON level using put with a JSONObject or JSONArray. Directly assigning a JDX_JSONObject subclass instance to these fields (e.g., a.aB = b) is not supported and will cause a runtime exception.

Key Components

config/json2_example.jdx — ORM Mapping File

This file defines the VIRTUAL_ATTRIB properties, relationships, and collection for the three JSON-based classes. Key elements:

  • JDX_DATABASE and JDBC_DRIVER — pre-configured for MySQL; a commented-out SQLite example is also included.
  • JDX_OBJECT_MODEL_PACKAGE — the base Java package, allowing short class name references.
  • OBJECT_MODEL_OVERVIEW — a free-text description of the object model, returned by getObjectModelSummary().
  • VIRTUAL_ATTRIB — declares each persistent JSON property and its Java type for all three classes.
  • RELATIONSHIP aB REFERENCES .B BYVALUE REFERENCED_KEY parentId WITH aId — maps A's one-to-one owned relationship to B, using parentId as the reference key alias for aId in B.
  • RELATIONSHIP aCs REFERENCES ArrayC BYVALUE WITH aId — maps A's one-to-many owned relationship to an array of C objects.
  • COLLECTION_CLASS ArrayC — defines the array collection type for C objects, keyed by aId.
  • REFERENCE_KEY parentId aId in class B — declares aId as an alternate reference key (parentId) used by the relationship from A.

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/.../JSON2Example.java — Main Application

The entry point of the sample application. It initializes JDX ORM, calls testObjectModelSummary(), then runs useJDXORM():

testObjectModelSummary(): Calls jdxs.getObjectModelSummary() and logs the output — useful for verifying that the ORM mapping was loaded correctly.

useJDXORM() demonstrates the following sequence:

  1. Deep delete all existing A objects (cascades to associated B and C objects).
  2. Insert A with aId=1 — built from a raw JSONObject graph: A contains a JSONObject for B and a JSONArray of two C objects. Inserted with deep flag (true).
  3. Insert A with aId=2 — built similarly but with one B and no C objects.
  4. Insert A with aId=3 — built using JDX_JSONObject subclass instances (A, B) directly via put(), then wiring them together at the JSON level using b.getJSONObject(). Demonstrates the correct way to compose related JSON objects.
  5. Insert A with aId=4 — a standalone A with no B or C objects.
  6. Query all A, B, and C objects independently and print results.
  7. Update a C object (cId=1000) independently by modifying its underlying JSONObject.
  8. Retrieve A with aId=1 by object ID (deep) and verify the updated C value is reflected.
  9. Extract the underlying JSONObject from the retrieved A and log its JSON string representation — demonstrating how the object can be passed to other application layers or sent over a network.

sources.txt — Source File List

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

./src/com/softwaretree/jdxjson2example/model/A.java
./src/com/softwaretree/jdxjson2example/model/B.java
./src/com/softwaretree/jdxjson2example/model/C.java
./src/com/softwaretree/jdxjson2example/JSON2Example.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 (the org.json library, required for JSONObject and JSONArray 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 (json-20240303.jar), and the appropriate JDBC driver JAR. Edit this file to point to the correct JDBC driver for your database before running the application.

  • 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 JSON2Example 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/json2_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 forceCreateDatabase flag in JSON2Example.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