Migrate your existing codebase to JDeli

Making the switch to a new image library can feel daunting. Will you need to rewrite thousands of lines of code? How long will the migration take? What if something breaks in production?

The good news? Migrating to JDeli doesn’t have to be complicated. In fact, depending on your needs, you might not need to change any code at all.

Whether you’re looking to improve performance, add support for modern formats like HEIC and JPEG XL, or eliminate troublesome native dependencies, JDeli offers flexible migration paths that fit your timeline and requirements.

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 maximum performance

Let’s explore both options so you can choose the one that’s right for your project.

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

If you’re using Java’s standard ImageIO API and want the smoothest possible migration, the JDeli ImageIO plugin is your answer. 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'
}

That’s it! Your existing code continues to work exactly as before:

// 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)

When to Use the ImageIO Plugin

This approach is ideal when:

• You have a large existing codebase using ImageIO
• You need to migrate quickly with minimal risk
• You’re working with legacy code that can’t easily be refactored
• You want to drop in JDeli as a performance upgrade without code review overhead

Approach 2: Direct API Migration

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

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.

Basic Migration Pattern

The migration 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)
);

When to Use the Direct API

Choose the direct API approach when:

• You’re starting a new project
• You need fine-grained control over encoding parameters
• You want to leverage image processing operations
• Performance optimization is critical
• You’re refactoring anyway and want to modernize your codebase

Choosing the Right Approach

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:

Pro tip: You can even use both approaches in the same project! Use the plugin for legacy modules while adopting the direct API for new features.

What You’ll Gain

Regardless of which approach you choose, migrating to JDeli delivers:

• Faster performance - Up to 3x speed improvements over standard ImageIO
• Modern format support - HEIC, JPEG XL, WebP, and more
• Pure Java - No native dependencies to manage or debug
• No JVM crashes - Eliminates segmentation faults from native libraries
• Better JPEG, PNG, and TIFF handling - Enhanced support for edge cases
• Single JAR deployment - No DLL/SO/dylib headaches
• Enterprise support - Direct access to JDeli developers

Getting Started

Ready to migrate? Here’s your action plan:

1. Download a free trial at www.idrsolutions.com/jdeli/trial-download
2. Choose your approach based on your project needs
3. Run your test suite - JDeli is designed to be a drop-in replacement
4. Measure the improvement - Benchmark your image operations
5. Deploy with confidence - Join companies already using JDeli in production

Have questions about your specific migration scenario? Our development team is here to help. Contact us or check out our comprehensive documentation to get started.

Common Migration 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 behavior 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.

Conclusion

Migrating to JDeli doesn’t have to be a major undertaking. Whether you choose the zero-code-change plugin approach or the feature-rich direct API, you’re just minutes away from faster image processing, better format support, and a more reliable Java image library.

The hardest part? Deciding which approach fits your project best. The actual migration? That’s the easy part.

Start your free trial today and see how simple the migration really is.

Sign up for JDeli Trial →