Kinesis SoftwareKineticFusion

[Show Table of Contents]

4 Running KineticFusion

[Hide Table of Contents]



4.1 The Java Environment

Most applications are designed and developed to run on a single type of computer environment, be it Microsoft Windows, Apple OS X or Linux. These applications are distributed as 'native' code, meaning they run directly on a computer without needing any additional software installed. In recent years, an alternative mechanism has become popular for developing and running applications that are not directly dependent on the type of system they are executing on. These applications run on what is known as Virtual Machines, and include well-known environments such as Python, PHP, and Java.

KineticFusion is written in Java, a key Internet technology developed by Sun Microsystems used in many Web applications and made freely available. The Java Runtime Environment, the application that allows users to execute Java applications, is available for all major computing platforms including Windows, OS X, Linux, HP-UX, Solaris, and many more. A more restricted version is even available for many modern mobile phones. Any application written in Java is immediately available for use on any on the supported Java platforms.

To run Java applications or Java applets, it is necessary to have Java installed on your computer. Java is available in two different flavors: the Java Runtime Environment and the Java Development Kit.

4.1.1 The Java Runtime Environment (JRE)

The Java Runtime Environment is the full Java environment required to run any Java program. The most recent version of the Java Runtime Environment can be downloaded for free from http://www.java.com/getjava. The size of the download varies but for many users the base installation size is approximately 7MB. After downloading, the environment is installed automatically on your computer and you can run KineticFusion.

4.1.2 The Java Development Kit (JDK)

The Java Development Kit provides all necessary development tools for writing and compiling Java programs in addition to a complete Java Runtime Environment. The most recent version of the Java Development Kit can be downloaded for free from the download links at http://java.sun.com/j2se/. KineticFusion does not require a JDK in order to run however to build extension Tag Libraries that allow users to create their own RVML extensions, it is necessary to have a Java Development Kit installed so that the classes that define the external libraries can be compiled.

4.1.3 Checking Your Java Version

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.

4.1.3.1 For Windows Users

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.

For advanced users, it is also possible to customize the parameters to the Java Virtual Machine by creating a file called '.jvmargs' in the installation folder. The first line of this file is read, if it exists, and the contents used as JVM arguments. More information on JVM arguments can be found in the KineticFusion Configuration documentation.

4.1.4 Java Application Execution

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.

4.1.5 Java Application Structure

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.

4.1.6 Running a Java Application

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.

4.1.6.1 Java and Application Properties

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

4.1.6.1.1 Class Path Background Information

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

4.1.6.1.2 Setting Configuration Options on the Command Line

A java option that is recommended for use with KineticFusion is the option for setting system and application properties (-D). KineticFusion uses properties to configuration application options. While these are normally defined in the KineticFusion.properties file, these properties can be overridden on the command-line using the '-D' option. This can be very useful when running in batch mode, and a user wishes to specify a different application setting for each document, More information on specifying application options on the command line can be found in the Configuration section.

When using dynamic data inside RVML documents, it is also possible to parameterize RVML documents by specifying global data model values on the command line. Model variables are prefixed by 'global.' and are immediately available to all RVML documents e.g.

java -classpath KFDeveloper.jar -Dglobal.width=800 com.kinesis.KineticFusion

This will automatically add the 'width' variable to the global data model that can be referenced within any RVML document:

<Movie width="${width}"...

Java provides each Java application with a set of standard system properties specifying, among other things, the nature of the Java environment and locale-specific information. The full list of these properties is displayed in the KineticFusion 'About...' dialog under the 'System' tab:
System Properties Image

4.1.6.2 Non-Standard Options

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

4.1.6.3 Application Main Class

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

4.1.6.4 Application Options

Application options are the list of space-separated options to the application. The options used by KineticFusion are listed in the Running KineticFusion Directly section.