Getting Started - Jukebox JavaFX Tutorial

Getting Started with the Jukebox Project

Welcome! This guide will help you set up your development environment and get the Jukebox project running on your computer.

Prerequisites

Before you can run the Jukebox project, you'll need:

Java Development Kit (JDK) 25+

The Jukebox project uses Java 25 and JavaFX 25. You need JDK 25 or later installed.

Check Your Java Version

Open a terminal/command prompt and run:

java -version

You should see output showing Java version 25 or higher.

An IDE (Integrated Development Environment)

We recommend IntelliJ IDEA Community Edition (free), but you can also use Eclipse or any other Java IDE.

Git (Optional)

If you want to clone the project from a repository, you'll need Git installed. However, since you already have the project files, this is optional.

Project Structure

The Jukebox project is organized as follows:

jukebox/
├── src/java/
│   ├── module-info.java          // Module configuration
│   ├── jukebox/
│   │   ├── Jukebox.java          // Main application class
│   │   ├── model/
│   │   │   ├── Album.java
│   │   │   ├── Database.java
│   │   │   ├── Genre.java
│   │   │   ├── Song.java
│   │   │   └── User.java
│   │   └── controller/
│   │       ├── AdminPanelController.java
│   │       ├── ApplicationWindowController.java
│   │       ├── ChooseAlbumController.java
│   │       ├── HomeScreenController.java
│   │       └── PlayAlbumController.java
│   └── resources/
│       ├── fxml/
│       │   ├── admin-panel-view.fxml
│       │   ├── application-window.fxml
│       │   ├── choose-album-view.fxml
│       │   ├── home-screen-view.fxml
│       │   └── play-album-view.fxml
│       └── styles/
│           └── application-window.css
├── lib/
│   ├── gson-2.14.0.jar          // Google Gson library for JSON
│   └── javafx-sdk-25.0.4/        // JavaFX SDK
├── database.json                // Application data file
└── README.md

Key Concepts:

src/java/ - Contains all Java source code
model/ - Data classes (Album, Song, etc.)
controller/ - Controller classes that manage views
resources/fxml/ - FXML files that define the UI layouts
lib/ - External libraries (JavaFX SDK and Gson)
database.json - Where application data is stored

Setting Up in IntelliJ IDEA

Follow these steps to open and configure the project in IntelliJ IDEA:

Open the Project

Launch IntelliJ IDEA
Click "File" > "Open" and select the jukebox folder
IntelliJ will recognize it as a Java project and start indexing the files

Configure Java SDK

If IntelliJ asks you to configure the JDK, click "Configure"
Select the JDK 25 installation on your computer
If you haven't installed JDK 25, download it from Oracle or Eclipse Temurin

Add JavaFX SDK as a Library

Go to "File" > "Project Structure" (Ctrl+Alt+Shift+S)
Click "Libraries" on the left side
Click the "+" button > "Java"
Navigate to lib/javafx-sdk-25.0.4/lib/ and select all JAR files
Click OK to add them as a library

Important: Make sure you select ALL JAR files in the lib/ folder of the JavaFX SDK.

Add Gson Library

In the same "Libraries" section, click the "+" button > "Java" again
Navigate to lib/gson-2.14.0/ and select gson-2.14.0.jar
Click OK to add it

Configure Module Settings

In "Project Structure", go to "Modules"
Make sure the JavaFX SDK library is in the "Dependencies" tab
If using modules, ensure the module path includes JavaFX

Configure Run Configuration

Click the dropdown next to the run button and select "Edit Configurations"
Click the "+" button and select "Application"
Configure as follows:
- Name: Jukebox
- Main class: jukebox.Jukebox
- JRE: JDK 25
- Working directory: The project root (jukebox)

Under "VM options", add:

--module-path lib/javafx-sdk-25.0.4/lib
--add-modules javafx.graphics,javafx.controls,javafx.fxml,java.desktop
--add-opens jukebox/jukebox.controller=javafx.fxml

Click OK to save

About VM Options:

--module-path - Tells Java where to find the JavaFX modules
--add-modules - Specifies which JavaFX modules to load
--add-opens - Required for FXML to access private fields in controllers

Running the Application

Start the Application

Make sure your run configuration is selected
Click the green "Run" button (or press Shift+F10)
The Jukebox application window should appear

Using the Application

The Jukebox has several views you can navigate through:

Home Screen: The starting screen with options to enter Play Mode or Admin Mode
Choose Album: Browse all albums in a table, select one to see its songs
Play Album: View and play songs from the selected album
Admin Panel: Add, edit, and delete albums and songs

Use the "GO HOME" button in the top-right to return to the home screen from any view.

Adding Data

Click "Admin Mode" from the home screen
Click "Add New Album" to create a new album
Select an album from the list
Click "Add New Song" to add songs to the album
Edit the album or song details in the text fields (they auto-save as you type)
Click "Save All" to persist your changes to database.json

Troubleshooting:

Application doesn't start: Check that your JDK is properly configured and the run configuration has the correct VM options.
FXML loading errors: Make sure the --add-opens VM option is correctly configured for the jukebox module.
Class not found errors: Verify that all JavaFX JAR files are added as libraries.
Gson errors: Ensure gson-2.14.0.jar is in your classpath.

Next Steps

Now that you have the project running, here's how to continue learning:

Try This Now

Open Jukebox.java in your IDE and trace through the code:

Find the main() method - this is where execution starts
Find the start() method - this is where JavaFX begins
Look at ApplicationWindowController.createViewInstance() - see how the main window is created
Notice the static fields at the top of Jukebox.java - these are used for communication between controllers