Skip to content

README.md

Latest commit

 

History

History
264 lines (180 loc) · 13 KB

README.md

File metadata and controls

264 lines (180 loc) · 13 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_PartialObjectLoadingExample

Overview

This project demonstrates Partial Object Loading — a JDX ORM feature that allows queries to retrieve only a specified subset of an object's attributes rather than all of them. This can significantly reduce data transfer and memory usage when only certain fields are needed from large or complex objects.

The domain model is the same organizational structure used in JDX_RelationshipsExample — a Company with Departments and ForeignLocations, and Employees each with a Department and an Address. This familiar model provides a rich set of attributes and relationships against which to demonstrate partial loading.

The key JDX ORM mechanism is the PROJECTED_ATTRIBUTES_HASHTABLE query detail, which lets the caller specify a HashMap mapping each class name to the list of attribute names to load for that class. Attributes not included in the projection are simply left at their default values in the returned objects (e.g., null for Strings, 0 for numerics) — no exception is thrown.

Additional query detail options demonstrated include:

  • QUALIFYING_PREDICATE — further filters which related objects are loaded (e.g., only addresses where city = 'San Jose').
  • IGNORE — skips loading a specific relationship entirely during a deep query (directed operations).
  • QFLAG_DUPLICATES_OK — a flag that may be needed alongside partial loading queries to avoid duplicate suppression issues.

Note: Partial object loading works with query() calls but not with getObjectById(). The README and source code both call this out explicitly.

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_PartialObjectLoadingExample/
├── config/
│   └── partialobjectloading_example.jdx  # ORM mapping specification file
├── src/
│   └── com/softwaretree/jdxpartialobjectloadingexample/
│       ├── PartialObjectLoadingExample.java  # Main application entry point
│       └── model/
│           ├── SimpleAddr.java           # Address model class
│           ├── SimpleCompany.java        # Company model class
│           ├── SimpleDept.java           # Department model class
│           ├── SimpleEmp.java            # Employee model class
│           └── SimpleForeignLocation.java  # Foreign location 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

The five model classes and their relationships are identical to those in JDX_RelationshipsExample:

Class Table Primary Key Relationships
SimpleCompany Simple_Company companyId Has many SimpleDept (List); has many SimpleForeignLocation (array)
SimpleDept Simple_Dept deptId Belongs to SimpleCompany via companyId
SimpleForeignLocation Simple_ForeignLocation locationId (auto-generated) Belongs to SimpleCompany via companyId
SimpleEmp Simple_Employee empId References SimpleDept via deptId; has one SimpleAddr
SimpleAddr Simple_Address addrId Belongs to SimpleEmp (addrId is an implicit attribute)

Key Components

config/partialobjectloading_example.jdx — ORM Mapping File

The mapping is identical in structure to JDX_RelationshipsExample, using the same mapping features: IMPLICIT_ATTRIB, RDBMS_GENERATED, BYVALUE relationships, COLLECTION_CLASS, QUERY_NAME, and REFERENCE_KEY. Key elements:

  • JDX_DATABASE and JDBC_DRIVER — pre-configured for SQLite; a commented-out MySQL example is also included.
  • JDX_OBJECT_MODEL_PACKAGE — the base Java package for all model classes.
  • RDBMS_GENERATED locationId on SimpleForeignLocation — auto-generated primary key (SQLite AUTOINCREMENT; MySQL AUTO_INCREMENT commented out).
  • IMPLICIT_ATTRIB addrId on SimpleAddr and IMPLICIT_ATTRIB deptId on SimpleEmp — foreign-key fields managed automatically by JDX ORM.
  • QUERY_NAME GetEmpByTitle on SimpleEmp — named parameterized query (defined but not used in the partial loading demonstrations).

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

The application runs two phases:

Phase 1 — populateEmployees(): Populates the database (same logic as JDX_RelationshipsExample):

  • Deletes existing employees and company objects within a transaction.
  • Inserts a SimpleCompany with two SimpleForeignLocation objects and two SimpleDept objects via a single deep insert.
  • Inserts three SimpleEmp objects (E1, E2, E3) with associated SimpleAddr objects.

Phase 2 — useJDXORM(): Demonstrates partial object loading:

  1. Standard shallow and deep queries for SimpleCompany C1 — baseline for comparison.

  2. Partial object loading — SimpleCompany (shallow): Loads only companyName, city, and state (not companyId). Uses PROJECTED_ATTRIBUTES_HASHTABLE with QFLAG_DUPLICATES_OK.

  3. Partial object loading — SimpleCompany (deep, without companyId): Same projection applied to a deep query — related SimpleDept and SimpleForeignLocation objects are loaded in full, but only the projected fields of SimpleCompany are populated.

  4. Partial object loading — SimpleCompany (deep, with companyId): Adds companyId to the projection list, enabling the deep query to correctly associate related objects.

  5. Standard deep query for all SimpleEmp objects — baseline for comparison.

  6. Partial object loading — SimpleEmp (deep): Loads only empId, empName, title, deptId from employees (omitting ssn and salary), and only addrId, city, state, country from addresses. Omitted fields are left at default values (null / 0).

  7. Partial loading with QUALIFYING_PREDICATE: Extends the employee partial query to additionally filter addresses by city = 'San Jose' — only employees whose address city matches are returned with their address loaded.

  8. getObjectById — partial loading not supported: Demonstrates that getObjectById ignores queryDetails and always loads all attributes; query() must be used instead for partial loading.

  9. Partial loading via query() for a single object: Uses query() with empId='E1' predicate and the partial loading queryDetails to retrieve one employee with selective field loading.

  10. Directed operation — IGNORE relationship: Combines partial attribute loading with the IGNORE option to perform a deep query that skips loading the dept relationship entirely, then verifying the result.

sources.txt — Source File List

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

./src/com/softwaretree/jdxpartialobjectloadingexample/model/SimpleForeignLocation.java
./src/com/softwaretree/jdxpartialobjectloadingexample/model/SimpleDept.java
./src/com/softwaretree/jdxpartialobjectloadingexample/model/SimpleCompany.java
./src/com/softwaretree/jdxpartialobjectloadingexample/model/SimpleAddr.java
./src/com/softwaretree/jdxpartialobjectloadingexample/model/SimpleEmp.java
./src/com/softwaretree/jdxpartialobjectloadingexample/PartialObjectLoadingExample.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 PartialObjectLoadingExample 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/partialobjectloading_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 PartialObjectLoadingExample.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