MACRO NEPAL
Building a Custom PDF Viewer with Apache PDFBox in Java
awiskar acharya
November 15, 2025
3:48 am

While many Java applications rely on external PDF viewers or browser components, there are scenarios where you need embedded, customizable PDF viewing capabilities. Apache PDFBox provides powerful tools not just for PDF creation and manipulation, but also for building custom PDF viewers. This article explores how to create a fully-featured PDF viewer using PDFBox, from basic rendering to advanced features like text selection and search.

Why Build a Custom PDF Viewer?

Common Use Cases:

  • Embedded document viewing in enterprise applications
  • Custom annotation and markup requirements
  • Offline PDF viewing capabilities
  • Branded document reader applications
  • Specialized document processing workflows

Advantages of PDFBox:

  • Pure Java solution (no native dependencies)
  • Open source and actively maintained
  • Extensive PDF manipulation capabilities
  • Good performance for most use cases
  • Customizable rendering pipeline

Setting Up Dependencies

Maven:

<dependencies>
<dependency>
<groupId>org.apache.pdfbox</groupId>
<artifactId>pdfbox</artifactId>
<version>3.0.1</version>
</dependency>
<dependency>
<groupId>org.apache.pdfbox</groupId>
<artifactId>pdfbox-tools</artifactId>
<version>3.0.1</version>
</dependency>
</dependencies>

Gradle:

dependencies {
implementation 'org.apache.pdfbox:pdfbox:3.0.1'
implementation 'org.apache.pdfbox:pdfbox-tools:3.0.1'
}

Basic PDF Viewer Implementation

Let's start with a simple PDF viewer that displays one page at a time.

Basic PDF Viewer Class:

import org.apache.pdfbox.pdmodel.PDDocument;
import org.apache.pdfbox.rendering.PDFRenderer;
import javax.swing.*;
import java.awt.*;
import java.awt.image.BufferedImage;
import java.io.File;
import java.io.IOException;
public class BasicPDFViewer extends JFrame {
private PDDocument document;
private PDFRenderer renderer;
private int currentPage = 0;
private JLabel imageLabel;
private JScrollPane scrollPane;
public BasicPDFViewer() {
initializeUI();
}
private void initializeUI() {
setTitle("PDF Viewer - Apache PDFBox");
setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
setSize(800, 1000);
setLocationRelativeTo(null);
// Create components
imageLabel = new JLabel();
imageLabel.setHorizontalAlignment(SwingConstants.CENTER);
scrollPane = new JScrollPane(imageLabel);
scrollPane.setHorizontalScrollBarPolicy(JScrollPane.HORIZONTAL_SCROLLBAR_AS_NEEDED);
scrollPane.setVerticalScrollBarPolicy(JScrollPane.VERTICAL_SCROLLBAR_AS_NEEDED);
add(scrollPane, BorderLayout.CENTER);
// Create toolbar
JToolBar toolBar = createToolbar();
add(toolBar, BorderLayout.NORTH);
// Create status bar
JLabel statusLabel = new JLabel("No document loaded");
add(statusLabel, BorderLayout.SOUTH);
}
private JToolBar createToolbar() {
JToolBar toolBar = new JToolBar();
JButton openButton = new JButton("Open PDF");
openButton.addActionListener(e -> openPDF());
JButton prevButton = new JButton("Previous");
prevButton.addActionListener(e -> showPreviousPage());
JButton nextButton = new JButton("Next");
nextButton.addActionListener(e -> showNextPage());
JButton zoomInButton = new JButton("Zoom In");
zoomInButton.addActionListener(e -> zoomIn());
JButton zoomOutButton = new JButton("Zoom Out");
zoomOutButton.addActionListener(e -> zoomOut());
toolBar.add(openButton);
toolBar.addSeparator();
toolBar.add(prevButton);
toolBar.add(nextButton);
toolBar.addSeparator();
toolBar.add(zoomInButton);
toolBar.add(zoomOutButton);
return toolBar;
}
public void openPDF() {
JFileChooser fileChooser = new JFileChooser();
fileChooser.setFileFilter(new javax.swing.filechooser.FileNameExtensionFilter(
"PDF Files", "pdf"));
if (fileChooser.showOpenDialog(this) == JFileChooser.APPROVE_OPTION) {
File file = fileChooser.getSelectedFile();
loadPDF(file);
}
}
private void loadPDF(File file) {
try {
// Close previous document
if (document != null) {
document.close();
}
// Load new document
document = PDDocument.load(file);
renderer = new PDFRenderer(document);
currentPage = 0;
setTitle("PDF Viewer - " + file.getName());
showPage(currentPage);
} catch (IOException ex) {
JOptionPane.showMessageDialog(this, 
"Error loading PDF: " + ex.getMessage(), 
"Error", JOptionPane.ERROR_MESSAGE);
}
}
private void showPage(int pageNumber) {
if (document == null || pageNumber < 0 || pageNumber >= document.getNumberOfPages()) {
return;
}
try {
// Render page to image
BufferedImage image = renderer.renderImage(pageNumber, 1.0f);
ImageIcon icon = new ImageIcon(image);
imageLabel.setIcon(icon);
// Update status
updateStatus(pageNumber);
} catch (IOException ex) {
JOptionPane.showMessageDialog(this, 
"Error rendering page: " + ex.getMessage(), 
"Error", JOptionPane.ERROR_MESSAGE);
}
}
private void showPreviousPage() {
if (currentPage > 0) {
currentPage--;
showPage(currentPage);
}
}
private void showNextPage() {
if (document != null && currentPage < document.getNumberOfPages() - 1) {
currentPage++;
showPage(currentPage);
}
}
private void zoomIn() {
// Zoom implementation would go here
JOptionPane.showMessageDialog(this, "Zoom In feature to be implemented");
}
private void zoomOut() {
// Zoom implementation would go here
JOptionPane.showMessageDialog(this, "Zoom Out feature to be implemented");
}
private void updateStatus(int pageNumber) {
int totalPages = document != null ? document.getNumberOfPages() : 0;
String status = String.format("Page %d of %d", pageNumber + 1, totalPages);
// Find and update status label
for (Component comp : getContentPane().getComponents()) {
if (comp instanceof JLabel && ((JLabel) comp).getText().contains("Page")) {
((JLabel) comp).setText(status);
break;
}
}
}
@Override
public void dispose() {
if (document != null) {
try {
document.close();
} catch (IOException e) {
e.printStackTrace();
}
}
super.dispose();
}
public static void main(String[] args) {
SwingUtilities.invokeLater(() -> {
new BasicPDFViewer().setVisible(true);
});
}
}

