Chapter 5. Installation and Configuration

Additional to the jadice server distribution file you receive a separate license file (JadiceServerLicense.properties). This license file has to be placed into the configuration directory /server-config. If the file is missing or the license is expired or invalid, an error message appears in the server and client log whenever jadice server is launched or a job is requested.

In case you hold a temporary evaluation license a message will appear when launching the server, but there will be no further constrictions on the jadice server's range of functionalities.

jadice server uses Apache FOP to convert XML documents and e-mails to PDF format. For licensing reasons the optional package for hyphenation cannot be included in the jadice server's distribution package. However, you can download it free of charge at http://offo.sourceforge.net/. To install the package you just need to copy the file hyphenation.jar into the directory server-lib.

There are three alternative layouts of the messaging system to choose from.

The XML configuration determines which of these three variants is used. The prospective connector is set in the paragraph <bean id="jms-connection-factory" …> in the file server-config/application/activemq-client.xml; the properties such as the name of the message queue and the port for ActiveMQ with which jadice server is to connect are determined in the paragraph <property name="properties" …> in the file server-config/application/server.xml with jadice.server.queue-name; and jadice.server.activemq-port. Since the class ActiveMQConnectionFactory implements both QueueConnectionFactory and TopicConnectionFactory, it is referenced with the aliases jms-queue-connection-factory as well as jms-topic-connection-factory in the respective places.

The file server-config/application/example/jms.xml contains examples which illustrate how connections via IBM Websphere MQ can be established. The fitting configuration code has to be inserted into XML configuration where it should replace the paragraphs <bean id="jms-queue-connection-factory" …> and <bean id="jms-topic-connection-factory" …>.

By default jadice server offers the messaging system (i. e. the message broker) to be used in its server instance. Unless determined otherwise Apache ActiveMQ is thus used as messaging system. Its settings are configured in the file server-config/application/embedded-activemq-broker.xml. A manual explaining how to encrypt the transmissions between client and server can be found at http://activemq.apache.org/ssl-transport-reference.html and http://activemq.apache.org/how-do-i-use-ssl.html.

Port and name of the utilized message queue are set in the main configuration file server-config/application/server.xml, see the section called “Configuring the Messaging System”.

To prevent the use of this internal broker, the paragraph <feature>embedded-activemq-broker</feature> in the file server-config/application/active-features.xml has to be deleted.

The server is launched via a system-dependent wrapper. Java VM and class path parameters are defined there.

The wrapper configuration file wrapper.conf can be found in the directory /wrapper.

Path to the Java VM:

# Java Application
wrapper.java.command=java

Definition of further class path entries:

# Java Classpath (include wrapper.jar)  Add class path # elements as needed starting from 1
wrapper.java.classpath.1=../bin/server-console.jar
wrapper.java.classpath.2=../msoffice-lib
# Example of a further class path entry
wrapper.java.classpath.N=...
	  			

If further parameters (such as setting a temporary directory for the VM) are needed, they can be set in the following way:

# Example of further JVM parameters
wrapper.java.additional.1=-server
wrapper.java.additional.2=-Djava.io.tmpdir=C:\tmp
wrapper.java.additional.N=<further parameters>
	  			

Defining JVM storage settings, wrapper.java.initmemory corresponds to parameter -Xms, wrapper.java.maxmemory corresponds to parameter -Xmx:

# Initial Java Heap Size (in MB)
#wrapper.java.initmemory=3

# Maximum Java Heap Size (in MB)
wrapper.java.maxmemory=512
	  			

Furthermore, it is possible to change the class path and thereby the loaded Java libraries, for example to add worker implementations to jadice server. These modifications can be made in the files /server-config/jadice-server.options and /server-config/jadice-server-local.options. The following entries are possible:

-cp 
<jar library>

--classpath
<jar library>

-ld 
<directory>

--library-dir 
<directory>

Note that there has to be a line break between the option and the parameter. The effective class path is formed in the following way:

Moreover, the following options are possible:

-xo 
<configuration file>

--extra-options
<configuration file>

The directory <LibreOffice directory>/program must be referenced. Otherwise the server cannot access the software file of LibreOffice. Configurations are listed in the file /server-config/jadice-server-local.options, for example,

# LibreOffice directory
-cp
C:\Program Files (x86)\Libre Office 5\program\
				

Moreover, <LibreOffice-Verzeichnis>/program/classes/java_uno.jar, juh.jar, jurt.jar, ridl.jar, unoloader.jar and unoil.jar have to be integrated in the class path. What is more, JVM and LibreOffice have to be binary compatible (x86 / x64).

If the paths are set incorrectly, an error will occur on conversion.

When using an operating system that is nor Windows (such as Linux, Unix), the package Xvfb (X window virtual framebuffer) has to be installed to allow for a headless and therefore automated operation of LibreOffice.

