How to annotate PDF and export pages with GroupDocs Java

In this comprehensive guide you’ll discover how to annotate PDF files using GroupDocs.Annotation for Java and then export only the pages that contain those annotations. By the end of the tutorial you’ll be able to add precise area and ellipse annotations, configure selective page export, and apply performance‑tuned techniques that work in production environments.

Quick answers

  • What is the primary benefit of exporting annotated pages? It creates a lightweight PDF containing only the relevant feedback, ideal for reviews and summaries.
  • Which Maven version is required? Maven 3.6+ is recommended.
  • Do I need a license for GroupDocs.Annotation? Yes, a trial or commercial license is required for production use.
  • Can I annotate formats other than PDF? Absolutely—GroupDocs supports 50+ document types.
  • How do I avoid memory issues with large PDFs? Process pages in batches, increase JVM heap, and always close the Annotator with try‑with‑resources.

What is “export annotated PDF pages”?

Exporting annotated PDF pages means generating a new PDF that contains only those pages where annotations exist. This reduces file size, focuses reviewers on the relevant content, and simplifies version control. By extracting just the annotated sections you keep the review cycle tight and avoid sending bulky files that contain unchanged material.

Why export annotated PDF pages?

Exporting only the pages that contain annotations produces a focused, smaller document that streamlines collaboration. Reviewers receive just the relevant pages, which reduces email size and web‑upload bandwidth. It also creates a clear audit trail by eliminating untouched pages, making it easier to track feedback and maintain version control.

Prerequisites: getting your environment ready

Before we start coding, let’s make sure you have everything set up correctly. Spending a few minutes here will save you hours of debugging later.

Required libraries and dependencies

You’ll need GroupDocs.Annotation for Java in your project. Below is the Maven configuration that actually works (many tutorials still reference outdated repository URLs).

