Migrate your existing codebase to JDeli

This guide shows how you can use your existing Java codebase with no or minimal changes to make use of JDeli

Two Paths to Migration

JDeli provides two distinct approaches for migrating your existing Java image processing code:

1. The ImageIO Plugin Approach - Zero code changes required
2. The Direct API Approach - Full control and enhanced API

Approach 1: ImageIO Plugin (The Zero-Refactoring Path)

This approach allows you to immediately benefit from JDeli’s performance and format support without touching a single line of your existing code.

How It Works

The ImageIO plugin registers JDeli as a service provider for ImageIO. When your code calls ImageIO.read() or ImageIO.write(), Java automatically routes those calls to JDeli’s implementation instead of the default handlers.

Setup Steps

For Maven projects:

<dependency>
    <groupId>com.idrsolutions</groupId>
    <artifactId>jdeli-imageio</artifactId>
    <version>3.0</version>
</dependency>

For Gradle projects:

dependencies {
    implementation 'com.idrsolutions:jdeli-imageio:3.0'
}

Existing code will continue to work exactly as before but now using JDeli.

// Your existing code - no changes needed!
BufferedImage image = ImageIO.read(new File("photo.heic"));
ImageIO.write(image, "jpeg", new File("output.jpg"));

Optional: Registering Additional Formats

By default, the plugin registers AVIF and HEIC support. If you want to enable JDeli for all supported formats, add this initialization code:

import com.idrsolutions.image.imageio.ImageIOSupport;
import com.idrsolutions.image.utility.InputFormat;
import com.idrsolutions.image.utility.OutputFormat;

// Register all supported formats
ImageIOSupport.registerReaders(InputFormat.values());
ImageIOSupport.registerWriters(OutputFormat.values());
// Register a supported format
ImageIOSupport.registerReader(InputFormat.BMP)
ImageIOSupport.registerWriter(OutputFormat.BMP)

// Unregister a supported format
ImageIOSupport.unregisterReader(InputFormat.HEIC)
ImageIOSupport.unregisterWriter(OutputFormat.HEIC)

Approach 2: Direct API Migration

For developers who want maximum control, performance optimization, and access to JDeli’s advanced features, the direct JDeli API is available.

Installation

First, add JDeli to your project. The library is distributed as a single JAR file with no external dependencies.

For Maven (requires credentials from your trial or license):

<dependencies>
    <dependency>
        <groupId>com.idrsolutions</groupId>
        <artifactId>jdeli</artifactId>
        <version>1.0</version>
    </dependency>
</dependencies>

For Gradle:

dependencies {
    implementation 'com.idrsolutions:jdeli:1.0'
}

Alternatively, you can add the JAR file directly to your classpath.

How to switch from ImageIO to the JDeli API

Switching is straightforward - JDeli’s API mirrors ImageIO’s simplicity:

Before (ImageIO):

import javax.imageio.ImageIO;
import java.awt.image.BufferedImage;
import java.io.File;

BufferedImage image = ImageIO.read(new File("input.jpg"));
ImageIO.write(image, "png", new File("output.png"));

After (JDeli):

import com.idrsolutions.image.JDeli;
import java.awt.image.BufferedImage;
import java.io.File;

BufferedImage image = JDeli.read(new File("input.jpg"));
JDeli.write(image, "png", new File("output.png"));

Advanced Features with Direct API

The direct API gives you access to powerful features that aren’t available through ImageIO:

1. Type-Safe Format Specification:

import com.idrsolutions.image.utility.OutputFormat;

BufferedImage image = JDeli.read(new File("photo.heic"));
JDeli.write(image, OutputFormat.PNG, new File("output.png"));

2. Custom Encoder Options:

import com.idrsolutions.image.jpeg.options.JpegEncoderOptions;

BufferedImage image = JDeli.read(inputFile);

JpegEncoderOptions options = new JpegEncoderOptions();
options.setQuality(95);

JDeli.write(image, options, new File("high-quality.jpg"));

3. Chained Image Processing:

import com.idrsolutions.image.processing.ImageProcessingOperations;

BufferedImage image = JDeli.read(inputFile);

ImageProcessingOperations operations = new ImageProcessingOperations()
    .scale(0.5)
    .rotate(90)
    .blur();

BufferedImage processed = operations.apply(image);
JDeli.write(processed, "jpeg", outputFile);

4. One-Step Conversion:

// Convert and process in a single operation
JDeli.convert(
    new File("input.tiff"),
    new File("output.webp"),
    new ImageProcessingOperations().scale(0.75)
);

Comparison of using Plugin versus JDeli API

Both migration paths use the same high-performance JDeli core library, so you get the same speed improvements and format support either way. Here’s a quick decision matrix:

Frequently Asked Questions

Q: Can I migrate gradually?
Yes! Both approaches work side-by-side. Start with the plugin for existing code and use the direct API for new features.

Q: Will my existing tests still pass?
In most cases, yes. JDeli is designed to be compatible with ImageIO while adding improvements.

Q: What if I encounter issues?
JDeli customers get direct support from our developers, with rapid responses and often fixes into the daily builds within days.

Q: Is the migration reversible?
Absolutely. With the plugin approach, you can simply remove the dependency. With the direct API, the changes are minimal and straightforward to revert if needed.