Document Format Registry¶

This page explains the concept of the document format registry used by JODConverter’s Java library. If you are new to JODConverter, start with the Java Library overview, then come back here for details about how formats are defined and found during a conversion.

What is a Document Format?¶

A DocumentFormat describes a file type that OOo can read or write. It includes:

• Name, primary extension and alternate extensions (e.g., pdf, docx, odt, xlsx, html(htm), png…).
• Media type (MIME type).
• Optional load properties applied when opening a document of that format.
• Optional store properties per document family (TEXT, SPREADSHEET, PRESENTATION, DRAWING) used when exporting.

What is the Registry?¶

The DocumentFormatRegistry is a lookup service that maps extensions and media types to DocumentFormat descriptors, and lists the available output formats for a document family.

JODConverter ships with a comprehensive default registry covering common office, text, spreadsheet, presentation, drawing and image formats.

Core Types¶

• DocumentFormat: The immutable description of a format (org.jodconverter.core.document.DocumentFormat).
• DocumentFormatRegistry: Interface to look up formats (org.jodconverter.core.document.DocumentFormatRegistry).
• DefaultDocumentFormatRegistry: Static convenience access to the default registry and well-known constants (e.g., DefaultDocumentFormatRegistry.PDF).
• SimpleDocumentFormatRegistry: A mutable in-memory registry you can build programmatically.
• JsonDocumentFormatRegistry: A registry that can be loaded from JSON.

Default Registry¶

The default document format registry is backed by a bundled JSON file: /document-formats.json.

If a /custom-document-formats.json is present on the application classpath, it is automatically loaded and merged on top of the defaults (overrides existing formats or adds new ones).

Typical Usage¶

• Let JODConverter pick formats automatically by file extension: If you pass File or stream with an explicit target format, converters will use the registry to resolve the correct configuration.
• Query formats yourself: Access by extension or media type

import org.jodconverter.core.document.DefaultDocumentFormatRegistry;
import org.jodconverter.core.document.DocumentFormat;
import org.jodconverter.core.document.DocumentFormatRegistry;

DocumentFormatRegistry registry = DefaultDocumentFormatRegistry.getInstance();
DocumentFormat pdf = registry.getFormatByExtension("pdf");
DocumentFormat docx = registry.getFormatByMediaType("application/vnd.openxmlformats-officedocument.wordprocessingml.document");

• List available output formats for a given family

import org.jodconverter.core.document.DefaultDocumentFormatRegistry;
import org.jodconverter.core.document.DocumentFamily;

var outputForText = DefaultDocumentFormatRegistry.getInstance().getOutputFormats(DocumentFamily.TEXT);

Custom Registry¶

Both LocalConverter and RemoteConverter accept a format registry in their builder.

import org.jodconverter.core.document.DocumentFormatRegistry;
import org.jodconverter.core.document.JsonDocumentFormatRegistry;
import org.jodconverter.local.LocalConverter;

// Example: load additional/overridden formats from a JSON string or stream
DocumentFormatRegistry custom = JsonDocumentFormatRegistry.create(jsonInputStream);

LocalConverter converter = LocalConverter.builder()
    .formatRegistry(custom) // use your registry
    .build();

Formats of the office¶

The default registry describes the common formats, not every format an office can write: converting to epub, webp or docm, for example, fails with "The target format is missing or not supported". OfficeFormatRegistry (local module) completes a registry with the formats of the office itself, built from the filters the office says it has:

import org.jodconverter.local.office.OfficeFormatRegistry;
import org.jodconverter.local.office.OfficeInfo;
import org.jodconverter.local.task.OfficeInfoTask;

OfficeInfo info = OfficeInfoTask.query(officeManager); // once, the manager being started

LocalConverter converter = LocalConverter.builder()
    .officeManager(officeManager)
    .formatRegistry(OfficeFormatRegistry.create(info))
    .build();

converter.convert(new File("book.odt")).to(new File("book.epub")).execute();

OfficeFormatRegistry.create(info) completes the default registry, and create(registry, info) any other. The completed registry always wins: its formats carry choices the office does not tell, such as the filter options of a text file. A format taken from the office has, for each family of documents, the export filter that writes the extension; when the office has several, the first by name is taken, so describe the format in a registry of your own when another one is wanted. jodconverter-cli --info lists the filters and their extensions.

Spring Boot¶

With the Spring Boot starter, one registry is shared by every converter it creates, local, external or remote, and is also exposed as the documentFormatRegistry bean. It is configured under jodconverter.document-formats:

jodconverter:
  document-formats:
    registry: classpath:my-document-formats.json   # defaults to the registry shipped with JODConverter
    options:                                        # load/store properties added to a format, by extension
      txt:
        load:
          FilterOptions: utf16
        store:
          TEXT:
            FilterOptions: utf16

A classpath:custom-document-formats.json resource, if present, is added to the registry. An application that declares its own DocumentFormatRegistry bean replaces the one of the starter.

Programmatic Customization¶

Build a registry in code when you only need a few tweaks:

import org.jodconverter.core.document.*;

SimpleDocumentFormatRegistry reg = new SimpleDocumentFormatRegistry();

DocumentFormat myPdf = DocumentFormat.builder()
    .name("PDF-A1")
    .extension("pdf")
    .mediaType("application/pdf")
    // Customize store properties for TEXT family (export as PDF/A-1)
    .storeProperty(DocumentFamily.TEXT, "FilterName", "writer_pdf_Export")
    .storeProperty(DocumentFamily.TEXT, "SelectPdfVersion", 1)
    .build();

reg.addFormat(myPdf);

Overriding the Default Registry¶

If you prefer to change the global default returned by DefaultDocumentFormatRegistry.getInstance(), which the converters use when no registry is given to their builder, set the instance before anything uses it. The constants of DefaultDocumentFormatRegistry (PDF, DOCX...) are read once, when that class is loaded, so set it before they are touched too:

import org.jodconverter.core.document.*;

DefaultDocumentFormatRegistryInstanceHolder.setInstance(registry);

Load/Store Property Precedence¶

Load properties used when opening a document are determined as follows:

1. Input DocumentFormat load properties (from the registry), then
2. Converter default load properties (Hidden=true, ReadOnly=true, UpdateDocMode=NO_UPDATE unless configured otherwise), then
3. Explicit per-converter loadProperty/loadProperties you set in the builder

Store properties used when saving the output are determined as follows:

1. Target DocumentFormat store properties (from the registry), then
2. Explicit per-converter storeProperty/storeProperties you set in the builder

Where to put custom JSON¶

• Place custom-document-formats.json on your application’s runtime classpath (e.g., in src/main/resources) to have it automatically merged with the defaults
• Or load any JSON at runtime and pass a JsonDocumentFormatRegistry instance to your converter

Troubleshooting¶

If a format cannot be resolved, ensure the extension is correct and present in the registry.

For advanced PDF export options (bookmarks, PDF/A, tagged PDF, etc.), set the corresponding store properties on the target DocumentFormat or via converter.storeProperty.

Related Pages¶

• Getting Started: Supported Formats
• Getting Started: Document Converters

Whenever OpenOffice.org (OOo for short) is mentioned, this can generally be interpreted to include any office suite derived from OOo such as Apache OpenOffice and LibreOffice.