LocalOfficeManager Configuration¶
The LocalOfficeManager
is the most common office manager used by the JODConverter users. It is the manager you must use when the OOo
installation lives on the same server as your application, hence the Local prefix.
When using a LocalOfficeManager, there are a number of settings that can be configured. Some of the default settings
used by JODConverter have been chosen because they have a greater chance of working out of the box, but they are
not necessarily the optimal ones.
A LocalOfficeManager is built using a builder:
OfficeManager officeManager = LocalOfficeManager.builder().build();
Here are all the properties you can set through the builder:
Note
JODConverter uses milliseconds for all time values.
📁officeHome¶
This property sets the office home directory of the office installation that will be used to perform document conversions.
Default: Auto-detected, starting with LibreOffice (over OpenOffice) and the most recent version.
// This example will force JODConverter to use the OpenOffice 4
// installation that can be found using the specified path.
OfficeManager officeManager =
LocalOfficeManager
.builder()
.officeHome("C:\\Program Files (x86)\\OpenOffice 4")
.build();
jodconverter:
local:
office-home: C:/Program Files (x86)/OpenOffice 4
jodconverter.local.office-home = C:/Program Files (x86)/OpenOffice 4
jodconverter-cli -i "C:/Program Files (x86)/OpenOffice 4" infile outfile
jodconverter-cli --office-home "C:/Program Files (x86)/OpenOffice 4" infile outfile
📁workingDir¶
This property sets the directory where temporary office profile directories will be created. An office profile directory is created per office process launched. This property will also be 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 =
LocalOfficeManager
.builder()
.workingDir("C:\\jodconverter\\tmp")
.build();
jodconverter:
local:
working-dir: "C:/jodconverter/tmp"
jodconverter.local.working-dir = "C:/jodconverter/tmp"
jodconverter-cli -w "C:/jodconverter/tmp" infile outfile
jodconverter-cli --working-dir "C:/jodconverter/tmp" infile outfile
📁templateProfileDir¶
A LocalOfficeManager creates temporary profile directories for its OOo processes, to avoid interfering with e.g.,
another OOo instance being used by the user. Using this property, you can provide a template profile directory
containing customized settings. The OfficeManager will copy such a template directory to the temporary profile,
so OOo will use the same settings while still keeping the OOo instances separate.
A profile can be customized in OOo by selecting the Tools > Options menu item. Settings that may be worth customizing for automated conversions include e.g.
- Load/Save > General: you may e.g., want to disable "Save URLs relative to Internet" for security reasons.
- Load/Save > Microsoft Office: these options affect conversions of embedded documents, e.g., an Excel table contained in a Word document. If not enabled, the embedded table will likely be lost when converting the Word document to another format.
Default: By default, this temporary profile will be a new one, created by OOo with its own default settings, and relies on the -nofirststartwizard command line option.
Note
The -nofirststartwizard switch is ignored by LibreOffice, see the
Command Line Parameters
documentation.
OfficeManager officeManager =
LocalOfficeManager
.builder()
.workingDir("C:\\jodconverter\\templateProfileDir")
.build();
jodconverter:
local:
working-dir: "C:/jodconverter/templateProfileDir"
jodconverter.local.working-dir = "C:/jodconverter/templateProfileDir"
jodconverter-cli -w C:\jodconverter\templateProfileDir infile outfile
jodconverter-cli --working-dir C:\jodconverter\templateProfileDir infile outfile
🔠hostName¶
This property sets the host name that will be used in the --accept argument when starting an office process. Most of
the time, the default will work. But if it doesn't work (unable to connect to the started process), using localhost
instead of the default value may work.
Default: 127.0.0.1
OfficeManager officeManager =
LocalOfficeManager
.builder()
.hostName("localhost")
.build();
jodconverter:
local:
host-name: localhost
jodconverter.local.host-name = localhost
jodconverter-cli -n localhost infile outfile
jodconverter-cli --host-name localhost infile outfile
🔢portNumbers / 🔠pipeNames¶
OOo inter-process communication can use either TCP sockets and/or named pipes. Named pipes have the advantage of not
taking up TCP ports (with their potential security implications), and they are marginally faster. However, they require
a native library to be loaded by the JVM, and this means having to set the java.library.path system property. That's
why it's not the default. The path that needs to be added to java.library.path is different depending on the platform,
but it should be the directory in the OOo installation containing libjpipe (or jpipe.dll).
- On Linux it's e.g.: java -Djava.library.path=/opt/openoffice.org/ure/lib
- On Windows it's e.g.: java "-Djava.library.path=C:\Program Files (x86)\OpenOffice 4\program"
Default: TCP socket, on port 2002.
// This example will use 4 TCP ports and 4 pipes, which will
// cause JODConverter to start 8 office processes (a bit excessive!)
// when the OfficeManager will be started.
OfficeManager officeManager =
LocalOfficeManager
.builder()
.portNumbers(2002, 2003, 2004, 2005)
.pipeNames("Pipe1", "Pipe2", "Pipe3", "Pipe4")
.build();
Note
pipeNames can't be used with Spring Boot for now.
jodconverter:
local:
port-numbers: 2002, 2003, 2004, 2005
jodconverter.local.port-numbers = 2002, 2003, 2004, 2005
Note
pipeNames can't be used with the command line tool, and only 1 port can be configured.
jodconverter-cli -p 2003 infile outfile
jodconverter-cli --port 2003 infile outfile
🔠processManager¶
A process manager is used when JODConverter needs to deal with a started office process. When JODConverter starts an office process, it must retrieve the PID of the started process to be able to kill it later if required.
Default: By default, JODConverter will try to find the best process manager according to the OS on
which JODConverter is running. But any process manager implementing the
ProcessManager
interface can be used if found on the classpath.
// This example will create an instance of the com.example.foo.CustomProcessManager
// class that will be used by the created OfficeManager.
OfficeManager officeManager =
LocalOfficeManager
.builder()
.processManager("com.example.foo.CustomProcessManager")
.build();
jodconverter:
local:
process-manager-class: com.example.foo.CustomProcessManager
jodconverter.local.process-manager-class = com.example.foo.CustomProcessManager
jodconverter-cli -m com.example.foo.CustomProcessManager infile outfile
jodconverter-cli --process-manager com.example.foo.CustomProcessManager infile outfile
🔠runAsArgs¶
This property specifies the sudo arguments that will be used with unix commands when JODConverter chooses a unix process manager.
OfficeManager officeManager =
LocalOfficeManager
.builder()
.runAsArgs("sudo")
.build();
runAsArgs can't be set with the Spring Boot module.
runAsArgs can't be set with the command line tool.
⌚processTimeout¶
This property sets the timeout, in milliseconds, when trying to execute an office process call (start/terminate).
Default: 120000 (2 minutes)
OfficeManager officeManager =
LocalOfficeManager
.builder()
.processTimeout(60000)
.build();
jodconverter:
local:
process-timeout: 60000
jodconverter.local.process-timeout = 60000
processTimeout can't be set with the command line tool, it will always be 120000.
⌚processRetryInterval¶
This property sets the delay, in milliseconds, between each try when trying to execute an office process call ( start/terminate).
Default: 250 (0.25 seconds)
OfficeManager officeManager =
LocalOfficeManager
.builder()
.processRetryInterval(1000)
.build();
jodconverter:
local:
process-retry-interval: 1000
jodconverter.local.process-retry-interval = 1000
processRetryInterval can't be set with the command line tool, it will always be 250.
⌚afterStartProcessDelay¶
This property specifies the delay, in milliseconds, after an attempt to start an office process before doing anything else. It is required on some OS to avoid an attempt to connect to the started process that will hang for more than 5 minutes before throwing a timeout exception, we do not know why.
Default: 0 (no delay). On FreeBSD, which is a known OS needing this, it defaults to 2000 (2 seconds).
OfficeManager officeManager =
LocalOfficeManager
.builder()
.afterStartProcessDelay(5000)
.build();
jodconverter:
local:
after-start-process-delay: 5000
jodconverter.local.after-start-process-delay = 5000
afterStartProcessDelay can't be set with the command line tool, it will always be 0.
🔠existingProcessAction¶
This property specifies the action that must be taken when trying to start an office process with a connection string and that there already is a process running with the same connection string. Available options are:
- FAIL: Indicates that the office manager must fail when trying to start an office process and there already is a process running with the same connection string. If that is the case, an exception is thrown.
- KILL: Indicates that the manager must kill the existing office process when starting a new office process, and there already is a process running with the same connection string.
- CONNECT: Indicates that the manager must connect to the existing office process when starting a new office process, and there already is a process running with the same connection string.
- CONNECT_OR_KILL: Indicates that the manager must first try to connect to the existing office process when starting a new office process, and there already is a process running with the same connection string. If the connection fails, then the manager must kill the existing office process.
Default: ExistingProcessAction.KILL.
See here to understand why such a property exists and to learn more about a use case where this properly is useful.
OfficeManager officeManager =
LocalOfficeManager
.builder()
.existingProcessAction(ExistingProcessAction.CONNECT_OR_KILL)
.build();
jodconverter:
local:
existing-process-action: connect_or_kill
jodconverter.local.existing-process-action = onnect_or_kill
jodconverter-cli -x connect_or_kill infile outfile
jodconverter-cli --existing-process-action connect_or_kill infile outfile
❎keepAliveOnShutdown¶
This property controls whether the manager will keep the office process alive on shutdown. If set to true, the stop
task will only disconnect from the office process, which will stay alive. If set to false, the office process will be
stopped gracefully (or killed if it could not be stopped gracefully).
See here to understand why such a property exists and to learn more about a use case where this properly is useful.
Default: false.
OfficeManager officeManager =
LocalOfficeManager
.builder()
.keepAliveOnShutdown(true)
.build();
jodconverter:
local:
keep-alive-on-shutdown: true
jodconverter.local.keep-alive-on-shutdown = true
jodconverter-cli -k outfile
jodconverter-cli --keep-alive-on-shutdown infile outfile
❎startFailFast¶
This property controls whether the manager will "fail fast" if an office process cannot be started or the connection
to the started process fails. If set to true, the start of a process will wait for the task to be completed, and will
throw an exception if the office process is not started successfully or if the connection to the started process fails.
If set to false, the task of starting the process and connecting to it will be submitted and will return immediately,
meaning a faster starting process. Only error logs will be produced if anything goes wrong.
Default: false.
OfficeManager officeManager =
LocalOfficeManager
.builder()
.startFailFast(true)
.build();
jodconverter:
local:
start-fail-fast: true
jodconverter.local.start-fail-fast = true
startFailFast can't be set with the command line tool, it will always be false. It would not be possible to support
this option with the command line tool.
🔢maxTasksPerProcess¶
This property sets the maximum number of tasks an office process can execute before restarting. 0 means an infinite number of tasks (will never restart). It is not recommended to set this property to 0 since some OOo installation is known to have memory leaks when converting documents.
Default: 200
OfficeManager officeManager =
LocalOfficeManager
.builder()
.maxTasksPerProcess(50)
.build();
jodconverter:
local:
max-tasks-per-process: 50
jodconverter.local.max-tasks-per-process = 50
maxTasksPerProcess can't be set with the command line tool, it will always be 200.
⌚taskQueueTimeout¶
This property is used to set the maximum living time of a task in the conversion queue. The task will be removed from
the queue if the waiting time is longer than this timeout and an OfficeException will be thrown.
Default: 30000 (30 seconds)
OfficeManager officeManager =
LocalOfficeManager
.builder()
.taskQueueTimeout(60000)
.build();
jodconverter:
local:
task-queue-timeout: 60000
jodconverter.local.task-queue-timeout = 60000
taskQueueTimeout can't be set with the command line tool, it will always be 30000.
⌚taskExecutionTimeout¶
This property sets the maximum time allowed to process a task. If the processing time of a task is longer than this timeout, this task will be aborted and the next task is processed.
Default: 120000 (2 minutes)
OfficeManager officeManager =
LocalOfficeManager
.builder()
.taskExecutionTimeout(60000)
.build();
jodconverter:
local:
task-execution-timeout: 60000
jodconverter.local.task-execution-timeout = 60000
jodconverter-cli -t 60000 infile outfile
jodconverter-cli --timeout 60000 infile outfile
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.