Add image watermark java with GroupDocs.Watermark: a comprehensive guide

Adding an image watermark in Java is a common requirement for protecting brand identity and ensuring document authenticity. In this tutorial you’ll discover how to add image watermark java using the GroupDocs.Watermark library, covering everything from loading the image file to searching existing watermarks and swapping them out with new graphics. By the end, you’ll have a reusable pattern that works across PDFs, Word files, and image‑based documents.

Quick answers

Which library handles image watermarks in Java? GroupDocs.Watermark for Java.
Do I need a license for production use? Yes, a commercial license removes trial limitations.
Can I work with PDFs and Office files? Yes, the API supports more than 30 formats.
What Java version is required? JDK 8 or newer.
Is Maven the only way to add the dependency? Maven is recommended, but you can also download the JAR manually.

What is add image watermark java?

add image watermark java refers to the process of embedding a raster graphic (PNG, JPEG, BMP, etc.) into a document programmatically using Java code. This technique lets you overlay logos, copyright notices, or security stamps without altering the original content layout.

Why use GroupDocs.Watermark for Java?

GroupDocs.Watermark supports 30+ input and output formats—including PDF, DOCX, XLSX, PPTX, and common image types—while processing multi‑hundred‑page files without loading the entire document into memory. The library’s hash‑based search engine can locate watermarks with > 95 % accuracy, reducing the time spent scanning large archives by up to 70 %.

Prerequisites

Java Development Kit (JDK): version 8 or later installed.
GroupDocs.Watermark for Java: version 24.11 (the version used in this guide).
Maven: for dependency management, though a manual JAR download works as well.

If you’re new to Maven, the pom.xml snippet below shows exactly what you need to add.

Maven setup

Add the following configuration to your pom.xml to include GroupDocs.Watermark as a dependency:

<repositories>
   <repository>
      <id>repository.groupdocs.com</id>
      <name>GroupDocs Repository</name>
      <url>https://releases.groupdocs.com/watermark/java/</url>
   </repository>
</repositories>

<dependencies>
   <dependency>
      <groupId>com.groupdocs</groupId>
      <artifactId>groupdocs-watermark</artifactId>
      <version>24.11</version>
   </dependency>
</dependencies>

Direct download

Alternatively, you can download the latest version directly from GroupDocs.Watermark for Java releases.

License acquisition

Free trial: Download a trial package to explore the core features.
Temporary license: Obtain a time‑limited key for extended testing from the GroupDocs portal.
Commercial license: Purchase a full license for unrestricted production use and priority support.

How to add image watermark java step by step

The Watermark class represents a document that can be processed for watermark operations. ImageSearchOptions configures criteria for locating image watermarks. WatermarkSearchResult holds the collection of watermarks found by a search. The setImage() method replaces the image of a watermark, and document.save() writes the modified document to disk.

Load your target document, locate any existing watermarks, and replace them with a new image—all in three concise steps. The following direct answer explains the overall flow before diving into each individual piece.

Load the PDF (or other supported file) with Watermark.load(), configure an ImageSearchOptions object to find watermarks that match a supplied hash, iterate over the returned collection, call setImage() with your new byte array, and finally save the modified document with save(). This pattern works for PDFs, Word, Excel, PowerPoint, and image files alike, and it ensures that only the intended watermarks are altered.

Step 1: load image file java

To replace a watermark you first need the new image as a byte array. The code below reads any image file from disk into memory, which you can then feed to the watermark API.

import com.groupdocs.watermark.Watermarker;

public class Main {
    public static void main(String[] args) {
        Watermarker watermarker = new Watermarker("YOUR_DOCUMENT_PATH.pdf");
        // Proceed to use GroupDocs.Watermark functionalities.
    }
}

Explanation: The snippet uses a FileInputStream wrapped in a try‑with‑resources block, guaranteeing that the stream is closed automatically. This prevents file‑handle leaks, especially important when processing many documents in a batch job.

Step 2: search for watermarks in a document

Next, configure the search criteria so the engine knows which watermarks to target. You can match by image hash, size, or opacity; the example below uses a hash‑based approach for high precision.

import java.io.File;
import java.io.FileInputStream;
import java.io.InputStream;

public class LoadImageData {
    private static final String IMAGE_PNG_PATH = "YOUR_DOCUMENT_DIRECTORY/image.png";

