GRADLE-MIGRATION.md

Gradle Migration Documentation

Overview

This project has been migrated from Apache Maven to Gradle, utilizing the current stable release of Gradle (9.3.0). The migration maintains all functionality while adding enhanced capabilities for standalone application packaging.

Version Information

• Gradle Version: 9.3.0 (current stable release as of January 2026)
• Java Version: 21 (using Java Toolchain)
• Build Tool: Gradle with Wrapper (platform-independent)

Migration Details

Build Files Created

1. build.gradle.kts - Main build configuration file (replaces pom.xml)
2. settings.gradle.kts - Project settings and name configuration
3. gradlew / gradlew.bat - Gradle wrapper scripts for Unix/Windows
4. gradle/wrapper/ - Gradle wrapper JAR and properties

Dependencies Migrated

All Maven dependencies have been successfully migrated to Gradle format:

Dependency	Version	Scope	Notes
junit-jupiter-api	5.11.4	test	JUnit 5 API for writing tests
junit-jupiter-engine	5.11.4	testRuntime	JUnit 5 test execution engine
junit-platform-launcher	1.11.4	testRuntime	Required for Gradle 9.x JUnit integration
jqwik	1.9.2	test	Property-based testing framework

Plugins Configured

1. java - Core Java compilation and build support
2. application - Provides run task and application packaging
3. jacoco - Code coverage reporting (version 0.8.12)
4. shadow - Creates standalone executable fat JARs (version 9.3.1)

Build Configuration

Java Toolchain

The project uses Gradle's Java Toolchain feature to ensure Java 21 is used consistently:

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

Application Configuration

Main class is configured for execution:

application {
    mainClass = 'edu.luc.cs335.arrayqueue.SingleQueueService'
}

JUnit Platform Configuration

The test task is configured to use both JUnit Jupiter and jqwik test engines:

tasks.test {
    useJUnitPlatform {
        includeEngines("jqwik", "junit-jupiter")
    }
    finalizedBy(tasks.jacocoTestReport)
}

JaCoCo Coverage

Code coverage is configured to:

• Run automatically after tests
• Exclude SingleQueueService.java from coverage metrics (pedagogical reasons)
• Generate both XML and HTML reports
• Enforce coverage thresholds matching the Maven configuration:
  • INSTRUCTION: 90%
  • METHOD: 100%
  • BRANCH: 90%
  • COMPLEXITY: 90%
  • LINE: 90%
  • CLASS: 100%

Standalone Execution

Shadow Plugin Integration

The project now uses the Shadow plugin to create standalone executable JARs. This plugin:

• Bundles all dependencies into a single JAR file
• Configures the manifest with the correct main class
• Creates a "fat JAR" that can run anywhere with Java installed

Generated Artifact

Running ./gradlew shadowJar produces:

build/libs/arrayqueue-jqwik-1.0-SNAPSHOT-all.jar

This JAR can be executed standalone:

java -jar build/libs/arrayqueue-jqwik-1.0-SNAPSHOT-all.jar [args...]

Command Reference

Maven vs Gradle Command Mapping

Maven Command	Gradle Equivalent	Description
mvn clean	./gradlew clean	Clean build artifacts
mvn compile	./gradlew compileJava	Compile source code
mvn test	./gradlew test	Run tests (including jqwik)
mvn package	./gradlew build or ./gradlew package	Build project
mvn verify	./gradlew check	Run verification tasks (includes coverage check)
mvn exec:java	./gradlew run or ./gradlew exec	Execute main class
N/A	./gradlew shadowJar	Create standalone fat JAR

Common Gradle Commands

Build Commands

# Clean and build the project
./gradlew clean build

# Build without tests
./gradlew build -x test

# Create standalone JAR
./gradlew shadowJar

# Alias for shadowJar (Maven-style)
./gradlew package

Execution Commands

# Run the application
./gradlew run

# Run with arguments
./gradlew run --args="arg1 arg2 arg3"

# Alias for run (Maven-style)
./gradlew exec

Testing Commands

# Run all tests (JUnit and jqwik)
./gradlew test

# Run tests with coverage report
./gradlew test jacocoTestReport

# Run tests with coverage verification
./gradlew check

# Run specific test class
./gradlew test --tests TestSimpleQueue

