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_Simple2Example

Overview

This project demonstrates CRUD (Create, Read, Update, Delete) operations on a simple Employee domain model class using JDX ORM, with a specific focus on contrasting two API styles for interacting with the database:

• JDXSetup / JDXS (lower-level API) — the application checks out a JXResource, obtains a JDXS handle, performs operations directly, and checks the resource back in. This style gives more control and is closer to the underlying JDX ORM mechanics.
• JDXHelper (higher-level API) — a convenience wrapper that handles resource checkout/checkin automatically, providing a simpler and more concise coding style for common operations.

Both useJDXORM1() (uses JDXSetup/JDXS) and useJDXORM2() (uses JDXHelper) perform exactly the same sequence of operations, making it easy to compare the two styles side by side.

A notable feature demonstrated here is update2() — a JDX API call that updates specific attributes of multiple objects matching a predicate in a single call, without loading the objects into memory first.

---

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_Simple2Example/
├── config/
│   └── simple2_example.jdx          # ORM mapping specification file
├── src/
│   └── com/softwaretree/jdxsimple2example/
│       ├── Simple2Example.java       # Main application entry point
│       └── model/
│           └── Employee.java         # 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

Employee

Field	Type	DB Column	Notes
id	int	EmpId	Primary key
name	String	EmpName
DOB	Date	DOB
exempt	boolean	Exempt
compensation	float	Salary

Four fields have their Java names remapped to different database column names via SQLMAP. Note that Employee in this example uses the class name as the table name (no explicit TABLE directive in the mapping), so the table name defaults to Employee.

---

Key Components

config/simple2_example.jdx — ORM Mapping File

• JDX_DATABASE and JDBC_DRIVER — pre-configured for SQLite; a commented-out MySQL example is also included.
• CLASS ... Employee with PRIMARY_KEY id.
• SQLMAP entries remap id → EmpId, name → EmpName, exempt → Exempt, compensation → Salary.

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

The application runs two phases that perform identical operations using different API styles:

Phase 1 — useJDXORM1() (lower-level JDXSetup/JDXS style):

1. Check out a JXResource; obtain JDXS jdxHandle.
2. Delete all existing employees; verify count with getAggregate(AGGR_COUNT).
3. Insert Mark (id=1) and Bill (id=2).
4. Query all employees; query with predicate compensation < 52000.
5. update2(employeeClassName, "id < 5", newValues, 0) — updates compensation=77777 and exempt=true for all employees with id < 5, without loading them into objects. Returns the count of updated rows.
6. Query employees with id < 5 to confirm the bulk update.
7. getObjectById for Bill (id=2); update his exempt and compensation individually; re-retrieve to confirm.
8. Delete Bill; query remaining; delete remaining via jdxHandle.delete(list, ...).
9. Check in the JXResource.

Phase 2 — useJDXORM2() (higher-level JDXHelper style): Performs the exact same sequence as Phase 1, but using JDXHelper convenience methods — jdxHelper.delete2(), jdxHelper.getObjectCount(), jdxHelper.insert(), jdxHelper.getObjects(), jdxHelper.update2(), jdxHelper.getObjectById(), jdxHelper.update(), jdxHelper.delete(). No explicit JXResource checkout/checkin is needed; JDXHelper handles that internally.

The key difference: useJDXORM1() requires manual resource lifecycle management; useJDXORM2() is more concise but provides less direct control.

---

sources.txt — Source File List

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

./src/com/softwaretree/jdxsimple2example/model/Employee.java
./src/com/softwaretree/jdxsimple2example/Simple2Example.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 (JSON 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 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 Simple2Example 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/simple2_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 Simple2Example.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)