# Using the Datalogics Maven repository — APDFL for Java

**Audience:** customers and evaluators using the Adobe PDF Library Java interface
**Verified:** the configuration below was built against a live repository on 2026-08-31 —
the version range resolved, and the native libraries and resources unpacked as described
**Repository:** `apdfl-public` — no credentials required
**Current release:** 21.1.0

## 1. Add the repository

Add Datalogics to your `~/.m2/settings.xml`:

```xml
<settings>
  <profiles>
    <profile>
      <id>datalogics</id>
      <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>
    </profile>
  </profiles>
  <activeProfiles>
    <activeProfile>datalogics</activeProfile>
  </activeProfiles>
</settings>
```

Or add the same `<repository>` block to a single project's `pom.xml` if you would rather
not change your global configuration.

**No credentials are required.** If you are prompted for a username or password, something
local is intercepting the request — see Troubleshooting.

## 2. Declare the dependencies

APDFL is more than a jar: the Java API is one artifact, the native libraries for your
platform are a second, and the runtime resources (fonts, CMaps, colour profiles) are a
third. All three come from the same coordinates, distinguished by classifier and type.

Select the right native payload automatically with OS-activated profiles:

```xml
<profiles>
  <profile>
    <id>Windows64</id>
    <activation><os><family>windows</family><arch>amd64</arch></os></activation>
    <properties><jni.classifier>win-x86-64-jni</jni.classifier></properties>
  </profile>
  <profile>
    <id>WindowsArm64</id>
    <activation><os><family>windows</family><arch>aarch64</arch></os></activation>
    <properties><jni.classifier>win-arm-64-jni</jni.classifier></properties>
  </profile>
  <profile>
    <id>Linux64</id>
    <!-- Use <name> rather than <family>, because the "unix" family also matches macOS -->
    <activation><os><name>Linux</name><arch>amd64</arch></os></activation>
    <properties><jni.classifier>linux-x86-64-jni</jni.classifier></properties>
  </profile>
  <profile>
    <id>LinuxArm64</id>
    <activation><os><name>Linux</name><arch>aarch64</arch></os></activation>
    <properties><jni.classifier>linux-arm-64-jni</jni.classifier></properties>
  </profile>
  <profile>
    <id>MacArm</id>
    <activation><os><family>mac</family><arch>aarch64</arch></os></activation>
    <properties><jni.classifier>mac-arm-64-jni</jni.classifier></properties>
  </profile>
</profiles>

<dependencies>
  <dependency>
    <groupId>com.datalogics.pdfl</groupId>
    <artifactId>pdfl</artifactId>
    <version>[21.0,22.0)</version>
  </dependency>
  <dependency>
    <groupId>com.datalogics.pdfl</groupId>
    <artifactId>pdfl</artifactId>
    <version>[21.0,22.0)</version>
    <type>zip</type>
    <classifier>${jni.classifier}</classifier>
  </dependency>
  <dependency>
    <groupId>com.datalogics.pdfl</groupId>
    <artifactId>pdfl</artifactId>
    <version>[21.0,22.0)</version>
    <type>zip</type>
    <classifier>resources</classifier>
  </dependency>
</dependencies>
```

The version range `[21.0,22.0)` picks up the newest 21.x release automatically. Pin an
exact version (`21.1.0`) instead if you prefer reproducible builds.

While older APDFL versions remain on Maven Central, a range sees versions from both
repositories and selects the highest — so a range keeps working across the move, with no
gap between what Central holds and what we publish here.

## 3. Unpack the native libraries and resources

The zip artifacts have to be exploded onto disk before the library can load them. Use
`maven-dependency-plugin` so it happens as part of every build:

```xml
<build>
  <pluginManagement>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <version>3.0.2</version>
      </plugin>
    </plugins>
  </pluginManagement>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-dependency-plugin</artifactId>
      <executions>
        <execution>
          <id>unpack-jni</id>
          <phase>generate-resources</phase>
          <goals><goal>unpack-dependencies</goal></goals>
          <configuration>
            <includeGroupIds>com.datalogics.pdfl</includeGroupIds>
            <includeArtifactIds>pdfl</includeArtifactIds>
            <includeClassifiers>${jni.classifier}</includeClassifiers>
            <includeTypes>zip</includeTypes>
            <outputDirectory>${project.build.directory}/lib</outputDirectory>
          </configuration>
        </execution>
        <execution>
          <id>unpack-resources</id>
          <phase>generate-resources</phase>
          <goals><goal>unpack-dependencies</goal></goals>
          <configuration>
            <includeGroupIds>com.datalogics.pdfl</includeGroupIds>
            <includeArtifactIds>pdfl</includeArtifactIds>
            <includeClassifiers>resources</includeClassifiers>
            <includeTypes>zip</includeTypes>
            <outputDirectory>${project.build.directory}/lib/Resources</outputDirectory>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>
```

Native libraries land in `target/lib` and resources in `target/lib/Resources`, which is
the layout the library expects.

## 4. Set your license key

