AttachedOfficeManager Configuration¶

The AttachedOfficeManager is the manager to use to connect to office processes that JODConverter does not start: processes started and managed outside of it, on the same machine or on another one, that accept UNO connections (soffice --accept=...). It does not restart a process that exits, but reconnects when the process is started again. It was named ExternalOfficeManager before 5.0; the old name still works, deprecated.

An AttachedOfficeManager is built using a builder:

OfficeManager officeManager = AttachedOfficeManager.builder().build();

Spring Boot¶

With the Spring Boot starter, set jodconverter.attached.enabled to true to get an AttachedOfficeManager bean named attachedOfficeManager, and a DocumentConverter bean named attachedDocumentConverter that converts through it. Each property below matches the builder property of the same name; the values shown are the defaults:

jodconverter:
  attached:
    enabled: true
    host-name: 127.0.0.1
    port-numbers: 2002              # or pipe-names / websocket-urls
    working-dir:                    # defaults to java.io.tmpdir
    connect-on-start: true
    connect-timeout: 120000
    connect-retry-interval: 250
    connect-fail-fast: false
    max-tasks-per-connection: 1000
    task-queue-capacity: 0          # no limit
    task-retries: 0                 # a task whose connection is lost fails
    task-queue-timeout: 30000
    task-execution-timeout: 120000
    apply-default-load-properties: true
    load-document-mode: auto        # remote: stream documents to an office process on another host

When the office processes run in another container or on another host, set load-document-mode to remote: the documents are then sent through the connection instead of being read from (and written to) the local file system. When the office processes run on the same host, or share a volume with the application, local is the better choice: a few export filters give an incomplete output through streams, see loadDocumentMode. The local and attached auto-configurations can be enabled together; inject the converter you need with @Qualifier("attachedDocumentConverter") or @Qualifier("localDocumentConverter").

Builder properties¶

Here are all the properties you can set through the builder:

📁workingDir¶

This property is used to create a temporary directory where files will be created when conversions are done using InputStream/OutputStream.

 Default: The system temporary directory as specified by the java.io.tmpdir system property.

NOTE that some OS automatically clean up the java.io.tmpdir directory periodically. It is recommended to check your OS to see if you have to set this property to a directory that won't be deleted.

OfficeManager officeManager =
    AttachedOfficeManager
        .builder()
        .workingDir("C:\\jodconverter\\tmp")
        .build();

🔠hostName¶

This property sets the host name that will be used in the --accept argument when connecting to an office process.

 Default: 127.0.0.1

OfficeManager officeManager =
    AttachedOfficeManager
        .builder()
        .hostName("localhost")
        .build();

🔢portNumbers / 🔠pipeNames / 🔠websocketUrls¶

This property sets the port number(s), pipe name(s) and websocket urls that will be used in the --accept argument when connecting to an office process.

If you want to know more about web socket, read the Pull Request where it has been introduced.

 Default: TCP socket, on port 2002.

// This example will use 4 TCP ports and 4 pipes, which will
// cause JODConverter to connect to 8 office processes (a bit excessive!)
// when the OfficeManager will be started.
OfficeManager officeManager =
    AttachedOfficeManager
        .builder()
        .portNumbers(2002, 2003, 2004, 2005)
        .pipeNames("Pipe1", "Pipe2", "Pipe3", "Pipe4")
        .build();

❎connectOnStart¶

This property controls whether a connection must be attempted when the manager starts. If false, a connection will only be attempted the first time a conversion task is executed.

 Default: true.

OfficeManager officeManager =
    AttachedOfficeManager
        .builder()
        .connectOnStart(false)
        .build();

⌚connectTimeout¶

This property sets the timeout, in milliseconds, after which a connection attempt will fail.

 Default: 120000 (2 minutes)

OfficeManager officeManager =
    AttachedOfficeManager
        .builder()
        .connectTimeout(60000)
        .build();

⌚connectRetryInterval¶

This property sets the delay, in milliseconds, between each try when trying to connect to the office process.

 Default: 250 (0.25 seconds)

OfficeManager officeManager =
    AttachedOfficeManager
        .builder()
        .connectRetryInterval(1000)
        .build();

❎connectFailFast¶

This property controls whether the manager will "fail fast" if the connection to the office process fails. If set to true, start() waits for all the connections to be established, and throws an exception if one of them cannot be; the manager cannot be used after that. If set to false, start() returns immediately: the tasks wait in the queue for a connection to be established (see taskQueueTimeout), and a connection that fails is retried, with a growing delay between the attempts (1, 2, 5, 10, then every 30 seconds). Only logs are produced if anything goes wrong.

 Default: false.

OfficeManager officeManager =
    AttachedOfficeManager
        .builder()
        .connectFailFast(true)
        .build();

🔢maxTasksPerConnection¶

This property sets the maximum number of tasks an office process can execute before reconnecting to it. 0 means an infinite number of tasks (will never reconnect).

 Default: 1000

OfficeManager officeManager =
    AttachedOfficeManager
        .builder()
        .maxTasksPerConnection(500)
        .build();

🔢taskQueueCapacity¶

This property sets the maximum number of tasks waiting in the conversion queue. A task submitted while the queue is full fails at once with an OfficeException, instead of waiting for the queue timeout; a web application can thus answer right away that it is overloaded. 0 means no limit.

 Default: 0 (no limit)

OfficeManager officeManager =
    AttachedOfficeManager
        .builder()
        .taskQueueCapacity(100)
        .build();

🔢taskRetries¶

This property sets how many times a task is executed again when the connection executing it is lost. Instead of failing, the task goes back to the head of the queue and is executed once the manager is connected again, or through another connection. Only a conversion from a file to a file, and an export of page images from a file, are executed again; see the same property of the local manager for the details.

 Default: 0 (a task whose connection is lost fails)

OfficeManager officeManager =
    AttachedOfficeManager
        .builder()
        .taskRetries(1)
        .build();

⌚taskQueueTimeout¶

This property sets the maximum time a task waits in the conversion queue, from its submission until an office process takes it. Waiting for a process to start or restart is part of it. When it expires, the task is removed from the queue without having been executed and fails with an OfficeException.

 Default: 30000 (30 seconds)

OfficeManager officeManager =
    AttachedOfficeManager
        .builder()
        .taskQueueTimeout(60000)
        .build();

⌚taskExecutionTimeout¶

This property sets the maximum time allowed to execute a task, counted from the moment a connection starts it, not from its submission. When it expires, the task fails with an OfficeException, the connection is closed and established again, and the next task is processed by another connection in the meantime.

 Default: 120000 (2 minutes)

OfficeManager officeManager =
    AttachedOfficeManager
        .builder()
        .taskExecutionTimeout(60000)
        .build();

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.