4.1 The Java Environment

Java has been used for many years and there are several versions. In order to run KineticFusion it is necessary to have the Java 1.4 Runtime Environment installed on your computer. The most recent version of Java is Version 1.5.0 and this is the preferred version for use since it includes many improvements over the previous two versions, 1.4.1 and 1.4.2. You can check what version of Java you have installed by typing at a command window:

java -version

There should be little difference in the appearance of a Java application from other applications you are used to. However, because it is not using the native graphical environment there may be minor differences noticed. These differences are extremely minor with Java 1.5 and KineticFusion is designed to function as intuitively as possible.

When the java command is executed in a windowing environment such as Windows, a separate console window is opened to display all output from the Java application. This window will close automatically when the application is terminated. On Windows systems there is another command called javaw. This command operates exactly the same as the java command except no console window is created. This means that any output from the application to the console is discarded. The 'javaw' command can be used interchangeably with the 'java' command in all future examples that do not require console output.

On Windows, KineticFusion is distributed with a KineticFusion.exe executable file. This is installed in the Start Menu and a shortcut to the application is placed on the desktop. This executable will automatically check to ensure that a valid Java installation is installed when running the application and, if Java cannot be found, the user is redirected to the Java website to download the latest version.

If the first parameter to KineticFusion.exe is '/C' then KineticFusion is run with a console window where all output is logged.

All Java applications are executed by the Java Runtime Environment, which contains the Java Virtual Machine. This means that the application begins executing as an interpreted application. While it is sometimes assumed that this causes Java applications to run very slowly in fact this is not generally the case. All code that is interpreted in the JVM is profiled internally and when enough information is available, the code is optimized on the fly to native code. This is called Just-In-Time Compiling. When using the GUI application the application may appear to be quite slow when the user first starts to use a particular piece of functionality. This is caused by the JVM performing the initial code profiling and management. In general, after using a particular area of functionality once, the performance should be greatly increased and will approach (sometimes surpassing) native speed.

A side effect of this feature is that when KineticFusion is being run on the command-line to process a single document, the JVM does not have enough information to perform much JIT execution. This means that the application will run slower than when used for the same purpose through the GUI.

A Java application consists of one or more Java classes along with associated resources. Classes and associated resources are normally stored together in a Java Archive (JAR) file, a zip-compatible archive. These archives have a '.jar' extension and can be opened with any of the common Zip utilities. Each Java application can have one or more JAR files.

The main KineticFusion application is contained in a Jar file in the main installation folder. The name of the Jar file depends of the installed edition:

• The Developer Edition Jar file is named KFDeveloper.jar
• The Server Edition Jar file is named KFServer.jar

All examples will use the Developer Edition Jar file name for simplicity.

This file contains all of the Java code required to execute the application. To start a Java application, a JVM is launched with the name of one of the classes in the Jar file, a class that is responsible for loading the entire application. For KineticFusion, the name of the class is com.kinesis.KineticFusion.

A Java application requires a JVM within which to run. On all platforms the command line for starting a JVM is:

java? <Java and Application Property definitions> <Application Main Class> <Application Options>

On a Windows environment launching a Java application will also launch an application console window so that the console output of the application can be displayed. As this is not the normal behavior for Windows applications there is an additional JVM binary on Windows called 'javaw.exe'. This works the same as the 'java.exe' command except that all console output from the application is totally discarded.

Options and properties to the JVM are specified on the command-line to alter the behavior of the JVM and to predefine configuration values for the application.

The following are the basic options that can be specified for the JVM and should be available on all platforms:

-server

The JVM specially tuned to maximize peak operating speed. It is intended for running long-running server applications, for which having the fastest possible operating speed is generally more important than having the fastest possible start-up time.

-classpath

Search path of directories and zip/jar files to search for class files (see below)

-D<name>=<value>

set a system or application property. This can be specified multiple times in the same command-line. For more information on this see the KineticFusion Configuration section.

-jar <Jar file name>

Execute the default application stored in the specified Jar file

-version

print the Java version and exit

-help

print all standard options supported

-X

print help on non-standard options. These will change depending on operating system.

The most basic start-up command for KineticFusion, when run from the installation folder, is:

java -classpath 'KFDeveloper.jar' com.kinesis.KineticFusion

When run from any other location the absolute location of the main Jar file needs to be specified, e.g.:

java -classpath 'c:/Program Files/KineticFusion/KFDeveloper.jar' com.kinesis.KineticFusion

The KineticFusion main Jar file KFDeveloper.jar can also be executed directly user the -jar option. For example, the following command-line will also launch KineticFusion:

java -jar KFDeveloper.jar

The class path is used by the JVM to locate the main application but it is also used by the application itself to help find additional configuration resources it needs. The class path is specified as quoted text and specifies a list of Jar files and directories to use when locating classes and resources. On Windows, these paths are separated by semi-colons while on Unix and OSX platforms, the path elements are separated by colon characters. For example, on Windows the full KineticFusion class path might be:

/Programs/KineticFusion/KFDeveloper.jar;/Programs/KineticFusion/lib/freemarker.jar

On Linux, this class path would be represented as:

/usr/local/KineticFusion/KFDeveloper.jar:/usr/local/KineticFusion/lib/freemarker.jar

It is recommended that all locations specified in the class path are absolute locations rather than relative, since it allows users to use the command regardless of their execution location. It is also possible to use a global environment variable to specify the class path. Java will automatically look for the environment variable CLASSPATH if no class path is specified on the command-line.

The class path is also used by the KineticFusion application to locate KineticFusion configuration files - any configuration files found on the class path override the default locations.

KineticFusion requires multiple libraries such as FreeMarker and Jaxen in order to run correctly. However, by default, all the necessary class path options are already defined within the main application Jar file. Once this Jar file is correctly referenced in the class path, there should be no need to further include all the additional libraries used by KineticFusion. The only class path element required is the main KineticFusion jar:

java -classpath 'KFDeveloper.jar' com.kinesis.KineticFusion

In addition to the standard options, each JVM also supports a list of non-standard options. The non-standard options supported by a JVM can be displayed by typing:

java -X

The two main non-standard options that a user should be aware of are:

-XmsnM

Specify the initial size, in megabytes, of the memory allocated to the application. Making this as large as the expected minimum size will increase application speed. The default value of 'n' is 2. Examples:

• -Xms20M
• -Xms40M
• -Xms6M

-XmxnM

Specify the maximum size, in megabytes, of the memory allocated to the application. Increasing this to a significant portion of your computer's hardware will ensure maximum effectiveness of caching behavior and reduce any Out Of Memory errors. If an Out of Memory error occurs, which can happen for example when processing extremely large TrueType fonts, then this option should be specified to increase allocated memory. The default value is 64MB. Examples:

• -Xmx60M
• -Xmx120M
• -Xmx512M

While there is no recommended setting for KineticFusion for these options, as they are based on individual usage, should the default maximum memory amount be exceeded (KineticFusion may terminate with an Out Of Memory Error), these options can be used to increase the maximum allowable amount. Increasing the minimum amount, if you know the application will require it, will also increase the speed of the system.

For example, to run KineticFusion with a minimum memory of 20 MB and a maximum of 256MB the command line could be:

java -Xms20M -Xmx256M -classpath 'KFDeveloper.jar' com.kinesis.KineticFusion

The application main class is the class that loads the Java application. As mentioned above, for KineticFusion this class name is 'com.kinesis.KineticFusion'