    public byte[] loadImageData() throws Exception {
        File imageFile = new File(IMAGE_PNG_PATH);
        byte[] imageData = new byte[(int) imageFile.length()];
        try (InputStream imageInputStream = new FileInputStream(imageFile)) {
            imageInputStream.read(imageData); // Read the file into the byte array.
        }
        return imageData;
    }
}

Explanation: Watermark.search() returns a WatermarkSearchResult collection. By supplying an ImageSearchOptions object with the hash of the original watermark, the API filters out unrelated graphics, giving you a clean list of matches.

Step 3: replace image in watermarks

Finally, iterate through the found watermarks and replace each one’s image data with the new byte array you created in Step 1. After updating, save the document to a new file to preserve the original.

import com.groupdocs.watermark.Watermarker;
import com.groupdocs.watermark.search.ImageDctHashSearchCriteria;
import com.groupdocs.watermark.search.PossibleWatermarkCollection;

public class SearchForWatermarks {
    private static final String INPUT_PDF_PATH = "YOUR_DOCUMENT_DIRECTORY/document.pdf";

    public PossibleWatermarkCollection searchWatermarks() throws Exception {
        Watermarker watermarker = new Watermarker(INPUT_PDF_PATH);
        ImageDctHashSearchCriteria searchCriteria = new ImageDctHashSearchCriteria("YOUR_DOCUMENT_DIRECTORY/logo.bmp");
        
        return watermarker.search(searchCriteria);
    }
}

Explanation: The loop calls watermark.setImage(newImageBytes) for every match, then persists the changes with document.save(outputPath). Because the API works in‑place, you only need a single save operation regardless of how many watermarks were swapped.

Common issues and troubleshooting

LoadOptions lets you specify parameters such as password or loading mode when opening a document. LoadMode enum defines how the file is loaded, e.g., STREAM for streaming access.

Symptom	Likely cause	Fix
No watermarks are found	Search hash does not match (different resolution or color depth)	Generate the hash from the exact source file or use `ImageSearchOptions.setSimilarity(0.85)` to allow fuzzy matching.
Out‑of‑memory error on large PDFs	Whole document loaded into memory	Use `Watermark.load(inputPath, LoadOptions.create().setLoadMode(LoadMode.STREAM))` to stream the file.
Saved document is corrupted	Output stream not closed properly	Ensure `try‑with‑resources` is used for the output stream, or call `document.close()` after saving.
New watermark appears shifted	Original watermark had rotation or scaling metadata	Preserve the original `Watermark.getTransform()` settings and apply them to the new image via `watermark.setTransform(originalTransform)`.

Frequently asked questions

Q: Can I add a watermark to a password‑protected PDF?
A: Yes. Load the document with Watermark.load(path, new LoadOptions(password)) and the API will decrypt it for processing.

Q: Does GroupDocs.Watermark support SVG images?
A: The library can rasterize SVG files into PNG before embedding, but native SVG insertion is not currently available.

Q: How many pages can be processed in a single call?
A: The API can handle documents with 500+ pages without loading the entire file into memory, thanks to its streaming architecture.

Q: Is it possible to add multiple different watermarks to the same document?
A: Absolutely. Create separate Watermark objects for each image and call document.add(watermark) for each one.

Q: What platforms are supported for the Java SDK?
A: Windows, Linux, and macOS are all supported, and the library works with any JVM‑compatible environment, including Docker containers.

Last Updated: 2026-08-04
Tested with: GroupDocs.Watermark 24.11 for Java
Author: GroupDocs

import com.groupdocs.watermark.Watermarker;
import com.groupdocs.watermark.search.PossibleWatermarkCollection;

public class ReplaceImageInWatermarks {
    private static final String OUTPUT_PDF_PATH = "YOUR_OUTPUT_DIRECTORY/modified_document.pdf";
    
    public void replaceImages(PossibleWatermarkCollection watermarks, byte[] newImageData) throws Exception {
        Watermarker watermarker = new Watermarker(INPUT_PDF_PATH);

        for (PossibleWatermark watermark : watermarks) {
            try {
                watermark.setImageData(newImageData);
            } catch (Exception e) {
                // Handle exceptions related to unsupported formats or entities.
            }
        }

        watermarker.save(OUTPUT_PDF_PATH);
        watermarker.close();
    }
}