Advanced PDF Viewer with Zoom and Navigation

Let's enhance our viewer with better zoom capabilities and thumbnail navigation.

Enhanced PDF Viewer:

import org.apache.pdfbox.pdmodel.PDDocument;
import org.apache.pdfbox.rendering.PDFRenderer;
import javax.swing.*;
import javax.swing.event.ChangeEvent;
import javax.swing.event.ChangeListener;
import java.awt.*;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseEvent;
import java.awt.image.BufferedImage;
import java.io.File;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
public class EnhancedPDFViewer extends JFrame {
private PDDocument document;
private PDFRenderer renderer;
private int currentPage = 0;
private float zoomFactor = 1.0f;
private JLabel imageLabel;
private JScrollPane scrollPane;
private JPanel thumbnailsPanel;
private List<JLabel> thumbnailLabels;
public EnhancedPDFViewer() {
initializeUI();
}
private void initializeUI() {
setTitle("Enhanced PDF Viewer");
setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
setSize(1200, 800);
setLocationRelativeTo(null);
// Create main split pane
JSplitPane splitPane = new JSplitPane(JSplitPane.HORIZONTAL_SPLIT);
splitPane.setDividerLocation(200);
// Thumbnails panel
thumbnailsPanel = new JPanel();
thumbnailsPanel.setLayout(new BoxLayout(thumbnailsPanel, BoxLayout.Y_AXIS));
JScrollPane thumbnailsScroll = new JScrollPane(thumbnailsPanel);
thumbnailsScroll.setPreferredSize(new Dimension(180, 0));
// Main content area
imageLabel = new JLabel();
imageLabel.setHorizontalAlignment(SwingConstants.CENTER);
scrollPane = new JScrollPane(imageLabel);
splitPane.setLeftComponent(thumbnailsScroll);
splitPane.setRightComponent(scrollPane);
add(splitPane, BorderLayout.CENTER);
// Create enhanced toolbar
add(createEnhancedToolbar(), BorderLayout.NORTH);
add(createStatusBar(), BorderLayout.SOUTH);
thumbnailLabels = new ArrayList<>();
}
private JToolBar createEnhancedToolbar() {
JToolBar toolBar = new JToolBar();
JButton openButton = new JButton("Open");
openButton.addActionListener(e -> openPDF());
JButton prevButton = new JButton("◀");
prevButton.addActionListener(e -> showPreviousPage());
JButton nextButton = new JButton("▶");
nextButton.addActionListener(e -> showNextPage());
JButton zoomInButton = new JButton("Zoom In");
zoomInButton.addActionListener(e -> setZoom(zoomFactor * 1.2f));
JButton zoomOutButton = new JButton("Zoom Out");
zoomOutButton.addActionListener(e -> setZoom(zoomFactor / 1.2f));
JButton fitWidthButton = new JButton("Fit Width");
fitWidthButton.addActionListener(e -> fitToWidth());
JButton actualSizeButton = new JButton("100%");
actualSizeButton.addActionListener(e -> setZoom(1.0f));
// Zoom slider
JSlider zoomSlider = new JSlider(25, 400, 100);
zoomSlider.addChangeListener(e -> {
if (!zoomSlider.getValueIsAdjusting()) {
setZoom(zoomSlider.getValue() / 100.0f);
}
});
toolBar.add(openButton);
toolBar.addSeparator();
toolBar.add(prevButton);
toolBar.add(nextButton);
toolBar.addSeparator();
toolBar.add(zoomOutButton);
toolBar.add(zoomInButton);
toolBar.add(fitWidthButton);
toolBar.add(actualSizeButton);
toolBar.addSeparator();
toolBar.add(new JLabel("Zoom:"));
toolBar.add(zoomSlider);
return toolBar;
}
private JPanel createStatusBar() {
JPanel statusPanel = new JPanel(new BorderLayout());
JLabel statusLabel = new JLabel("No document loaded");
statusLabel.setBorder(BorderFactory.createLoweredBevelBorder());
statusPanel.add(statusLabel, BorderLayout.CENTER);
return statusPanel;
}
private void openPDF() {
JFileChooser fileChooser = new JFileChooser();
fileChooser.setFileFilter(new javax.swing.filechooser.FileNameExtensionFilter(
"PDF Files", "pdf"));
if (fileChooser.showOpenDialog(this) == JFileChooser.APPROVE_OPTION) {
loadPDF(fileChooser.getSelectedFile());
}
}
private void loadPDF(File file) {
try {
// Close previous document
if (document != null) {
document.close();
}
// Load new document
document = PDDocument.load(file);
renderer = new PDFRenderer(document);
currentPage = 0;
zoomFactor = 1.0f;
setTitle("Enhanced PDF Viewer - " + file.getName());
showPage(currentPage);
generateThumbnails();
} catch (IOException ex) {
JOptionPane.showMessageDialog(this, 
"Error loading PDF: " + ex.getMessage(), 
"Error", JOptionPane.ERROR_MESSAGE);
}
}
private void showPage(int pageNumber) {
if (document == null || pageNumber < 0 || pageNumber >= document.getNumberOfPages()) {
return;
}
try {
// Render page with current zoom factor
BufferedImage image = renderer.renderImage(pageNumber, zoomFactor);
ImageIcon icon = new ImageIcon(image);
imageLabel.setIcon(icon);
currentPage = pageNumber;
updateThumbnailSelection();
updateStatus();
} catch (IOException ex) {
JOptionPane.showMessageDialog(this, 
"Error rendering page: " + ex.getMessage(), 
"Error", JOptionPane.ERROR_MESSAGE);
}
}
private void generateThumbnails() {
thumbnailsPanel.removeAll();
thumbnailLabels.clear();
if (document == null) return;
try {
int totalPages = document.getNumberOfPages();
for (int i = 0; i < totalPages; i++) {
// Render thumbnail (small version)
BufferedImage thumbImage = renderer.renderImage(i, 0.2f);
ImageIcon thumbIcon = new ImageIcon(thumbImage);
JLabel thumbLabel = new JLabel(thumbIcon);
thumbLabel.setText("Page " + (i + 1));
thumbLabel.setVerticalTextPosition(SwingConstants.BOTTOM);
thumbLabel.setHorizontalTextPosition(SwingConstants.CENTER);
thumbLabel.setBorder(BorderFactory.createEmptyBorder(5, 5, 5, 5));
final int pageIndex = i;
thumbLabel.addMouseListener(new MouseAdapter() {
@Override
public void mouseClicked(MouseEvent e) {
showPage(pageIndex);
}
});
thumbnailsPanel.add(thumbLabel);
thumbnailLabels.add(thumbLabel);
}
thumbnailsPanel.revalidate();
thumbnailsPanel.repaint();
updateThumbnailSelection();
} catch (IOException ex) {
ex.printStackTrace();
}
}
private void updateThumbnailSelection() {
for (int i = 0; i < thumbnailLabels.size(); i++) {
JLabel thumbLabel = thumbnailLabels.get(i);
if (i == currentPage) {
thumbLabel.setBorder(BorderFactory.createLineBorder(Color.BLUE, 2));
} else {
thumbLabel.setBorder(BorderFactory.createEmptyBorder(5, 5, 5, 5));
}
}
}
private void setZoom(float newZoom) {
if (newZoom < 0.1f) newZoom = 0.1f;
if (newZoom > 5.0f) newZoom = 5.0f;
zoomFactor = newZoom;
if (document != null) {
showPage(currentPage);
}
}
private void fitToWidth() {
if (document == null || scrollPane.getViewport().getWidth() == 0) return;
try {
// Get page dimensions
float pageWidth = document.getPage(currentPage).getMediaBox().getWidth();
float viewportWidth = scrollPane.getViewport().getWidth() - 20; // Padding
zoomFactor = viewportWidth / pageWidth;
showPage(currentPage);
} catch (Exception ex) {
ex.printStackTrace();
}
}
private void showPreviousPage() {
if (currentPage > 0) {
showPage(currentPage - 1);
}
}
private void showNextPage() {
if (document != null && currentPage < document.getNumberOfPages() - 1) {
showPage(currentPage + 1);
}
}
private void updateStatus() {
int totalPages = document != null ? document.getNumberOfPages() : 0;
String status = String.format("Page %d of %d | Zoom: %.0f%%", 
currentPage + 1, totalPages, zoomFactor * 100);
// Update status bar
Component[] comps = getContentPane().getComponents();
for (Component comp : comps) {
if (comp instanceof JPanel) {
Component[] subComps = ((JPanel) comp).getComponents();
for (Component subComp : subComps) {
if (subComp instanceof JLabel) {
((JLabel) subComp).setText(status);
return;
}
}
}
}
}
@Override
public void dispose() {
if (document != null) {
try {
document.close();
} catch (IOException e) {
e.printStackTrace();
}
}
super.dispose();
}
public static void main(String[] args) {
SwingUtilities.invokeLater(() -> {
new EnhancedPDFViewer().setVisible(true);
});
}
}