```xml
<repositories>
   <repository>
      <id>repository.groupdocs.com</id>
      <name>GroupDocs Repository</name>
      <url>https://releases.groupdocs.com/annotation/java/</url>
   </repository>
</repositories>
<dependencies>
   <dependency>
      <groupId>com.groupdocs</groupId>
      <artifactId>groupdocs-annotation</artifactId>
      <version>25.2</version>
   </dependency>
</dependencies>

### System requirements

- **Java Development Kit (JDK)**: Version 8 or higher (JDK 11+ recommended for better performance)  
- **Maven**: Version 3.6+ for dependency management  
- **Memory**: At least 2 GB RAM available for your application (more for large PDFs)

### Knowledge prerequisites

You should be comfortable with basic Java programming, Maven dependency management, and file I/O operations. Don’t worry if you’re not an expert—each step includes clear explanations.

## Setting up GroupDocs.Annotation for Java

Now let’s get GroupDocs.Annotation properly configured in your project. This is where many developers hit their first roadblock, so pay close attention.

### Step 1: add the dependency

Use the Maven configuration above to include GroupDocs.Annotation in your project. After adding it to your `pom.xml`, run:

```text
```bash
mvn clean install

If you see any download errors, double‑check that your repository URL matches the snippet exactly.

### Step 2: handle licensing (important!)

GroupDocs.Annotation isn’t free for commercial use. You have a few options:

- **Free trial** – good for development and testing  
- **Temporary license** – perfect for extended evaluation periods  
- **Full license** – required for production deployment  

To get started with evaluation, visit [GroupDocs Purchase](https://purchase.groupdocs.com/buy) for licensing options.

### Step 3: basic initialization

The `Annotator` class is GroupDocs.Annotation’s main entry point for loading, modifying, and saving PDF documents. You can initialize it as follows:

```text
```java
import com.groupdocs.annotation.Annotator;

try (final Annotator annotator = new Annotator("YOUR_DOCUMENT_DIRECTORY/document.pdf")) {
    // Your annotation code goes here
    System.out.println("Annotator initialized successfully!");
}

**Pro tip:** Always use try‑with‑resources (as shown above) to ensure proper cleanup of file handles. Forgetting this step is a common source of memory leaks.

## Implementation guide: adding annotations step by step

Now for the fun part—let’s start adding actual annotations to your PDFs. We’ll focus on two popular annotation types that cover most use cases.

### How to add area annotations (perfect for highlighting sections)

Area annotations are fantastic when you need to highlight entire paragraphs, sections, or any rectangular region in your PDF. Think of them as digital highlighter markers.

#### Step 1: create an area annotation

The `Rectangle` class defines the position and size of an annotation on a PDF page.

```text
```java
import com.groupdocs.annotation.models.Rectangle;
import com.groupdocs.annotation.models.annotationmodels.AreaAnnotation;

// Create area annotation
AreaAnnotation area = new AreaAnnotation();
area.setBox(new Rectangle(100, 100, 100, 100)); // x, y, width, height in pixels
area.setBackgroundColor(65535); // Yellow highlight color (ARGB format)
area.setPageNumber(1); // First page (1-indexed)

**Understanding the parameters**  
- `Rectangle(100, 100, 100, 100)`: Position (100 px from left, 100 px from top) with 100 px width and height  
- `65535`: This is yellow in ARGB format. Common colors: Red = 16711680, Blue = 255, Green = 65280  
- `setPageNumber(1)`: PDF pages are 1‑indexed, not 0‑indexed (a frequent mistake)

#### When to use area annotations  

- Highlighting important paragraphs in legal documents  
- Marking sections that need review in project specifications  
- Drawing attention to specific data ranges in reports  
- Creating visual boundaries around content blocks  

### How to add ellipse annotations (great for callouts)

Ellipse annotations are perfect when you want to draw attention to specific elements without the harsh edges of rectangles. They’re especially useful for highlighting circular charts, logos, or creating a soft‑focus area.

#### Step 2: create an ellipse annotation

```text
```java
import com.groupdocs.annotation.models.annotationmodels.EllipseAnnotation;

// Create ellipse annotation
EllipseAnnotation ellipse = new EllipseAnnotation();
ellipse.setBox(new Rectangle(200, 200, 150, 100)); // Ellipse bounds
ellipse.setBackgroundColor(123456); // Custom color
ellipse.setPageNumber(1); // Same page as area annotation

**Why use ellipses over rectangles?**  
Ellipses provide a softer, more organic highlight compared to the hard edges of rectangles, making them visually appealing for circular elements such as charts or logos. They create a spotlight effect that draws attention without fully obscuring content, and can give annotations a hand‑drawn appearance that feels less intrusive in professional documents.

#### Step 3: add annotations to your document

Now let’s combine both annotations and add them to your PDF in one batch operation:

```text
```java
import java.util.ArrayList;
import java.util.List;

// Create a list to hold all annotations
List<com.groupdocs.annotation.models.AnnotationBase> annotations = new ArrayList<>();
annotations.add(area);
annotations.add(ellipse);

// Add all annotations at once (more efficient than adding individually)
annotator.add(annotations);

System.out.println("Added " + annotations.size() + " annotations successfully!");

**Performance tip:** Adding annotations in batches (as shown above) is significantly faster than calling `annotator.add()` multiple times, especially with large documents.

## How to export annotated PDF pages with GroupDocs

You can configure GroupDocs to **export only the pages that contain annotations**. This feature is invaluable for creating summary documents or reducing file sizes.

#### Setting up selective page export

The `SaveOptions` class lets you specify how the PDF is saved, including whether to include only annotated pages.

```text
```java
import com.groupdocs.annotation.options.export.SaveOptions;

// Configure save options for annotated pages only
SaveOptions saveOptions = new SaveOptions();
saveOptions.setOnlyAnnotatedPages(true); // This is the magic setting

// Save the document with your custom options
annotator.save("YOUR_OUTPUT_DIRECTORY/annotated_summary.pdf", saveOptions);

**Real‑world use cases**  

- **Legal review** – export only pages with attorney comments  
- **Academic grading** – create summary sheets with only marked sections  
- **Project management** – generate status reports showing only updated sections  
- **Quality assurance** – extract pages with identified issues  

## Common issues and solutions

Let’s address the problems you’re most likely to encounter and save you some debugging time.

### Issue 1: “File is being used by another process”

**Symptoms:** `IOException` when trying to save the annotated document  
**Cause:** Not properly closing the `Annotator` instance  
**Solution:** Always use try‑with‑resources:

```text
```java
// Wrong way - can cause file locks
Annotator annotator = new Annotator("document.pdf");
// ... your code ...
// Forgot to close!

// Right way - automatic cleanup
try (Annotator annotator = new Annotator("document.pdf")) {
    // ... your code ...
} // Automatically closed here

### Issue 2: Annotations appearing in wrong positions

**Symptoms:** Annotations show up in unexpected locations  
**Cause:** Coordinate system misunderstanding or DPI scaling issues  
**Solution:**  

- PDF coordinates start from **bottom‑left** (not top‑left like most UI frameworks)  
- Test with known coordinate values first  
- Consider PDF page dimensions when calculating positions  

### Issue 3: OutOfMemoryError with large PDFs

**Symptoms:** Application crashes when processing large documents  
**Cause:** Loading the entire PDF into memory  
**Solution:**  

```text
```java
// Increase JVM heap size
// -Xmx2g for 2GB max heap

// Or process pages individually
for (int page = 1; page <= totalPages; page++) {
    // Process one page at a time
}

### Issue 4: Colors not displaying correctly

**Symptoms:** Annotation colors appear different than expected  
**Cause:** Color format confusion (RGB vs ARGB)  
**Solution:** Use ARGB format consistently:  

- Red: `0xFFFF0000` or `16711680`  
- Green: `0xFF00FF00` or `65280`  
- Blue: `0xFF0000FF` or `255`  
- Semi‑transparent red: `0x80FF0000`

## Best practices for production use

Ready to deploy your annotation features? Here are the practices that separate amateur implementations from professional‑grade solutions.

### Memory management

```text
```java
// Configure JVM for optimal performance
// -XX:+UseG1GC -Xmx4g -XX:MaxGCPauseMillis=200

// In your code, process large documents in chunks
private void processLargeDocument(String filePath) {
    try (Annotator annotator = new Annotator(filePath)) {
        // Process annotations in batches of 10‑20
        List<AnnotationBase> batch = new ArrayList<>();
        for (AnnotationBase annotation : allAnnotations) {
            batch.add(annotation);
            if (batch.size() >= 20) {
                annotator.add(batch);
                batch.clear(); // Free memory
            }
        }
        // Handle remaining annotations
        if (!batch.isEmpty()) {
            annotator.add(batch);
        }
    }
}

### Error handling strategy

```text
```java
public boolean addAnnotationSafely(String inputPath, String outputPath) {
    try (Annotator annotator = new Annotator(inputPath)) {
        // Your annotation logic here
        annotator.save(outputPath);
        return true;
    } catch (Exception e) {
        // Log the error with context
        logger.error("Failed to annotate document: " + inputPath, e);
        
        // Clean up partial files
        try {
            Files.deleteIfExists(Paths.get(outputPath));
        } catch (IOException cleanupError) {
            logger.warn("Could not clean up partial file", cleanupError);
        }
        
        return false;
    }
}

### Performance optimization tips

1. **Batch operations** – always add multiple annotations at once  
2. **Lazy loading** – only load pages you’re actually annotating  
3. **Connection pooling** – reuse `Annotator` instances when possible (with caution)  
4. **File streaming** – use streaming for very large documents  

## When to choose GroupDocs vs alternatives

GroupDocs.Annotation isn’t the only game in town. Here’s when it makes sense:

**Choose GroupDocs when:**  

- You need 50+ annotation types across 50+ document formats  
- You require enterprise‑level support and detailed documentation  
- You are building a commercial application and need a clear licensing model  

**Consider alternatives when:**  

- You only need basic PDF highlighting (Apache PDFBox may suffice)  
- Budget constraints demand an open‑source solution  
- Your use case is limited to simple text markup  

## Practical applications in the real world

### Legal document review  

Law firms use area annotations to highlight contract clauses and ellipse annotations to mark disputed sections. The selective export feature creates clean summary documents for client review.

### Academic paper feedback  

Universities implement annotation systems where professors can mark student submissions with different colored annotations for grammar (red), content (blue), and structure (green).

### Software documentation review  

Development teams annotate API documentation during review cycles, using annotations to mark sections needing updates or clarification.

### Quality assurance processes  

Manufacturing companies annotate inspection reports, highlighting compliance issues and marking corrective actions with different annotation types.

## Performance considerations for large‑scale deployment

When you’re ready to handle serious workloads, keep these factors in mind:

### Memory usage optimization  

- **Document size:** a 10 MB PDF typically consumes ~50 MB of heap during processing  
- **Annotation count:** each annotation adds ~1‑2 KB of overhead  
- **Concurrent users:** plan for 100 MB+ per simultaneous annotation session  

### Processing speed benchmarks  

Based on real‑world testing:  

- Small PDF (1‑10 pages): ~100‑500 ms per annotation  
- Medium PDF (10‑50 pages): ~500 ms‑2 s per annotation  
- Large PDF (100+ pages): ~2‑10 s per annotation  

### Scaling strategies  

```text
```java
// Use thread pools for concurrent processing
ExecutorService executor = Executors.newFixedThreadPool(4);

// Process multiple documents concurrently
CompletableFuture<Void> future = CompletableFuture.runAsync(() -> {
    processDocument(documentPath);
}, executor);

## Frequently asked questions

**Q: How do I install GroupDocs.Annotation in my Java project?**  
A: Add the Maven dependency shown in the prerequisites section to your `pom.xml`, then run `mvn clean install`. Ensure the repository URL is exactly as shown above.

**Q: Can I annotate document formats other than PDF?**  
A: Yes! GroupDocs.Annotation supports 50+ formats, including Word, Excel, PowerPoint, and image files. The API remains largely the same across formats.

**Q: What annotation types are available besides area and ellipse?**  
A: GroupDocs supports 15+ types such as text highlights, underlines, strikeouts, arrows, watermarks, text replacement, and point annotations. Each type has specific styling options.

**Q: How do I handle large PDF files without running out of memory?**  
A: Process documents in chunks, increase JVM heap (`-Xmx4g`), use streaming where possible, and always close `Annotator` instances. For files over 100 MB, consider processing pages individually.

**Q: Is there a way to customize annotation appearance beyond basic colors?**  
A: Absolutely. You can customize opacity, border styles, text properties, and even add custom icons. Each annotation type exposes extensive styling setters.

**Related resources:** [GroupDocs.Annotation Documentation](https://docs.groupdocs.com/annotation/java/) | [Complete API Reference](https://apireference.groupdocs.com/annotation/java) | [GroupDocs Community Forum](https://forum.groupdocs.com/c/annotation)

---

**Last Updated:** 2026-10-16  
**Tested with:** GroupDocs.Annotation 25.2  
**Author:** GroupDocs

## Related Tutorials

- [Add Arrow PDF in Java – Complete GroupDocs Tutorial](/annotation/java/graphical-annotations/annotate-pdf-arrows-groupdocs-java/)
- [Add Checkbox Annotations Pdf Groupdocs Java](/annotation/java/form-field-annotations/add-checkbox-annotations-pdf-groupdocs-java/)
- [Edit PDF Annotations Java - Complete GroupDocs Tutorial](/annotation/java/annotation-management/groupdocs-annotation-java-modify-pdf-annotations/)