Getting started on Java

This guide will take you through the steps necessary to integrate PSPDFKit into your Java application. By the end, you’ll be able to load a PDF document into your application using the PSPDFKit API.

Select the build system you’re using:

Gradle Build System

  1. In your top-level build.gradle file, add the PSPDFKit Maven repository:

allprojects {
	repositories {
		maven {
				url 'https://my.nutrient.io/maven/'
		}
	}
}

  1. In the depending module’s build.gradle file, add the PSPDFKit dependency:

    dependencies {
    implementation 'com.pspdfkit:libraries-java:1.6.1'
}

  2. Add the OCR dependency (optional). This is only necessary if you plan to use the OCR feature.

To use the PSPDFKit OCR feature with the PSPDFKit Java Library, a separate package, libraries-java-ocr, is required.

Add the new package dependency to your build.gradle file:

dependencies {
...
    implementation 'com.pspdfkit:libraries-java-ocr:1.6.1'
}

Maven Build System

  1. In your top-level pom.xml file, add the PSPDFKit Maven repository:

<repositories>
	<repository>
		<id>pspdfkit</id>
		<name>PSPDFKit Maven</name>
		<url>https://my.nutrient.io/maven/</url>
	</repository>
</repositories>

  1. In the depending module’s pom.xml file, add the PSPDFKit dependency:

<dependencies>
	<dependency>
		<groupId>com.pspdfkit</groupId>
		<artifactId>libraries-java</artifactId>
		<version>1.6.1</version>
	</dependency>
</dependencies>

  1. Add the OCR dependency (optional). This is only necessary if you plan to use the OCR feature.

To use the PSPDFKit OCR feature with the PSPDFKit Java Library, a separate package, libraries-java-ocr, is required.

Add the new package dependency to your project pom.xml file:

<dependencies>
    ...
    <dependency>
        <groupId>com.pspdfkit</groupId>
        <artifactId>libraries-java-ocr</artifactId>
        <version>1.6.1</version>
    </dependency>

Using the PSPDFKit Java Library

  1. Now that the PSPDFKit Java Library is added, you can use the SDK in your application. You need to initialize the SDK prior to calling any other PSPDFKit method. Use the initializeTrial method if you haven’t yet bought a license key, or the initialize method if you have a key:

public void initializePSPDFKit() throws PSPDFKitInitializeException {
    PSPDFKit.initializeTrial();
}
@Throws(PSPDFKitInitializeException::class)
fun initializePSPDFKit() : Void {
    PSPDFKit.initializeTrial();
}

  1. Load a document with:

File file = new File("path/to/document.pdf");
PdfDocument document = PdfDocument.open(new FileDataProvider(file));
val file = File("path/to/document.pdf")
val document = PdfDocument.open(FileDataProvider(file))

  1. Once you have a document loaded, you can use the rest of the library. See the API docs and guides for more information, or try out the Catalog examples (see below).

Building and Running the Catalog App

The PSPDFKit Java Library comes with an example application called the Catalog app, which contains many useful examples for exploring the different features of PSPDFKit and getting started quickly. You can find the app in the Example folder of the SDK ZIP file.

To build and run the Catalog app, follow these steps.

  1. Download the latest release.

  2. Extract PSPDFKit-Libraries-java_binary-{version}.zip to your desired location and cd into the root of its directory.

  3. cd into the Catalog (cd catalog).

  4. Build and run the Catalog application:

./gradlew runJava

The PSPDFKit Java Library comes with an example application called the Catalog app, which contains many useful examples for exploring the different features of PSPDFKit and getting started quickly. You can find the app in the Example folder of the SDK ZIP file.

To build and run the Catalog app, follow these steps.

  1. Download the latest release.

  2. Extract PSPDFKit-Libraries-java_binary-{version}.zip to your desired location and cd into the root of its directory.

  3. cd into the Catalog (cd catalog).

  4. Build and run the Catalog application:

./gradlew runJava

The PSPDFKit Java Library comes with an example application called the Catalog app, which contains many useful examples for exploring the different features of PSPDFKit and getting started quickly. You can find the app in the Example folder of the SDK ZIP file.

To build and run the Catalog app, follow these steps.

  1. Download the latest release.

  2. Extract PSPDFKit-Libraries-java_binary-{version}.zip to your desired location and cd into the root of its directory.

  3. cd into the Catalog (cd catalog).

  4. Build and run the Catalog application:

gradlew.bat runJava

This guide will take you through the steps necessary to integrate PSPDFKit into your Java application. By the end, you’ll be able to load a PDF document into your application using the PSPDFKit API.

Only use the manual method if absolutely necessary. Otherwise, refer to the main integrating PSPDFKit Java Library guide for more details.

Select the build system you’re using:

Gradle Build System

If you’re using the Gradle build system, a good example of how to integrate the PSPDFKit Java Library can be seen in the Catalog example distributed in the downloaded ZIP.

