JAG - Java Application for Gmail

A desktop email client with a JavaFX GUI. It sends, receives, organizes and stores emails (including attachments) using a MySQL database.

Term project for the fall 2018 420-510-DW (Programming V) course at Dawson College.

Table of Contents

• Tech Stack
• Project History
• How to Run
• Usage
• What I Learned

Tech Stack

• Java 17 (originally Java 8) and JavaFX 21
• Maven for builds and dependency management
• MySQL for persistence
• JUnit for unit tests
• Docker and Docker Compose for a reproducible build and database

Project History

The repository keeps three snapshots of the project, so you can see how it evolved:

Stage	Commit	Description
Original	340a337	The project as it was submitted in 2018.
Minimal changes	main	The smallest set of changes needed to build and run it today.

How to Run

Prerequisites

• Docker with Docker Compose
• Java 17 or later (JavaFX is bundled in the jar, so no separate install is needed)
• A Gmail account with an App password

1. Start the database

docker compose up -d

2. Build the jar

DOCKER_BUILDKIT=1 docker build --target artifact --output type=local,dest=./dist .

This produces dist/jag.jar, a large jar that runs on all platforms. To get a smaller jar for one platform, pass it as a build argument:

DOCKER_BUILDKIT=1 docker build --build-arg PLATFORM=<platform> --target artifact --output type=local,dest=./dist .

where <platform> is linux, linux-aarch64, win, mac or mac-aarch64. A single-platform jar only runs on that platform.

Tests are skipped by default. To run them during the build, add --build-arg SKIP_TESTS=false. The tests need a database connection, so run them on your machine with mvn test while the database is up.

3. Configure

Rename config.properties.template to config.properties and fill in your values, including your Gmail App password. If config.properties is missing, the program opens the Configuration module on startup instead of the main module.

4. Run

java -jar dist/jag.jar

Usage

Main Module

Email Tree View

The right part of the main module. Available actions:

1. Right-click an email to reply, reply-all, forward, or delete it.
2. Drag an email to move it to another folder.
3. Right-click a folder to delete it and all of its contents.

Email Display View

The left part of the main module. It shows the currently focused email. Click an attachment to download it.

Top Bar

From the top bar you can:

1. Create a new email.
2. Open the Configuration module.

Email Composition Module

• Edit the To, Cc, and Bcc fields by clicking on them, and write the message body in the lower text area.
• To attach or detach files, use the top bar.
• When you're done, choose File → Send. The email is validated, and a popup confirms if it was sent successfully.

Configuration Module

Enter new values for the credentials used throughout the program.

• OK validates the input and saves it to the configuration file.
• Cancel leaves the configuration file unchanged.

What I Learned

Build systems with Maven

• Declaring dependencies and managing versions through the pom.xml.
• Following the standard project layout and build lifecycle (compile, test, package).
• Packaging an application and its dependencies into a single runnable jar.

GUI programming with JavaFX

• Building user interfaces with scenes, layouts and controls.
• Handling user events such as clicks, context menus and drag and drop.
• Opening and coordinating multiple windows (main, composition and configuration).

Data access with DAOs and data beans

• Representing emails, folders and attachments as plain data beans.
• Isolating all database code in DAO classes, so the rest of the application never touches SQL.
• Working with JDBC to read and write data in a relational database.

The MVC pattern

• Separating the data (model), the screens (view) and the logic connecting them (controller).
• Keeping each layer small and focused, which makes the code easier to change and test.

Unit testing with JUnit

• Writing repeatable tests for the DAO and data layers.
• Setting up a known database state before each test using SQL scripts.
• Understanding which tests need external resources (a database) and which don't.