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_SequenceExample

Overview

This project demonstrates how JDX ORM supports named sequence generators for creating persistently unique sequence numbers across multiple invocations of an application.

Named sequences are defined declaratively in the ORM mapping file and accessed in application code via the JDXSeqUtil utility class. This allows JDX to automatically generate and assign unique primary key values to new model objects in a controlled and persistent way — meaning sequence counters survive application restarts and continue from where they left off.

The domain model is a simple organizational structure consisting of Departments and Employees, where unique IDs for both are generated using named sequences (DeptIdSequence and EmpIdSequence) rather than being hard-coded or database-auto-incremented.

---

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_SequenceExample/
├── config/
│   └── sequence_example.jdx         # ORM mapping specification file
├── src/
│   └── com/softwaretree/jdxsequenceexample/
│       ├── SequenceExample.java      # Main application entry point
│       └── model/
│           ├── Department.java       # Department model class
│           └── 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

Class	Table	Primary Key	Relationships
Department	Dept	deptId (String)	None
Employee	Emp	empId (int)	References Department via deptId

Both primary keys are assigned using JDX named sequence generators rather than hard-coded values or database auto-increment.

---

Key Components

config/sequence_example.jdx — ORM Mapping File

This declarative file defines the object-to-table mappings and the named sequence generators. Key elements:

• JDX_DATABASE and JDBC_DRIVER — database connection and driver settings. Pre-configured for MySQL; a commented-out SQLite example is also included.

• CLASS / PRIMARY_KEY / RELATIONSHIP — standard class mappings. Employee references Department via deptId.

• SEQUENCE — defines named sequence generators:

  Sequence Name	MAX_INCREMENT	START_WITH	Description
  EmpIdSequence	10	100	Generates employee IDs starting at 100
  DeptIdSequence	5	(default)	Generates department ID sequence numbers

  MAX_INCREMENT controls how many sequence numbers JDX reserves at once from the database, reducing round-trips. START_WITH sets the initial value of the sequence counter.

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/Department.java and Employee.java — Domain Model Classes

Two simple POJOs:

• Department — has deptId (String) and deptName (String).
• Employee — has empId (int), empName, title, deptId (String), and a dept reference to a Department object.

Both include a no-arg default constructor as required by JDX ORM.

---

src/.../SequenceExample.java — Main Application

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

1. Delete all existing Employee and Department objects from the database.
2. Create a JDXSeqUtil for DeptIdSequence and call getNextSeq() to obtain a unique department ID, then construct a Department with ID "DEPT_<seq>" and insert it.
3. Create a JDXSeqUtil for EmpIdSequence (with a pre-fetch batch size of 3) and insert five Employee objects, each using getNextSeq() for their empId.
4. Query all employees with a shallow query and print results.
5. Retrieve a specific employee (Charlie) by object ID using a deep query.
6. Query all departments and print results.

Important note from the code: JDXSeqUtil.getNextSeq() may internally use a new database transaction to persist the next batch of sequence numbers. It must therefore not be called from within an active JXSession transaction scope (i.e., between tx_begin() and tx_commit()). This is particularly relevant on Android, which has limitations on concurrent transactions.

---

sources.txt — Source File List

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

./src/com/softwaretree/jdxsequenceexample/model/Department.java
./src/com/softwaretree/jdxsequenceexample/model/Employee.java
./src/com/softwaretree/jdxsequenceexample/SequenceExample.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 for your database. 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 SequenceExample 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/sequence_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 SequenceExample.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)