PDF Options¶

PdfOptions sets the options of a conversion to PDF with plain Java methods, so you don't have to know the names and values of the FilterData properties of the office PDF export filter. It works with the local and the remote converters.

// A preset for the common cases
converter.convert(source).to(target).with(PdfOptions.archive()).execute();

// Or built step by step
PdfOptions options =
    PdfOptions.builder()
        .version(PdfVersion.PDF_A_2B)
        .tagged(true)
        .images(images -> images.jpegQuality(85).maxResolution(300))
        .pages(pages -> pages.range("1-5"))
        .watermark(watermark -> watermark.text("DRAFT"))
        .build();

converter.convert(source).to(target).with(options).execute();

The options apply to that conversion only. With a target that is not a PDF document, execute() throws an IllegalArgumentException. When the target is an OutputStream, give the format first: .to(outputStream).as(DefaultDocumentFormatRegistry.PDF).with(options).

Presets¶

A preset is a starting point: PdfOptions.archive().toBuilder().pages(pages -> pages.range("1-3")).build().

What you need to know¶

• Only the options you set are sent. Empty options (PdfOptions.builder().build()) change nothing.
• Office versions. An office installation silently ignores an option it does not know. The tables below give the first version that supports each option, and the local converter logs a warning for each option the running office is too old for. "all" means every LibreOffice version and Apache OpenOffice.
• Invalid combinations. build() throws an IllegalArgumentException for options that cannot work together: a password with a PDF/A version (the office would silently produce a document that is not encrypted), a permission without a permission password, PDF/UA with tagged(false), or signature details without a certificate.
• Precedence. The options are merged into the FilterData set on the target format and on the converter, and win when both set the same property.
• Remote conversions. The options are sent as request parameters, like the other store properties. Only servers that support custom properties, such as the JODConverter sample REST service, use them; LibreOffice Online and Collabora ignore them. Passwords are then part of the request URL, so prefer a local conversion for them.

Options¶

General¶

An office installation that does not know a version produces its default PDF version instead.

Images: images(...)¶

Pages: pages(...)¶

Comments: comments(...)¶

Bookmarks: bookmarks(...)¶

Forms: forms(...)¶

Links: links(...)¶

Initial view: initialView(...)¶

Viewer window: viewer(...)¶

Security: security(...)¶

The permissions (the last four options) require a permission password. PDF/A does not allow encryption.

PdfOptions.builder()
    .security(security -> security
        .openPassword("to-open")
        .permissionPassword("to-change-permissions")
        .printing(Printing.LOW_RESOLUTION)
        .copying(false))
    .build();

Watermark: watermark(...)¶

Digital signature: signature(...)¶

certificateSubjectName takes the certificate, by its subject name such as "CN=My Company", from the certificate store used by the office installation: the Windows certificate store on Windows, an NSS database on Linux (the MOZILLA_CERTIFICATE_FOLDER environment variable of the office process can point to it). certificatePem needs no certificate store. When the certificate cannot be found or used, the conversion fails with an OfficeException.

LibreOffice versions older than 7.4 can only sign with a certificate object given through the SignatureCertificate property; set it with filterData("SignatureCertificate", certificate) and filterData("SignPDF", true).

Presentations (Impress): presentation(...)¶

Spreadsheets (Calc): spreadsheet(...)¶

LibreOffice ignores sheetRange when singlePageSheets is set. With an .xlsx workbook, singlePageSheets may leave out the top rows or the first columns of a sheet that was saved scrolled; see the known LibreOffice issues.

Any other property¶

filterData(name, value) sets any FilterData property that has no dedicated method. These properties are applied last and are not validated.

PdfOptions.builder().filterData("ExportNotesInMargin", true).build();

Options by name¶

option(name, value) applies an option given by its name and its text value, the way the command line and the Spring Boot properties do: images.jpeg-quality=80, security.printing=low-resolution, version=a-2b. It is the way to apply options read from a configuration file of your own. The names are those of the command line table below, except that the certificate, the private key and the certificate authorities of a signature are given as PEM text, with signature.certificate, signature.private-key (which must be used together) and signature.ca; PdfOptions.optionNames() lists them. An unknown name or a value that is not valid throws an IllegalArgumentException.

PdfOptions.archive().toBuilder()
    .option("pages.range", "1-3")
    .option("watermark.color", "#FF0000")
    .build();

