Skip to content

README.md

Latest commit

 

History

History
257 lines (182 loc) · 11.4 KB

README.md

File metadata and controls

257 lines (182 loc) · 11.4 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_RelationshipsExample

Overview

This project demonstrates how JDX ORM handles object models with one-to-one and one-to-many relationships between Java classes, and how those relationships are mapped declaratively to a relational database.

The domain model represents a small organizational structure:

  • A Company has many Departments (one-to-many, stored as a List) and many ForeignLocations (one-to-many, stored as an array).
  • An Employee belongs to a Department (many-to-one) and has one Address (one-to-one).

The example application demonstrates shallow and deep CRUD operations, lazy fetching of related objects, named queries, directed operations (selectively ignoring related objects during retrieval), and batch inserts — all using the JDX ORM API.

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_RelationshipsExample/
├── config/
│   └── relationships_example.jdx    # ORM mapping specification file
├── src/
│   └── com/softwaretree/jdxrelationshipsexample/
│       ├── RelationshipsExample.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 summarized below:

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)

Notes on IMPLICIT_ATTRIB

Two classes use the IMPLICIT_ATTRIB mapping feature, which allows JDX ORM to automatically manage foreign-key fields without explicit initialization in application code:

  • SimpleAddr.addrId — automatically initialized with the empId of the containing SimpleEmp when that employee is persisted.
  • SimpleEmp.deptId — automatically initialized with the deptId of the referenced SimpleDept when the employee is persisted.

Key Components

config/relationships_example.jdx — ORM Mapping File

This declarative file defines how the Java object model maps to relational database tables. It specifies:

  • JDX_DATABASE and JDBC_DRIVER — database connection and driver settings.
  • JDX_OBJECT_MODEL_PACKAGE — the base Java package for all model classes, allowing short class name references within the file.
  • CLASS / PRIMARY_KEY — each mapped class and its primary key.
  • RELATIONSHIP — one-to-one and one-to-many relationships, specified as BYVALUE (owned/deep) or by reference.
  • COLLECTION_CLASS — descriptors for collection-typed relationships (array and List), including element ordering.
  • IMPLICIT_ATTRIB — foreign-key fields automatically managed by JDX ORM.
  • RDBMS_GENERATED — marks locationId in SimpleForeignLocation as auto-generated by the database.
  • QUERY_NAME — a named parameterized query (GetEmpByTitle) defined on SimpleEmp for reuse in application code.

The file is pre-configured for SQLite. A commented-out MySQL example is also included. 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/.../RelationshipsExample.java — Main Application

The entry point of the sample application. It initializes JDX ORM and runs two phases:

Phase 1 — populateEmployees(): Sets up the database with sample data:

  • Deletes any pre-existing objects.
  • Inserts a SimpleCompany with two SimpleDept objects and two SimpleForeignLocation objects using a deep insert (persistence by reachability).
  • Inserts SimpleEmp objects with associated SimpleAddr objects, both individually and in batch.

Phase 2 — useJDXORM(): Demonstrates various query and update patterns:

  • Shallow query of a company, followed by lazy fetch of its foreign locations.
  • Deep query of a company (retrieves all related objects in one call).
  • Deep query of all employees.
  • getObjectById with shallow and deep flags.
  • Lazy fetch of a related object (address) from a shallowly retrieved employee.
  • Update of an employee and re-retrieval.
  • Named query (GetEmpByTitle) to retrieve employees filtered by title.
  • Directed operations — deep query while selectively ignoring the dept relationship, followed by an explicit access call to fetch it separately.

sources.txt — Source File List

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

./src/com/softwaretree/jdxrelationshipsexample/model/SimpleAddr.java
./src/com/softwaretree/jdxrelationshipsexample/model/SimpleCompany.java
./src/com/softwaretree/jdxrelationshipsexample/model/SimpleDept.java
./src/com/softwaretree/jdxrelationshipsexample/model/SimpleEmp.java
./src/com/softwaretree/jdxrelationshipsexample/model/SimpleForeignLocation.java
./src/com/softwaretree/jdxrelationshipsexample/RelationshipsExample.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 RelationshipsExample 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/relationships_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 RelationshipsExample.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