```java
Library.setLicenseKey("xxxx-xxxx-xxxx-xxxx");
Library lib = new Library();
```

Call `setLicenseKey` before constructing the `Library`. Evaluation keys come from the
[free trial page](https://www.datalogics.com/pdf-sdk-free-trial).

## Optional components

Each is an additional dependency alongside `pdfl`, following the same pattern.

| Component | Artifact | Notes |
|---|---|---|
| Forms plug-in | `forms-extension` | Windows x64, Linux x64, Linux ARM |
| WebConvert (HTML/URL to PDF) | `web-conversion` | Also requires `web-conversion-cef-runtime` |
| Chromium runtime for WebConvert | `web-conversion-cef-runtime` | Large (~600 MB); Windows x64/ARM, Linux x64/ARM, macOS ARM |
| OCR language data | `ocr-data` | Platform-independent; declare with `<type>zip</type>` and unpack it the same way |

`forms-extension` and `web-conversion` declare `pdfl` as a dependency, so adding either
one brings the core library with it. `web-conversion` also depends on
`web-conversion-cef-runtime`, so the Chromium runtime arrives automatically — be aware
that it is a large download.

On macOS the WebConvert plug-in and its Chromium runtime ship together inside
`web-conversion-cef-runtime`, because the macOS bundle is a single signed framework that
cannot be split. There is no macOS payload in `web-conversion` itself.

## Complete working examples

<https://github.com/datalogics/apdfl-java-maven-samples> — every sample is a self-contained
Maven project using exactly the configuration above. The OCR samples additionally show how
to declare and unpack `ocr-data`.

Full documentation:
<https://dev.datalogics.com/adobe-pdf-library-21/java/getting-started>

## Verifying what you downloaded

Every artifact is published with a GPG signature (`.asc`), and with MD5 and SHA-1 checksums
that Maven verifies automatically. To check a signature yourself:

```bash
gpg --keyserver keys.openpgp.org --recv-keys 17256739C183CC6A40152F0EE8A4DCC0AD04A223

URL=https://repo.datalogics.com/api/maven/datalogics-enterprise/apdfl-public/com/datalogics/pdfl/pdfl/21.1.0
curl -O "$URL/pdfl-21.1.0.jar"
curl -O "$URL/pdfl-21.1.0.jar.asc"
gpg --verify pdfl-21.1.0.jar.asc pdfl-21.1.0.jar
```

Expect `Good signature from ...`. GPG will also warn that the key is not certified with a
trusted signature; that is normal and simply means you have not personally signed our key.

## If you previously used Maven Central

Versions already on Maven Central remain there and keep resolving — nothing was removed,
and existing builds are unaffected. New releases are published only to the repository
above.

To move an existing project across, add the repository configuration and update the
version. Nothing else changes: the group and artifact ids, the classifiers, and the
unpacking steps are all identical.

Two things you gain:

- **ARM platforms.** Windows ARM and Linux ARM builds could not be published to Maven
  Central. They are available here.
- **Complete releases.** Central's size limits forced us to publish components on
  staggered schedules. Every component of a release now ships together.

## Troubleshooting

**You are prompted for credentials.** The repository requires none. Check `settings.xml`
for a `<mirror>` with `<mirrorOf>*</mirrorOf>`, which redirects every request — including
this one — through an internal proxy. Change it to `<mirrorOf>*,!datalogics</mirrorOf>`.

**`blocked mirror for repositories` / `maven-default-http-blocker`.** Maven 3.8.1 and later
refuse plain-HTTP repositories. Confirm your configured URL begins with `https://`.

**Java version.** Maven 3.9 requires Java 8 or newer. If Maven dies with a `ClassLoader`
stack trace before contacting any repository, check `JAVA_HOME`; a stale Java 7 setting
produces exactly that failure and has nothing to do with the repository.

**`Could not find artifact`.** Check the platform table — not every component is built for
every platform. `forms-extension` has no Windows ARM build, and `web-conversion` has no
macOS payload (see above).

**`Could not find artifact com.datalogics.pdfl:pdfl:zip:${jni.classifier}:...`** — note the
literal `${jni.classifier}` in the message. No OS profile matched, so the property was
never set. The usual cause is a **JDK whose architecture differs from the hardware**: an
x86_64 JDK on an Apple Silicon Mac reports `os.arch=x86_64`, so the `aarch64` profile does
not activate, and there is no macOS x86_64 build of APDFL to fall back on. Check with:

```bash
java -XshowSettings:properties -version 2>&1 | grep os.arch
```

Install a JDK matching your hardware, or set the property explicitly with
`-Djni.classifier=mac-arm-64-jni`.

**Native library fails to load at runtime.** Confirm `target/lib` actually contains the
unpacked libraries — a correct unpack produces the platform's shared libraries plus the
`activate` licensing binary. If the directory is missing entirely, the `unpack-jni`
execution never ran or matched nothing; see the previous item.

**Corporate proxy or firewall.** Requests go to `repo.datalogics.com` over HTTPS on port
443. That host may need allowing alongside `repo.maven.apache.org`.

## Support

<support@datalogics.com>