How to Work with Excel Document Properties in Java

Document properties, often called metadata, are descriptive fields embedded within an Excel file. They include details such as author name, title, subject, keywords, and more. Managing these properties programmatically helps organize files, improves searchability in document management systems, and ensures consistency across batches of generated reports.

This article explains how to add, read, and modify document properties in Excel files using Spire.XLS for Java, covering both built-in and custom properties.

Project Setup

To use Spire.XLS for Java in a Maven project, add the following repository and dependency to your pom.xml file:

<repositories>
    <repository>
        <id>com.e-iceblue</id>
        <name>e-iceblue</name>
        <url>https://repo.e-iceblue.com/nexus/content/groups/public/</url>
    </repository>
</repositories>
<dependencies>
    <dependency>
        <groupId>e-iceblue</groupId>
        <artifactId>spire.xls</artifactId>
        <version>16.4.1</version>
    </dependency>
</dependencies>

Refresh your project to download the required JAR files. The library requires Java 8 or later. A free version is available with a limit on the number of worksheets per workbook; a paid license removes this restriction.

Types of Document Properties

Excel supports two categories of document properties:

• Built-in properties: Standard fields defined by the Excel specification, such as Title, Subject, Author, Manager, Company, Category, Keywords, and Comments. These are visible in the File Info panel of Excel.
• Custom properties: User-defined key-value pairs you create for specific metadata needs. They can store information like a document ID, approval status, revision number, or department code.

Both types are stored within the Excel file and remain with it when shared or archived.

Adding Built-in Document Properties

Built-in properties are accessed through the DocumentProperties object associated with a workbook. The following example sets several common built-in fields on a new Excel file:

import com.spire.xls.*;

public class AddBuiltInProperties {
    public static void main(String[] args) {
        // Create a new workbook
        Workbook workbook = new Workbook();

        // Add a worksheet and put sample data in a cell
        Worksheet sheet = workbook.getWorksheets().get(0);
        sheet.getCellRange("A1").setValue("Sample Data");

        // Access document properties
        DocumentProperties properties = workbook.getDocumentProperties();

        // Set built-in properties
        properties.setAuthor("Jane Doe");
        properties.setTitle("Quarterly Sales Report");
        properties.setSubject("Sales Data for Q1 2026");
        properties.setManager("John Smith");
        properties.setCompany("Acme Corporation");
        properties.setCategory("Financial");
        properties.setKeywords("sales, quarterly, report, 2026");
        properties.setComments("Generated automatically by the reporting system");

        // Save the file
        workbook.saveToFile("output/WithProperties.xlsx", ExcelVersion.Version2016);
        workbook.dispose();
    }
}

Key points about this code:

• getDocumentProperties() returns the properties collection for the workbook.
• Individual setter methods such as setAuthor(), setTitle(), and setCompany() write values to the corresponding built-in fields.
• Properties are saved along with the sheet data when saveToFile() is called.

Adding Custom Document Properties

Custom properties store metadata beyond the predefined built-in set. Each custom property consists of a name, a value, and a data type. The library supports string, numeric, date, and boolean custom property types.

Here is an example that adds several custom properties to a workbook:

import com.spire.xls.*;

public class AddCustomProperties {
    public static void main(String[] args) {
        // Create a new workbook
        Workbook workbook = new Workbook();
        Worksheet sheet = workbook.getWorksheets().get(0);
        sheet.getCellRange("A1").setValue("Document with Custom Properties");

        // Add custom document properties
        workbook.getCustomDocumentProperties().add("DocumentID", "DOC-2026-0042");
        workbook.getCustomDocumentProperties().add("ApprovalStatus", "Approved");
        workbook.getCustomDocumentProperties().add("RevisionNumber", 3);
        workbook.getCustomDocumentProperties().add("ProcessedDate", new java.util.Date());
        workbook.getCustomDocumentProperties().add("IsConfidential", true);

        // Save the file
        workbook.saveToFile("output/CustomProperties.xlsx", ExcelVersion.Version2016);
        workbook.dispose();
    }
}

Important details about custom properties:

• The add() method accepts a property name and a value. The data type is inferred from the Java type of the value you pass.
• Property names must be unique within a workbook. Adding a property with an existing name overwrites the previous value.
• Custom properties are persisted in the file and can be read by other applications that support Excel metadata.

Reading Existing Document Properties