If jadice server is installed on Windows NT, 2000, Server 2003 or an older version and if the the conversion is to be realized with MSWordNode / MSExcelNode /… , the “Microsoft Visual C++ 2005 SP1 Redistributable Package (x86)” needs to be installed first.

Using MS Office 2007 Service Pack 2 or more recent versions, it is possible to export PDFs natively. If you are using any version of MS Office 2007 that predates Service Pack 2, “2007 Microsoft Office Add-in: Microsoft Save as PDF” has to be installed in order to use the native PDF export.

Furthermore, it needs to be determined how macros should be treated in MS Office's “Trust Center”. Since user queries are not possible in server operation, only the option “Disable all macros without notification” is sensible (see Figure 5.1, “Feasible Setting for Macros in MS Office”). ActiveX settings have to be modified accordingly.

Figure 5.1. Feasible Setting for Macros in MS Office

If jadice server is installed as a Windows service as described in the section called “Server” this service may not log on as the local system account but as a technical account (see Figure 5.2, “Installation of jadice server as technical account”). Else the conversion via MS Office may fail with various, irreproducible errors.

Figure 5.2. Installation of jadice server as technical account

To circumvent the security guidelines that prevent jadice server from accessing MS Outlook, the software Advanced Security for Outlook has to be installed and configured.

Configuration:

In MS Outlook 2007 the option “Empty the Deleted Items Folder upon exiting” has to be activated, too. You can find this setting under → Options → Other. In addition, the option “Warn before permanently deleting items” has to be deactivated. This setting is located under Advanced Tools → Options → Other → Advanced Optiones.

In order to convert MS Project files that have been created with an earlier version of the software the setting “Allow loading files with legacy or non-default file formats.” needs to be selcted in the Trust Center:

Figure 5.3. Settings for legacy formats in MS Project 2010

The framework log4j is used for the administration of log entries. This framework is configured in the file /server-config/logging/log4j-appenders.xml or /server-config/log4j-appenders-mvm.xml if operating in multi-VM mode. By default log messages are returned in the console as well as saved in the directory /log/.

In the default settings files saved in this directory are rotated on a daily basis with the help of the LogAppender DailyRollingFileAppender. Since this tool does not offer the option of only keeping the log files of the last n days, you should make sure that there is enough storage space for saving the log files or automatically and regularly move or delete the older files. Otherwise, we recommend using RollingFileAppender as it provides the option of delineating a maximum of files to keep.

Further options for logging are listed as comments in the configuration file and just need to be activated.

In order to be able to use the GhostscriptNode, the following conditions need to be met:

The use of external libraries can cause an error and result in a crash of Java Virtual Machine or even jadice server.

In order to ensure continuing job processing in such a case, jadice server can be launched in multiple instances on a single computer. In this scenario a central instance of jadice server monitors the other instances, which carry out the actual work. If any of these working instances fails to respond or has crashed, the central instances terminates the respective process and automatically launches a new instance of jadice server.

If you want to operate jadice server in this multi-VM mode, the comment marking in the file /server-config/application/active-features.xml around <feature>mvm</feature> has to be deleted.

The working instances can be configured in the file /server-config/application/multi-vm-manager.xml in the paragraph <bean id="server" …>. There are several ways to adapt the number of working instances:

Further launching parameters of the starting JVM such as available storage space can be determined under <property name="instanceJVMOptions" …>.

In order to activate the SOAP interface via which queries in XML format are posed to jadice server, the comment marking around the element <feature>soap</feature> in the file server-config/application/active-features.xml has to be deleted.

In the element <jaxws:endpoint …> in the file server-config/application/soap.xml an endpoint of the web service (as instance of javax.xml.ws.Endpoint) is propagated. The pre-set attribute address="http://${jadice.server.hostname}:9000/jadiceServer" provides the endpoint using the name of the host computer on port 9000.

See the section called “SOAP Interface” for more information on the use of the SOAP interface.

In order to activate the REST interface via which requests in XML or JSON format are posed to jadice server the comment marking around the element <feature>rest</feature> in the file server-config/application/active-features.xml has to be deleted.

In the element <jaxrs:server …> in the file server-config/application/rest.xml the JAX-RS endpoint of the REST interface is propageted. The pre-set attribute address="http://${jadice.server.hostname}:9001/jadiceServer" provides the endpoint using the name of the host computer on port 9001.

See the section called “REST Interface” for more information on the use of the REST interface.

The security interface serves to prevent or limit unauthenticated clients' access to jadice server and its range of functions. In order to activate the interface, the comment markings around the paragraphs <feature>security</feature> in the file server-config/application/active-features.xml have to be deleted.

The file server-config/application/security.xml contains an exemplary configuration which needs to be set to the desired security level. For further information on this setting and the use of the security interface see Chapter 8, Security Interface.