Text Extraction and Search Feature

Let's add text extraction and search capabilities to our viewer.

Text Extraction and Search Panel:

import org.apache.pdfbox.pdmodel.PDDocument;
import org.apache.pdfbox.text.PDFTextStripper;
import javax.swing.*;
import java.awt.*;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
public class PDFViewerWithSearch extends EnhancedPDFViewer {
private JTextField searchField;
private JButton searchButton;
private JList<String> searchResultsList;
private DefaultListModel<String> searchResultsModel;
private List<SearchResult> allSearchResults;
public PDFViewerWithSearch() {
super();
addSearchPanel();
}
private void addSearchPanel() {
// Create search panel
JPanel searchPanel = new JPanel(new BorderLayout());
JPanel searchInputPanel = new JPanel(new FlowLayout());
searchField = new JTextField(20);
searchButton = new JButton("Search");
searchInputPanel.add(new JLabel("Search:"));
searchInputPanel.add(searchField);
searchInputPanel.add(searchButton);
searchResultsModel = new DefaultListModel<>();
searchResultsList = new JList<>(searchResultsModel);
searchResultsList.setSelectionMode(ListSelectionModel.SINGLE_SELECTION);
JScrollPane resultsScroll = new JScrollPane(searchResultsList);
resultsScroll.setPreferredSize(new Dimension(250, 150));
searchPanel.add(searchInputPanel, BorderLayout.NORTH);
searchPanel.add(resultsScroll, BorderLayout.CENTER);
// Add search panel to the left of split pane
JSplitPane mainSplitPane = (JSplitPane) getContentPane().getComponent(0);
JSplitPane leftSplitPane = new JSplitPane(JSplitPane.VERTICAL_SPLIT);
leftSplitPane.setTopComponent(mainSplitPane.getLeftComponent());
leftSplitPane.setBottomComponent(searchPanel);
leftSplitPane.setDividerLocation(400);
mainSplitPane.setLeftComponent(leftSplitPane);
setupSearchListeners();
}
private void setupSearchListeners() {
searchButton.addActionListener(e -> performSearch());
searchField.addActionListener(e -> performSearch());
searchResultsList.addListSelectionListener(e -> {
if (!e.getValueIsAdjusting() && searchResultsList.getSelectedIndex() != -1) {
navigateToSearchResult(searchResultsList.getSelectedIndex());
}
});
}
private void performSearch() {
String searchText = searchField.getText().trim();
if (searchText.isEmpty() || document == null) {
return;
}
searchResultsModel.clear();
allSearchResults = new ArrayList<>();
try {
PDFTextStripper stripper = new PDFTextStripper();
Pattern pattern = Pattern.compile(Pattern.quote(searchText), Pattern.CASE_INSENSITIVE);
for (int page = 0; page < document.getNumberOfPages(); page++) {
stripper.setStartPage(page + 1);
stripper.setEndPage(page + 1);
String pageText = stripper.getText(document);
Matcher matcher = pattern.matcher(pageText);
while (matcher.find()) {
int start = Math.max(0, matcher.start() - 50);
int end = Math.min(pageText.length(), matcher.end() + 50);
String context = pageText.substring(start, end).replaceAll("\\s+", " ").trim();
String resultText = String.format("Page %d: ...%s...", page + 1, context);
searchResultsModel.addElement(resultText);
allSearchResults.add(new SearchResult(page, matcher.start(), context));
}
}
if (searchResultsModel.isEmpty()) {
searchResultsModel.addElement("No results found");
}
} catch (IOException ex) {
JOptionPane.showMessageDialog(this, 
"Error searching document: " + ex.getMessage(), 
"Search Error", JOptionPane.ERROR_MESSAGE);
}
}
private void navigateToSearchResult(int resultIndex) {
if (allSearchResults != null && resultIndex < allSearchResults.size()) {
SearchResult result = allSearchResults.get(resultIndex);
showPage(result.page);
// Could add highlighting here
}
}
private static class SearchResult {
int page;
int position;
String context;
SearchResult(int page, int position, String context) {
this.page = page;
this.position = position;
this.context = context;
}
}
public static void main(String[] args) {
SwingUtilities.invokeLater(() -> {
new PDFViewerWithSearch().setVisible(true);
});
}
}