You can also retrieve properties from an existing Excel file. Built-in and custom properties use different access patterns, as shown in this example:

import com.spire.xls.*;
import com.spire.xls.core.spreadsheet.collections.XlsCustomDocumentPropertiesCollection;

public class ReadProperties {
    public static void main(String[] args) {
        // Load an existing workbook
        Workbook workbook = new Workbook();
        workbook.loadFromFile("output/WithProperties.xlsx");

        // Read built-in properties
        DocumentProperties properties = workbook.getDocumentProperties();
        System.out.println("=== Built-in Properties ===");
        System.out.println("Author: " + properties.getAuthor());
        System.out.println("Title: " + properties.getTitle());
        System.out.println("Subject: " + properties.getSubject());
        System.out.println("Manager: " + properties.getManager());
        System.out.println("Company: " + properties.getCompany());
        System.out.println("Category: " + properties.getCategory());
        System.out.println("Keywords: " + properties.getKeywords());
        System.out.println("Comments: " + properties.getComments());

        // Read custom properties
        System.out.println("\n=== Custom Properties ===");
        XlsCustomDocumentPropertiesCollection customProps = workbook.getCustomDocumentProperties();
        for (int i = 0; i < customProps.getCount(); i++) {
            String name = customProps.get(i).getName();
            Object value = customProps.get(i).getValue();
            System.out.println(name + ": " + value);
        }

        workbook.dispose();
    }
}

A sample output from this code would look like:

=== Built-in Properties ===
Author: Jane Doe
Title: Quarterly Sales Report
Subject: Sales Data for Q1 2026
Manager: John Smith
Company: Acme Corporation
Category: Financial
Keywords: sales, quarterly, report, 2026
Comments: Generated automatically by the reporting system

=== Custom Properties ===
DocumentID: DOC-2026-0042
ApprovalStatus: Approved
RevisionNumber: 3
ProcessedDate: Sun Jun 01 14:30:00 EDT 2026
IsConfidential: true

The getCustomDocumentProperties() method returns a collection you can iterate through to access each property's name and value. The getCount() method gives the number of custom properties, and get(index) retrieves an individual property by its position.

Updating Existing Properties

Modifying properties in an existing file follows the same pattern as adding them. Load the workbook, call the relevant setter or add method, and save:

// Update a built-in property
properties.setAuthor("Updated Author Name");

// Update a custom property (using add with an existing name overwrites the value)
workbook.getCustomDocumentProperties().add("ApprovalStatus", "Pending Review");

For custom properties, calling add() with an existing property name replaces the previous value. There is no separate update method.

Practical Use Cases

Programmatic management of document properties supports several real-world scenarios:

• Document classification: Set categories and keywords to make files easier to locate in document management systems.
• Audit information: Store processing dates, revision numbers, and approval statuses directly within the file.
• Batch consistency: Apply uniform metadata across hundreds of auto-generated reports without manual intervention.
• Regulatory requirements: Embed required metadata fields to meet organizational or compliance standards.

Alternative Libraries for Excel Metadata

Several other Java libraries can handle Excel document properties:

Library	License	Notes
Apache POI	Apache 2.0 (open source)	Accesses document summary information through its HPSF module; requires more low-level code for some operations
Aspose.Cells	Commercial	Supports built-in and custom properties with a similar API design
JExcelApi	LGPL (open source)	Limited to the older .xls format; does not support .xlsx files

Apache POI can read and write document properties, though the API involves working with POIFS file system components for certain property operations. Aspose.Cells provides comparable functionality under a commercial license. JExcelApi is restricted to legacy Excel formats and is not suitable for modern .xlsx workflows.

Conclusion

Working with Excel document properties through Spire.XLS for Java involves two main interfaces: the DocumentProperties object for built-in metadata fields like author, title, and subject, and the CustomDocumentProperties collection for user-defined key-value pairs that can store strings, numbers, dates, and boolean values. Both types of properties can be written when creating new files and read back from existing workbooks using straightforward getter and setter methods. These capabilities are particularly useful in automated reporting pipelines where consistent metadata helps with file organization, searchability, and compliance. Developers considering this library should evaluate whether the free version's worksheet limits align with their document volumes and whether the property-handling API covers the metadata fields their workflows require. For more advanced scenarios, the library's documentation also covers applying properties to password-protected files and working with additional built-in fields beyond those shown here.