Default options of a converter¶

A converter can apply the same options to all its conversions to PDF:

DocumentConverter converter =
    LocalConverter.builder()
        .officeManager(officeManager)
        .defaultTargetOptions(PdfOptions.archive())
        .build();

converter.convert(source).to(target).execute();   // PDF/A-2b

The default options only apply to the conversions whose target is a PDF document. Options given to a conversion with with(...) replace them entirely for that conversion; they are not merged.

Spring Boot¶

With the Spring Boot starter, the jodconverter.pdf properties set the default PDF options of the auto-configured converters (local, external and remote):

jodconverter:
  local:
    enabled: true
  pdf:
    preset: archive
    pages:
      skip-empty-pages: true
    watermark:
      text: DRAFT

• preset is archive, accessible or compact; the other properties are applied on top of it.
• The properties have the names of the command line options: jodconverter.pdf.tagged, jodconverter.pdf.images.jpeg-quality, jodconverter.pdf.security.open-password... Your IDE completes them, with their description.
• A choice is the name of the constant, in any of the forms Spring Boot accepts: low-resolution, LOW_RESOLUTION. The version is pdf-1-7, pdf-2-0, pdf-a-2b...
• The certificates of the signature are Spring resources, in the PEM format: jodconverter.pdf.signature.certificate, jodconverter.pdf.signature.private-key (used together) and jodconverter.pdf.signature.certificate-authorities, such as classpath:signing/certificate.pem or file:/etc/signing/key.pem.
• jodconverter.pdf.filter-data.<property> sets any other property.
• Properties that are not valid, or that cannot be used together, prevent the application from starting.

The starter creates a PdfOptions bean from these properties, only when at least one of them is set. To build the options in Java instead, define your own PdfOptions bean: the auto-configured converters use it the same way, and the properties are then ignored.

@Bean
PdfOptions pdfOptions() {
  return PdfOptions.archive().toBuilder().watermark(watermark -> watermark.text("DRAFT")).build();
}

A conversion can still use other options with with(...).

Command line¶

The command line tool takes a preset with --pdf-preset (archive, accessible or compact) and any option with --pdf-option name=value, which can be repeated:

jodconverter-cli --pdf-preset archive --pdf-option pages.range=1-3 in.docx out.pdf
jodconverter-cli --pdf-option version=1.7 --pdf-option tagged=true --pdf-option security.open-password=secret in.docx out.pdf

The name of an option is the name of its method, in lower case with hyphens, after the name of its group:

The values:

• Yes or no: true or false.
• A choice: the name of the constant, in any case, with hyphens or underscores: security.printing=low-resolution, initial-view.magnification=fit-width.
• version: 1.5, 1.6, 1.7, 2.0, a-1b, a-2b, a-3b, a-4 or default.
• watermark.color: an RGB value such as FF0000.
• The signature files: signature.certificate-file and signature.private-key-file are the paths of the certificate and of its private key, in the PEM format, and must be used together; signature.ca-file is the path of the certificates of the certificate authorities.

An unknown name, a value that is not valid, or options that cannot be used together stop the tool before any conversion, with an error message and the exit status 255. A password given on a command line can be seen by the other users of the machine, in the list of the running processes.

How the options were tested¶

Each option was converted with a real office installation, and the PDF document it produced was inspected (document catalog, encryption permissions, annotations, form fields, images, page content, signature) to check that the option had its effect:

• LibreOffice 25.2.7 and 26.2.6 on Windows: every option, except the digital signature.
• LibreOffice 26.2.6 on Linux: the digital signature, by subject name and with a PEM certificate, with its location, reason and contact information.
• Not tested: the password and timestampAuthority options of the signature, the effect of caPem, and the signature by subject name on Windows. No option was tested with Apache OpenOffice or with LibreOffice versions older than 25.2.

The integration tests of JODConverter repeat these checks at each build, except for the digital signature, with the office installed on the build machine.

One option of the export filter is not offered: FirstPageOnLeft. Every version of LibreOffice and OpenOffice reads it and then discards it, so it never has any effect.

How the versions were established¶

The "Requires" columns come from the source code of the PDF export filter (filter/source/pdf/pdfexport.cxx) of every LibreOffice release branch from 3.5 to 26.8, and of Apache OpenOffice 4.1: an option requires the first version whose filter reads it. This tells when an option started to exist, not how well it worked at the time.