# Run tests continuously (on file changes)
./gradlew test --continuous

Dependency Commands

# View dependency tree
./gradlew dependencies

# View test dependencies only
./gradlew dependencies --configuration testRuntimeClasspath

# Check for dependency updates
./gradlew dependencyUpdates

Information Commands

# List all tasks
./gradlew tasks

# List all tasks including detailed descriptions
./gradlew tasks --all

# View project properties
./gradlew properties

Project Structure

The source directory structure remains unchanged from Maven:

arrayqueue-jqwik-maven/
├── build.gradle.kts          # Gradle build configuration
├── settings.gradle.kts        # Gradle project settings
├── gradlew                    # Unix Gradle wrapper script
├── gradlew.bat               # Windows Gradle wrapper script
├── gradle/
│   └── wrapper/
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── src/
│   ├── main/
│   │   └── java/
│   │       └── edu/
│   │           └── luc/
│   │               └── cs335/
│   │                   └── arrayqueue/
│   │                       ├── FixedArrayQueue.java
│   │                       ├── SimpleQueue.java
│   │                       └── SingleQueueService.java
│   └── test/
│       └── java/
│           └── edu/
│               └── luc/
│                   └── cs335/
│                       └── arrayqueue/
│                           ├── TestSimpleQueue.java
│                           └── TestSimpleQueueJqwik.java
└── build/                    # Gradle build output (gitignored)
    ├── classes/
    ├── libs/                 # Contains generated JARs
    ├── reports/              # Test and coverage reports
    └── test-results/

Build Output Locations

Artifact Type	Maven Location	Gradle Location
Compiled classes	target/classes/	build/classes/java/main/
Test classes	target/test-classes/	build/classes/java/test/
JAR files	target/*.jar	build/libs/*.jar
Test reports	target/surefire-reports/	build/reports/tests/test/
Coverage reports	target/site/jacoco/	build/reports/jacoco/test/

Advanced Features

Configuration Cache

Gradle 9.x supports configuration cache for faster builds. Enable it by adding to gradle.properties:

org.gradle.configuration-cache=true

Build Scans

Generate detailed build analysis:

./gradlew build --scan

Parallel Execution

Enable parallel test execution in build.gradle.kts:

test {
    maxParallelForks = Runtime.runtime.availableProcessors().intdiv(2) ?: 1
}

Custom Tasks

Two alias tasks have been added for Maven users:

• package - Calls shadowJar (Maven-style packaging)
• exec - Calls run (Maven-style execution)

Migration Benefits

1. Faster Builds: Gradle's incremental compilation and build cache
2. Better Dependency Management: Transitive dependency resolution
3. Flexible Scripting: Kotlin DSL for complex build logic
4. Rich Plugin Ecosystem: Easy integration of new build tools
5. Standalone Packaging: Built-in support for fat JAR creation
6. Modern Tooling: Active development and Java 21+ support
7. jqwik Integration: Native support for property-based testing

Troubleshooting

Gradle Daemon Issues

# Stop all Gradle daemons
./gradlew --stop

# Check daemon status
./gradlew --status

Clean Build

# Force clean build
./gradlew clean build --no-build-cache

Wrapper Update

# Update to latest Gradle version
./gradlew wrapper --gradle-version=9.3.0

Dependency Conflicts

# View dependency insight
./gradlew dependencyInsight --dependency junit-jupiter

jqwik Tests Not Running

If jqwik tests aren't being discovered, verify that:

1. The test task includes the jqwik engine: includeEngines("jqwik", "junit-jupiter")
2. Test classes are annotated with @Property or other jqwik annotations
3. The jqwik dependency is in the testImplementation configuration

Compatibility Notes

• Java 21: Required by project configuration
• Gradle 9.3.0: Uses Shadow plugin 9.3.1 for compatibility
• JUnit 5: Platform launcher explicitly included for Gradle 9.x
• jqwik 1.9.2: Full property-based testing support
• IDE Support: Works with IntelliJ IDEA, Eclipse, VS Code with Gradle extensions

References

• Gradle Documentation
• Shadow Plugin
• Gradle Java Plugin
• Gradle Application Plugin
• JUnit 5 User Guide
• jqwik Documentation