Skip to content

README.md

Latest commit

 

History

History
252 lines (174 loc) · 11.6 KB

README.md

File metadata and controls

252 lines (174 loc) · 11.6 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_MySQL_SakilaExample

Overview

This project demonstrates how JDX ORM can work with an existing database schema — specifically the MySQL Sakila sample database — without creating or modifying any tables. The model classes and ORM mapping are defined manually based on an understanding of the existing schema, allowing JDX ORM to read and query data from Sakila's tables in an object-oriented way.

This example is complementary to JDX_ReverseEngineeringExample and JDX_ReverseEngineeringJSONExample, which automate the generation of classes and mapping from existing schemas. Here, the classes and mapping are hand-authored to demonstrate the relationships more explicitly.

The domain model covers a subset of the Sakila schema:

  • Film has a one-to-one relationship with Film_Text (the film's full-text search index entry).
  • Film has a many-to-many relationship with Actor through the join table film_actor, represented by the join class Film_Actor.
  • From the Film side: Film has a List actors collection of Actor objects.
  • From the Actor side: Actor has a List films collection of Film objects.

Important: Since this application works with the existing Sakila database, forceCreateSchema is set to false in main() to prevent JDX from dropping or recreating existing tables. However, JDX requires a JDXMetadata table to be present; if it doesn't exist, JDX may attempt to treat the database as fresh. See the Getting Started section for the required DDL.

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.
  • MySQL with the Sakila sample database installed and populated. See https://dev.mysql.com/doc/sakila/en/ for installation instructions.
  • The JDXMetadata table created in the Sakila database (see Getting Started below).

Project Structure

JDX_MySQL_SakilaExample/
├── config/
│   └── mysql_sakila_example.jdx     # ORM mapping specification file
├── src/
│   └── com/softwaretree/jdxmysqlsakilaexample/
│       ├── MySQLSakilaExample.java   # Main application entry point
│       └── model/
│           ├── Actor.java            # Actor model class
│           ├── Film.java             # Film model class
│           ├── Film_Actor.java       # Join class (Film ↔ Actor)
│           └── Film_Text.java        # Film full-text 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
├── JDXDemo.bat                       # Windows: launch the JDXDemo GUI application
├── JDXDemo.sh                        # Mac/Linux: launch the JDXDemo GUI application
└── README.md                         # This file

Domain Model

Class Design

All model classes use public fields (no private fields with getters/setters), reflecting the pattern typically generated by the JDX reverse engineering tool.

Class Table Primary Key Relationships
Film film film_id One Film_Text (BYVALUE); many Actor via Film_Actor
Film_Text film_text film_id Belongs to Film
Film_Actor film_actor actor_id + film_id Join class linking Film and Actor
Actor actor actor_id Many Film via Film_Actor

Film fields

film_id (short), title, description, release_year (Date), language_id (short), original_language_id (short), rental_duration (short), rental_rate (BigDecimal), length (short), replacement_cost (BigDecimal), rating, special_features, last_update (Timestamp), filmText (Film_Text), actors (List of Actor via join).

Actor fields

actor_id (short), first_name, last_name, last_update (Timestamp), films (List of Film via join).

Film_Text fields

film_id (short), title, description.

Film_Actor fields

film_id (short), actor_id (short), last_update (Timestamp). Composite primary key.

Key Components

config/mysql_sakila_example.jdx — ORM Mapping File

Maps four classes to existing Sakila tables and declares two JOIN_COLLECTION_CLASS descriptors for the bidirectional many-to-many relationship. Key elements:

  • JDX_DATABASE and JDBC_DRIVER — configured for MySQL Sakila. Update with your local credentials.
  • JDX_OBJECT_MODEL_PACKAGE — base package for all model classes.
  • CLASS .Film TABLE film — declares RELATIONSHIP filmText REFERENCES .Film_Text BYVALUE WITH film_id (one-to-one) and RELATIONSHIP actors REFERENCES ListFilmActors WITH film_id (many-to-many via join). Multiple SQLMAP NULLABLE entries cover optional columns.
  • CLASS .Film_Text TABLE film_text — simple class with nullable description.
  • CLASS .Film_Actor TABLE film_actor — join class with composite PRIMARY_KEY actor_id film_id.
  • JOIN_COLLECTION_CLASS ListActorFilms — collection of Film objects for a given Actor, traversed through Film_Actor, keyed by actor_id, join key film_id, ordered by title.
  • CLASS .Actor TABLE actor — declares RELATIONSHIP films REFERENCES ListActorFilms WITH actor_id.
  • JOIN_COLLECTION_CLASS ListFilmActors — collection of Actor objects for a given Film, traversed through Film_Actor, keyed by film_id, join key actor_id, ordered by last_name.

Refer to the JDX Database & JDBC Driver Specification Guide for configuring other databases.

Note: Update JDX_DATABASE credentials to match your local MySQL setup before running.

src/.../MySQLSakilaExample.java — Main Application

The application sets forceCreateSchema = false to avoid modifying the existing Sakila tables. It demonstrates:

  1. Shallow query for Film with film_id=1 — retrieves scalar fields only; filmText and actors are null.
  2. Lazy fetch of filmText — calls jdxHandle.access(film, "filmText", ...) to retrieve the Film_Text object for the shallowly loaded film.
  3. Deep query for Film with film_id=1 — retrieves the film along with its Film_Text and full list of associated Actor objects through the join table.
  4. Deep query for Actor objects — retrieves a maximum of 2 Actor objects ordered by first_name, last_name, each with their associated Film objects through the join table.

sources.txt — Source File List

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

./src/com/softwaretree/jdxmysqlsakilaexample/model/Film_Text.java
./src/com/softwaretree/jdxmysqlsakilaexample/model/Film_Actor.java
./src/com/softwaretree/jdxmysqlsakilaexample/model/Film.java
./src/com/softwaretree/jdxmysqlsakilaexample/model/Actor.java
./src/com/softwaretree/jdxmysqlsakilaexample/MySQLSakilaExample.java

Film_Text and Film_Actor are listed first as they have no dependencies on the other model classes.

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 MySQL JDBC driver JAR. Edit this file to point to the correct JDBC driver version for your setup.

  • 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 MySQLSakilaExample main class.

Windows:

runJDXExample.bat

Mac/Linux:

chmod +x runJDXExample.sh   # first time only
./runJDXExample.sh

JDXDemo.bat / JDXDemo.sh — JDXDemo GUI

Launches the JDXDemo desktop GUI application to interactively browse the Sakila film, actor, film_actor, and film_text tables using the JDX ORM configuration.

Windows:

JDXDemo.bat

Mac/Linux:

chmod +x JDXDemo.sh   # first time only
./JDXDemo.sh

Getting Started

  1. Install the MySQL Sakila sample database if not already present. See https://dev.mysql.com/doc/sakila/en/.

  2. Create the JDXMetadata table in the Sakila database to prevent JDX from treating it as a fresh database:

    CREATE TABLE IF NOT EXISTS JDXMetadata (
    jdxORMId TEXT,
    jdxTimestamp TEXT,
    jdxMetaVersionId TEXT,
    jdxMetaFileName TEXT,
    jdxMetaInfo TEXT
);

  3. Configure the database by editing config/mysql_sakila_example.jdx:

    • Update JDX_DATABASE with the correct MySQL connection URL and credentials.
    • Update setEnvironment.bat (Windows) or setEnvironment.sh (Mac/Linux) if using a different JDBC driver version.

  4. Compile the source files:

    compile.cmd          # Windows
./compile.sh         # Mac/Linux

  5. Run the sample application:

    runJDXExample.bat    # Windows
./runJDXExample.sh   # Mac/Linux

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