Complete the following steps for manual Gradle integration.

  1. Create a folder within your project named libs.

  2. Download the latest release.

  3. In the downloaded ZIP file, there will be a JAR file, pspdfkit-1.6.1.jar. Copy this JAR file into the libs folder you just created.

  4. In your project’s build.gradle folder, add a dependency to the copied JAR file (replace the wildcards with the version number):

dependencies {
	...
	implementation files('libs/pspdfkit-1.6.1.jar')

	// Required by PSPDFKit.
	implementation 'org.json:json:20180813'
	implementation 'org.apache.httpcomponents:httpclient:4.5.9'
	...
}

Now your Gradle project will depend upon the PSPDFKit JAR. More information about declaring dependencies can be found in the Gradle documentation.

  1. Add the OCR dependency (optional). This is only necessary if you plan to use the OCR feature.

To use the PSPDFKit OCR feature with the PSPDFKit Java Library, a separate package, libraries-java-ocr, is required.

Maven Build System

To use the PSPDFKit Java Library with Maven, it’s first necessary to install the PSPDFKit JAR to a Maven repository. Only when this is done can it be a reference for a Maven project.

  1. Download the latest release.

  2. Extract the files from PSPDFKit-Java-binary-1.6.1.zip into a known location.

  3. Within your project, using mvn on the command line, add the PSPDFKit JAR to a repository, replacing both the version (where necessary) and the path to the JAR and POM (extracted from PSPDFKit-Java-binary-1.6.1.zip):

mvn install:install-file -Dfile=/path/to/jar/pspdfkit-*.*.*.jar -DpomFile=/path/to/pom/pspdfkit-pom.xml

This will install the JAR to a local repository. It’s also possible to publish this JAR remotely; see the Maven guides if this is a requirement.

  1. Add the PSPDFKit Java Library as a dependency of your project. In your project’s pom.xml, add the following, replacing the version with the target version:

...
<dependencies>
	<dependency>
		<groupId>com.pspdfkit.api</groupId>
		<artifactId>pspdfkit</artifactId>
		<version>1.6.1</version>
	</dependency>
</dependencies>
...

Now your Maven project will depend on the PSPDFKit JAR published to the chosen repository.

  1. Add the OCR dependency (optional). This is only necessary if you plan to use the OCR feature.

To use the PSPDFKit OCR feature with the PSPDFKit Java Library, a separate package, libraries-java-ocr, is required.

Using the PSPDFKit Java Library

  1. Now that the PSPDFKit Java Library is added, you can use the SDK in your application. You need to initialize the SDK prior to calling any other PSPDFKit method. Use the initializeTrial method if you haven’t yet bought a license key, or the initialize method if you have a key:

public void initializePSPDFKit() throws PSPDFKitInitializeException {
    PSPDFKit.initializeTrial();
}
@Throws(PSPDFKitInitializeException::class)
fun initializePSPDFKit() : Void {
    PSPDFKit.initializeTrial();
}

  1. Load a document with:

File file = new File("path/to/document.pdf");
PdfDocument document = PdfDocument.open(new FileDataProvider(file));
val file = File("path/to/document.pdf")
val document = PdfDocument.open(FileDataProvider(file))

  1. Once you have a document loaded, you can use the rest of the library. See the API docs and guides for more information, or try out the Catalog examples (see below).

Building and Running the Catalog App

The PSPDFKit Java Library comes with an example application called the Catalog app, which contains many useful examples for exploring the different features of PSPDFKit and getting started quickly. You can find the app in the Example folder of the SDK ZIP file.

To build and run the Catalog app, follow these steps.

  1. Download the latest release.

  2. Extract PSPDFKit-Libraries-java_binary-{version}.zip to your desired location and cd into the root of its directory.

  3. cd into the Catalog (cd catalog).

  4. Build and run the Catalog application:

./gradlew runJava

The PSPDFKit Java Library comes with an example application called the Catalog app, which contains many useful examples for exploring the different features of PSPDFKit and getting started quickly. You can find the app in the Example folder of the SDK ZIP file.

To build and run the Catalog app, follow these steps.

  1. Download the latest release.

  2. Extract PSPDFKit-Libraries-java_binary-{version}.zip to your desired location and cd into the root of its directory.

  3. cd into the Catalog (cd catalog).

  4. Build and run the Catalog application:

./gradlew runJava

The PSPDFKit Java Library comes with an example application called the Catalog app, which contains many useful examples for exploring the different features of PSPDFKit and getting started quickly. You can find the app in the Example folder of the SDK ZIP file.

To build and run the Catalog app, follow these steps.

  1. Download the latest release.

  2. Extract PSPDFKit-Libraries-java_binary-{version}.zip to your desired location and cd into the root of its directory.

  3. cd into the Catalog (cd catalog).

  4. Build and run the Catalog application:

gradlew.bat runJava