JCopist - JCopist installation guide

Prerequisites

JCopist has been successfully tested with the following configurations:

Operating system:
- Microsoft Windows 2000 and XP.
- Red Hat Linux ES V4.

Java Runtime Environment, version 1.5 or higher:
The Java Runtime Environment is not included in the JCopist distribution, you will need to install it separately. (You can download it here).
In the rest of this guide, the base Java installation directory (that is, the directory containing bin) will be referred to as JAVA_HOME.
OpenOffice.org, version 2.0.1 or higher:
OpenOffice.org is not included in the JCopist distribution, you will need to install it separately. (You can download it here).
In the rest of this guide, the base OpenOffice.org installation directory (that is, the directory containing program) will be referred to as OFFICE_HOME.

Warning: do not use OpenOffice.org version 2.0.2, as it contains a bug that will prevent JCopist from functionning.
Apache Tomcat, version 5.5.17 or higher (for the web services version of JCopist):
Apache Tomcat is not included in the JCopist distribution, you will need to install it separately. (You can download it here).
In the rest of this guide, the base Tomcat installation directory (that is, the directory containing bin) will be referred to as CATALINA_HOME.

If you test JCopist with a different configuration, please let us know on the project's forum.

Install the JCopist binaries

RMI version

Create a base directory for the JCopist binaries. It will be referred to as JCOPIST_HOME.

Copy the following directories from the binary RMI distribution to JCOPIST_HOME:

bin - startup/shutdown scripts.
conf - configuration files.
lib - JCopist JARs.
lib-ext - third party JARs.

Edit the file JCOPIST_HOME/bin/startup.sh (or startup.cmd for Windows) and change the variables called JCOPIST_HOME and OFFICE_HOME according to your environment.

Edit the file JCOPIST_HOME/bin/startup.sh (or startup.cmd for Windows) and change the variable called JCOPIST_HOME according to your environment.

Adapt the configuration files in JCOPIST_HOME/conf to your needs. For more information, see the configuration guide.

Web Services version

The binary Web Services distribution contains:

a WAR file named jcopist-ws-XXX.war.
two configuration files: conf/jcopist.xml and conf/log4j.properties.

To install the Web Services version, you must deploy the webapp in your servlet container. With Apache Tomcat, this is achieved by copying the WAR file to CATALINA_HOME/webapps (the context name is based on the WAR file name, so rename the file if you want a shorter context name).

Open Office dependencies

You have to add 4 JAR files from the OpenOffice.org distribution in your webapp's classpath:

For OpenOffice 2.X

$OFFICE_HOME/program/classes/juh.jar
$OFFICE_HOME/program/classes/jurt.jar
$OFFICE_HOME/program/classes/ridl.jar
$OFFICE_HOME/program/classes/unoil.jar

For OpenOffice 3

$OFFICE_HOME/URE/java/juh.jar
$OFFICE_HOME/URE/java/jurt.jar
$OFFICE_HOME/URE/java/ridl.jar
$OFFICE_HOME/Basis/program/classes/unoil.jar

The classpath MUST refer directly to these files, you can not use a copy of the JARs (this causes a java.lang.UnsatisfiedLinkError at webapp deployment, we have no explanation for this). The only way we have found is to modify the Tomcat classpath directly.

For instance, for a Windows installation, edit $CATALINA_HOME/bin/setclasspath.bat and add the last 4 red lines:

[...]
rem Set standard CLASSPATH
rem Note that there are no quotes as we do not want to introduce random
rem quotes into the CLASSPATH
set CLASSPATH=%JAVA_HOME%\lib\tools.jar

For OpenOffice 2.X

set CLASSPATH=%CLASSPATH%;C:\Program Files\OpenOffice.org 2.0\program\classes\juh.jar
set CLASSPATH=%CLASSPATH%;C:\Program Files\OpenOffice.org 2.0\program\classes\jurt.jar
set CLASSPATH=%CLASSPATH%;C:\Program Files\OpenOffice.org 2.0\program\classes\ridl.jar
set CLASSPATH=%CLASSPATH%;C:\Program Files\OpenOffice.org 2.0\program\classes\unoil.jar

For OpenOffice 3

