Upgrading Java Applications from APDFL 18 to APDFL 21
Estimated Reading Time: 3 Minutes## Overview
Upgrading Adobe PDF Library (APDFL) Java applications to v21 involves updating Java, dependency versions, and the package repository. The Java package `com.datalogics.PDFL` and Maven coordinates `com.datalogics.pdfl:pdfl` remain unchanged. Existing APDFL calls can generally be retained.
APDFL v21 uses Adobe's v21 core and includes improvements to PDF processing, fonts, and document conversion. Fro more information, refer to APDFL v21 Release Notes.
Before You Begin
Plan for **JDK 17 or later**. The APDFL 21.0.1 classes examined for this migration use Java 17 bytecode, so Java 8 and Java 11 cannot load them.
Verify the Java version used by your IDE, Maven, build server, and deployment service. Updating a developer workstation alone does not update the production runtime. Where practical, first verify your existing application on the newer JDK with APDFL v18 still referenced.
Also confirm that the selected native package matches the JVM's operating system and architecture. Public v21 Maven packages are License-Managed; non-License-Managed customers should obtain their packages through their Datalogics distribution channel. Older installer-based Java integrations need to move to the packaged Java distribution.
Update the Application
1. Update the Java Build Configuration
Configure your build for Java 17 or later. For example, existing Maven compiler properties can be updated to:
```xml
<properties>
<maven.compiler.source>17</maven.compiler.source>
<maven.compiler.target>17</maven.compiler.target>
</properties>
```
Confirm that `JAVA_HOME` and the Java installation reported by `mvn -version` point to the intended JDK.
2. Configure the Package Repository
Starting with package 21.1.0, new Java releases are published to the Datalogics Maven repository. Previously published versions remain on Maven Central.
Add the following inside your project's `pom.xml` `<project>` element, merging it with any existing `<repositories>` section:
```xml
<repositories>
<repository>
<id>datalogics</id>
<url>https://repo.datalogics.com/api/maven/datalogics-enterprise/apdfl-public</url>
<releases><enabled>true</enabled></releases>
<snapshots><enabled>false</enabled></snapshots>
</repository>
</repositories>
```
The public repository requires no credentials. If access fails, check your organization's Maven mirror or proxy configuration. For complete configuration examples, see [How to Obtain APDFL Java Packages from the Datalogics Maven Repository](https://kb.datalogics.com/article/how-to-obtain-apdfl-java-packages-from-the-datalogics-maven-repository-185.html).
3. Update All APDFL Artifacts Together
The Java distribution includes the API JAR, a platform-specific JNI ZIP, and a resources ZIP. Update all three to the same APDFL package release, along with any explicitly referenced Javadoc artifact.
Use a shared Maven property to keep those references aligned:
```xml
<properties>
<apdfl.version>21.1.0</apdfl.version>
</properties>
```
Replace each core APDFL artifact's version with `${apdfl.version}`. The value above is an example; select the v21 release approved for your application. Avoid `LATEST` when you need reproducible builds.
Review Forms Extension and OCR dependencies separately for compatible versions and platform availability. Their version numbers need not all match the core package.
4. Refresh Native Libraries and Resources
Keep the dependency-unpacking steps in your build. In the sample layout, native libraries are unpacked into `target/lib` and resources into `target/lib/Resources`.
Perform a clean build to remove stale files. Review runtime search paths and deployment scripts for `DL180`; the Java interface now loads `com-datalogics-DL210PDFL` and requires its matching native dependencies. Deploy the complete updated resource tree as well.
Verify the Upgrade
Run the application on the actual deployment JVM and process representative documents. The newer core can change rendering, font matching, and color conversion results.
An `UnsupportedClassVersionError` indicates an older JVM and occurs before APDFL licensing or native initialization. Native-loading errors instead warrant checking JNI versions, search paths, dependencies, and architecture.
The licensing API remains unchanged. For License-Managed applications, preserve your existing license configuration and confirm license-file or server compatibility with the target release.
How to Get Additional Help
Contact Datalogics Tech Support
Fetch the answers quickly using our AI assistant Scout, available for any language. Scout also opens access to our MCP server, connecting APDFL with your favorite AI tools for faster and easier coding.