Performance Optimization Tips

1. Caching Rendered Pages:

public class PageCache {
private Map<Integer, BufferedImage> cache = new HashMap<>();
private PDFRenderer renderer;
private int maxCacheSize = 10;
public PageCache(PDFRenderer renderer) {
this.renderer = renderer;
}
public BufferedImage getPage(int pageNumber, float zoom) throws IOException {
int key = generateKey(pageNumber, zoom);
if (cache.containsKey(key)) {
return cache.get(key);
}
// Render and cache
BufferedImage image = renderer.renderImage(pageNumber, zoom);
// Manage cache size
if (cache.size() >= maxCacheSize) {
cache.remove(cache.keySet().iterator().next());
}
cache.put(key, image);
return image;
}
private int generateKey(int pageNumber, float zoom) {
return pageNumber * 1000 + (int)(zoom * 100);
}
public void clear() {
cache.clear();
}
}

2. Background Rendering:

private void showPageAsync(int pageNumber) {
SwingWorker<BufferedImage, Void> worker = new SwingWorker<BufferedImage, Void>() {
@Override
protected BufferedImage doInBackground() throws Exception {
return renderer.renderImage(pageNumber, zoomFactor);
}
@Override
protected void done() {
try {
BufferedImage image = get();
ImageIcon icon = new ImageIcon(image);
imageLabel.setIcon(icon);
updateStatus();
} catch (Exception ex) {
ex.printStackTrace();
}
}
};
worker.execute();
}

Best Practices

  1. Resource Management:
   // Always close documents
@Override
public void dispose() {
if (document != null) {
try {
document.close();
} catch (IOException e) {
// Log error
}
}
super.dispose();
}
  1. Error Handling:
   try {
document = PDDocument.load(file);
} catch (IOException ex) {
logger.error("Failed to load PDF", ex);
showErrorDialog("Cannot load PDF file: " + ex.getMessage());
}
  1. Memory Management:
   // For large documents, use memory mapping
PDDocument.load(new File("large.pdf"), MemoryUsageSetting.setupMixed(100 * 1024 * 1024));

Conclusion

Building a custom PDF viewer with Apache PDFBox provides:

  • Complete Control: Customize every aspect of the viewing experience
  • No External Dependencies: Pure Java solution
  • Integration Flexibility: Seamlessly embed in existing applications
  • Extensibility: Add custom features like annotation, digital signatures, or specialized rendering

While PDFBox may not match the performance of native PDF renderers for very large documents, it offers an excellent balance of features, flexibility, and ease of integration for most use cases. The examples provided in this article give you a solid foundation for building sophisticated PDF viewing applications tailored to your specific requirements.

Category : JAVA

Leave a Reply

Your email address will not be published. Required fields are marked *


Macro Nepal Helper