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_StreamingExample

Overview

This project demonstrates object streaming in JDX ORM — the ability to retrieve query results iteratively, a few objects at a time, rather than loading all matching objects into memory at once. This is particularly useful when querying large result sets where loading everything in a single call would be memory-intensive or slow.

The streaming API works as follows:

1. Open a stream — call query() with the JDXS.QFLAG_STREAM flag and an initialCount to retrieve the first batch of objects. The database cursor remains open.
2. Fetch subsequent batches — call queryFetch(fetchCount, ...) in a loop to retrieve the next fetchCount objects from the open cursor. Continue until queryResults.size() < fetchCount, indicating no more objects remain.
3. Close the stream — call queryClose() to close the database cursor.

Streaming queries must be performed within a transaction (tx_begin() / tx_commit()), as the database cursor must remain open across multiple fetch calls.

The example populates 15 Employee objects, then demonstrates two streaming scenarios:

• Stream all employees with an initial fetch of 5, followed by batches of 4.
• Stream a filtered, ordered subset (name > 'Doug' ORDER BY DOB) with the same batch sizes.

---

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_StreamingExample/
├── config/
│   └── streaming_example.jdx        # ORM mapping specification file
├── src/
│   └── com/softwaretree/jdxstreamingexample/
│       ├── StreamingExample.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	In thousands

All four non-DOB fields have their Java names remapped to different database column names via SQLMAP.

---

Key Components

config/streaming_example.jdx — ORM Mapping File

• JDX_DATABASE and JDBC_DRIVER — pre-configured for SQLite; a commented-out MySQL example is also included.
• CLASS ... Employee TABLE 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/.../StreamingExample.java — Main Application

The application runs two phases:

Phase 1 — populateDatabase(): Inserts 15 Employee objects using three different insertion strategies:

• Individual inserts — employees 1–9, each in its own implicit transaction.
• Batch with explicit transaction — employees 10–12 inserted one by one within a single tx_begin() / tx_commit() scope.
• Batch list insert — employees 13–15 inserted in a single jdxHandle.insert(list, ...) call.

Verifies the total count using getAggregate(AGGR_COUNT) after population.

Phase 2 — useJDXORM(): Demonstrates streaming in two scenarios:

Stream 1 — all employees:

1. Get total count with getAggregate(AGGR_COUNT).
2. tx_begin() — streaming requires an active transaction.
3. query(..., initialCount=5, QFLAG_STREAM, ...) — opens the stream and retrieves the first 5 objects.
4. Loop: queryFetch(fetchCount=4, ...) — fetches the next 4 objects per iteration until fewer than fetchCount are returned.
5. queryClose() then tx_commit() — closes the cursor and ends the transaction.

Stream 2 — filtered and ordered employees:

1. getAggregate(AGGR_COUNT, predicate="name > 'Doug'") — counts the qualifying subset.
2. Same tx_begin() → query(..., "name > 'Doug' ORDER BY DOB", initialCount=5, QFLAG_STREAM) → loop queryFetch(4) → queryClose() → tx_commit() pattern as above, with results ordered by DOB.

Important: A streaming query must always be closed with queryClose() before starting a new one. Failing to close an open stream will cause an error on the next streaming query.

---

sources.txt — Source File List

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

./src/com/softwaretree/jdxstreamingexample/model/Employee.java
./src/com/softwaretree/jdxstreamingexample/StreamingExample.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 StreamingExample 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/streaming_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 StreamingExample.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)