Prerequisites

JCopist has been successfully tested with the following configurations:

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

    Compatibility with other unices has not been tested yet. Note that, in order to launch multiple OpenOffice processes simultaneously, JCopist simulates users by dynamically changing the USER and HOME environment variables. Some systems might not allow this.

• 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.

  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.

  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.

  ---

The web services version of JCopist also requires a servlet container. It has currently been tested with Apache Tomcat 5.5.17. 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

Create the 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 <workDir> tag at the beginning of the configuration file provided with the distribution. This directory will be referred to as JCOPIST_WORK.

The default directory structure is the following:

 $JCOPIST_WORK
 +-- deploy
 +-- jobs
 |   +-- failed
 |   +-- pending
 |   +-- retry
 +-- ooProfiles
 +-- templates
 +-- tmp
     +-- builders
     +-- converters

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.

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 (not necessarily in french :-) ):

  
• 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.