Jabel Documentation

For Gradle 6 or older, add jabel-javac-plugin as an annotationProcessor. You must configure the compileJava task to set sourceCompatibility (for IDE support) and use compilerArgs to set the --release 8 flag and the -Xplugin:jabel argument.

Note that on Java 14 and higher, the -Xplugin:jabel argument can be omitted. If using --enable-preview, you may need to filter it out of the arguments during the doFirst phase as shown in the example.

dependencies {
    annotationProcessor 'com.github.bsideup.jabel:jabel-javac-plugin:0.4.2'
}

// Add more tasks if needed, such as compileTestJava
configure([tasks.compileJava]) {
    sourceCompatibility = 14 // for the IDE support

    options.compilerArgs = [
            "--release", "8",
            '--enable-preview',
    ]

    doFirst {
        // Can be omitted on Java 14 and higher
        options.compilerArgs << '-Xplugin:jabel'

        options.compilerArgs = options.compilerArgs.findAll {
            it != '--enable-preview'
        }
    }
}

To use Jabel with Maven, you need to add jabel-javac-plugin as a dependency and configure the maven-compiler-plugin with the -Xplugin:jabel argument.

To ensure you don't accidentally use Java 9+ APIs, set the <release> configuration to 8. You should set <source> and <target> to the version of the modern syntax you are using (e.g., 14).

To verify installation, look for Jabel: initialized. in your Maven build output.

<dependencies>
    <dependency>
        <groupId>com.github.bsideup.jabel</groupId>
        <artifactId>jabel-javac-plugin</artifactId>
        <version>0.4.1</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.8.1</version>
            <configuration>
                <!-- Make sure we're not using Java 9+ APIs -->
                <release>8</release>
                <source>14</source>
                <target>14</target>
                <!-- The following setting can be avoided on Java 14 and higher -->
                <compilerArgs>
                    <arg>-Xplugin:jabel</arg>
                </compilerArgs>
            </configuration>
        </plugin>
    </plugins>
</build>

Gradle 7+ uses toolchains, making configuration straightforward. Add jabel-javac-plugin as both annotationProcessor and compileOnly. Set options.release = 8 and use javaToolchains to specify a higher Java version (e.g., 16) for the compiler.

If you want to force tests to run with a Java 8 runtime, configure the test task with a Java 8 launcher.

dependencies {
    annotationProcessor 'com.github.bsideup.jabel:jabel-javac-plugin:0.4.2'
    compileOnly 'com.github.bsideup.jabel:jabel-javac-plugin:0.4.2'
}

configure([tasks.compileJava]) {
    sourceCompatibility = 16 // for the IDE support
    options.release = 8

    javaCompiler = javaToolchains.compilerFor {
        languageVersion = JavaLanguageVersion.of(16)
    }
}

// Optional: Force tests to run with Java 8
compileTestJava {
    sourceCompatibility = targetCompatibility = 8
}

test {
    javaLauncher = javaToolchains.launcherFor {
        languageVersion = JavaLanguageVersion.of(8)
    }
}

Jabel allows you to write code using modern Java syntax (features from Java 9 through 14) even when your project's target compatibility is set to Java 8. The following features are demonstrated in the example code:

• Switch Expressions: Using switch as an expression with -> syntax and yield for multi-line blocks.
• Local Variable Type Inference (var): Using var for local variables and within lambda parameters.
• Pattern Matching for instanceof: Using if (obj instanceof Type variable) to perform type checks and binding in a single step.
• Nest-mates: Accessing private members of an outer class from an inner class.
• Project Coin features:
  • Using @SafeVarargs on private methods.
  • Using effectively final variables in try-with-resources blocks.
• Text Blocks: Using triple quotes (""") for multi-line string literals.

// Switch Expressions
var result = switch (args.length) {
    case 1 -> {
        yield """
                one...
                yet pretty long!
        """;
    }
    case 2, 3 -> "two or three";
    default -> "default value";
};

// Pattern Matching in instanceof
if (prefix instanceof String s) {
    return s + Integer.toString(0);
}

// Var in lambda parameter
Function<Object, String> function = (var prefix) -> {
    if (prefix instanceof String s) {
        return s;
    }
    return "";
};

// Effectively final variables in try-with-resources
var closeable = new AutoCloseable() {
    @Override
    public void close() {}
};
try (closeable) {
    // use closeable
}