set CLASSPATH=%CLASSPATH%;C:\Program Files\OpenOffice.org 3\URE\java\juh.jar
set CLASSPATH=%CLASSPATH%;C:\Program Files\OpenOffice.org 3\URE\java\jurt.jar
set CLASSPATH=%CLASSPATH%;C:\Program Files\OpenOffice.org 3\URE\java\ridl.jar
set CLASSPATH=%CLASSPATH%;C:\Program Files\OpenOffice.org 3\Basis\program\classes\unoil.jar

Create JCopist directory structure

JCopist uses the file system to store templates, server state and temporary files. All directories must be created before the server starts.

The base work directory is defined in the jcopist.xml configuration file provided with the distribution.
The <workDir> tag at the beginning of this file will be referred to as JCOPIST_WORK.

The default directory structure is the following:

In case you want to change the directory structure itself, each sub-directory is defined in a tag in the rest of the configuration file.

Warning: if your operating system is Windows, do not use a base directory name longer than 32 characters (including drive letter and column). This causes OpenOffice.org to throw a com.sun.star.lang.DisposedException (this is probably related to a dynamically-created directory that exceeds the maximum path size in Windows).

For instance, the following base directory will work:

c:\mytools\jcopist\workdirectory
 <-------- 32 characters ------->

... while the following won't:

c:\mytools\jcopist\work_directory
 <-------- 33 characters -------->

Apparently, the limit in Linux is higher. We haven't determined the maximum allowed size.

JCopist modes

JCopist with socket mode: launch OpenOffice server

To use JCopist in socket mode you have to configure the jcopist.xml file:

	[...]
 	<converterManager>
	 	<socket>true</socket>
	 	<socketHost>localhost</socketHost>
	 	<socketPort>8100</socketPort>
	[...]
 	</converterManager>

In order to launch an OpenOffice server you can use the following command line:

For OpenOffice 2.X:

C:\Program Files\OpenOffice.org 2.X\program > soffice.bin
		-headless 
		-display :99 
		-accept="socket,host=localhost,port=8100,name=test;urp;StarOffice.NamingService" 
		-nofirststartwizard

For OpenOffice 3:

C:\Program Files\OpenOffice.org 3\program > soffice.exe
		-headless 
		-display :99 
		-accept="socket,host=localhost,port=8100,name=test;urp;StarOffice.NamingService" 
		-nofirststartwizard

With linux operating system you have to launch a Server X

$ /usr/X11R6/bin/Xvfb -screen scrn2 800x600x16 :99 &

JCopist without socket mode: Accept the OpenOffice.org licence

JCopist launches multiple OpenOffice.org instances to parallelize document conversions.

Normally, a system user can only run one instance at a time. In order to overcome this limitation, JCopist "simulates" multiple users by dynamically changing the "user name" and "user home directory" system properties when the OpenOffice.org processes are launched.

However, before OpenOffice.org can be launched (even in silent mode), the user must have accepted the license. Therefore, we use a "reference" home directory of a user who has accepted the license. When dynamic users are created, this directory is copied to their home directory.

You have to complete the license agreement procedure for your OpenOffice.org installation. Therefore, we cannot provide the reference home directory with the JCopist distribution. You have to create it with the following procedure:

cd to JCOPIST_WORK/ooProfiles.
create a sub-directory called reference.

open a system console, and set the system properties:

for Windows (assuming JCOPIST_WORK = c:\jcopist):

C:\jcopist\ooProfiles> set USERNAME=reference
C:\jcopist\ooProfiles> set USERPROFILE=c:\jcopist\ooProfiles\reference

for Linux (assuming JCOPIST_WORK = /opt/jcopist):

$ export USER=reference
$ export HOME=/opt/jcopist/ooProfiles/reference

then launch OpenOffice.org (assuming $OFFICE_HOME/program is on your system path):
```
$ soffice
```
You will be presented with OpenOffice.org's license agreement window:
follow the procedure. When it is complete, an OpenOffice.org window opens, close it.

directories and files have been generated in the reference directory. You can do some cleaning, as only the following files are needed:

for Windows:

reference
 +-- Application Data
     +-- OpenOffice.org2
         +-- user
             +-- registry
                 +-- data
                     +-- org
                         +-- openoffice
                             +-- Setup.xcu

for Linux:

reference
 +-- .openoffice.org2
     +-- user
         +-- registry
             +-- data
                 +-- org
                     +-- openoffice
                         +-- Setup.xcu

What's next

JCopist is now installed.

Before lauching the server, have a look at the configuration guide.

User resources

Developer Resources

Project Documentation

Installation guide