Configuration
JODConverter uses milliseconds for all time values.
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.
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.
- 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, which will cause
// JODConverter to start 4 office processes when the
// OfficeManager will be started.
OfficeManager officeManager =
LocalOfficeManager.builder()
.portNumbers(2002, 2003, 2004, 2005)
.build();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("D:\\Program Files (x86)\\OpenOffice 4")
.build();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 in order 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();This property specifies the sudo arguments that will be used with unix commands when JODConverter choose a unix process manager.
OfficeManager officeManager =
LocalOfficeManager.builder()
.runAsArgs("sudo")
.build();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.
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 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 defaults settings, and relies on the -nofirststartwizard command line option.
This property sets the timeout, in milliseconds, when trying to execute an office process call (start/terminate).
Default: 120000 (2 minutes)
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)
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 default to 2000 (2 seconds).
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.
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.
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 could not been stopped gracefully).
Default: false.
This property specifies whether OpenGL must be disabled when starting a new office process (LibreOffice only). Nothing will be done if OpenGL is already disabled according to the user profile used with the office process. If the option is changed, then office must be restarted. If you have problems with crashing LO instances, you should test this property.
Default: false.
This property sets the maximum number of tasks an office process can execute before restarting. 0 means infinite number of task (will never restart).
Default: 200
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)
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)
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.