HOW-TO RUN JANEL

CONTENTS
SHORT ANSWER
FILES INCLUDED
MICROSOFT DLLS FOR JAVA 6 AND JAVA 7
HOW IS THE CONFIGURATION (.LAP) FILE FOUND
STRUCTURE OF .LAP FILES
CUSTOM PROPERTIES IN A .LAP FILE
DETERMINING THE JVM WITH CUSTOM PROPERTIES IN A .LAP FILE
JAVA SYSTEM PROPERTIES IN A .LAP FILE
PROPERTY VALUE VARIABLES IN A .LAP FILE
COMMAND-LINE ARGUMENTS
ERROR MESSAGES
EXECUTABLE'S RESOURCES
CUSTOM ICONS
VERSIONING
FREQUENTLY ASKED QUESTIONS

SHORT ANSWER
The short answer to how-to run Janel is: Go to Janel's Executables\Win32 directory. Change JanelConsole32.exe to the name of your Java application that you want to launch, such as MyApp.exe. Rename a .lap file to MyApp.lap. In the .lap file set the property janel.main.class to the fully qualified name of the class that has your main method, and set the -Djava.class.path property to the desired classpath. Copy MyApp.exe, MyApp.lap, msvcr71.dll and msvcr100.dll to a directory, and you should be ready to launch your Java application with Janel.

Another example:

1. Go to Janel's Executables directory.
2. Rename JanelWindows32.exe to MyExampleApp.exe.
3. Rename JanelWindows32.lap to MyExampleApp.lap.
4. Set the contents of MyExampleApp.lap to be:
   janel.main.class=example.ClassThatHasMainMethod
-Djava.class.path=lib\MyExample.jar
5. Put MyExampleApp.exe, MyExampleApp.lap, msvcr71.dll, and msvcr100.dll in the same directory.
6. MyExampleApp.exe is ready to launch.

FILES INCLUDED
There are four binary Janel executables (listed below) included in the downloaded zip file from http://sourceforge.net/projects/janel/files/. The Win32 executables are in the Executables\Win32 directory and x64 executables are in the Executables\x64 directory.

1. JanelWindows32.exe is for 32-bit (x86) Windows and does not create a console when launched and reports errors using pop-ups.

2. JanelWindows64.exe is for 64-bit (x64) Windows but otherwise behaves the same as JanelWindows32.exe.

3. JanelConsole32.exe is for 32-bit (x86) Windows and creates a console when launched and reports errors by writing to the console.

4. JanelConsole64.exe is for 64-bit (x64) Windows but otherwise behaves the same as JanelConsole32.exe.

There are example configuration files for the launcher, these have the extension of .lap.

MICROSOFT DLLS FOR JAVA 6 AND JAVA 7
For executing with Java 6 the file msvcr71.dll must be installed on the PC or deployed to the same directory as the Janel launcher. For executing with Java 7 the file msvcr100.dll must be installed on the PC or deployed to the same directory as the Janel launcher.

HOW IS THE CONFIGURATION (.LAP) FILE FOUND
The executable will only search the directory which it is in for a .lap file with the same name as itself. For example, JanelWindows32.exe will look for JanelWindows32.lap only within the directory in which JanelWindows32.exe resides.

STRUCTURE OF .LAP FILES
The .lap files are similar to Java properties files. Most of the properties have their names on the left separated by an equal sign, but for some properties an equals sign is not needed.

A # can be used for a comment but can only be used at the start of a line with no property definitions before it on the line.
An example of a comment in a .lap file:
# this is a comment in a .lap file

A ^ (caret) can be used to continue a line. It must be the last character in the line.
An example of a line continuation in a .lap file:
-Djava.class.path=C:\path\to\some\where;^
..\..\Test\TestLaunch\dist\TestLaunch.jar

Currently there are two kinds of properties, custom properties that start with "janel" and Java system properties that start with "-".

CUSTOM PROPERTIES IN A .LAP FILE
All custom properties are case-sensitive. The custom properties available are:

• janel.main.class = the main Java class to call, ex. mypackage.Start or mypackage/Start
• janel.bin.jvm.dir = the type of JVM. Its current name reflects the fact that it's the directory name that holds the jvm.dll. Possible values are prefer_client (the default), prefer_server, require_client (the same as just client), and require_server (the same as server). "prefer" means that Janel will use the other type of JVM if necessary. All values are case-insensitive.
• janel.java.bundle = informs Janel whether to look for the JVM from a SDK or a JRE install. The possible values are prefer_jre (the default), prefer_sdk, require_jre (the same as JRE), and require_sdk (the same as SDK). "prefer" means that Janel will use the other Java installation if necessary. All values are case-insensitive.
• janel.jvm.path = the path to the jvm.dll file, example C:\Java\bin\client\jvm.dll. If set but file does not exist, Janel will fall back to using another installed Java installation.
• janel.java.home.path = the Java home path, the root directory of the Java installation. For SDK installations the Java home path is the directory that holds directory jre, which holds the bin directory. For JRE installations it is the directory that holds the bin directory. If set but directory does not exist, Janel will fall back to using another installed Java installation.
• janel.min.java.version = the minimum version of the JVM, example 1.4.1
• janel.max.java.version = the maximum version of the JVM, example 1.6.0
• janel.trap.console.ctrl = true/false, yes/no to trap console control commands and call an initiateExit(int) static method in the main Java class. Defaults to false.
• janel.classpath.jars.dir = the path to one directory of jars that will be included in the classpath. Multiple instances of this property can be used to include multiple directories.
• janel.library.path.dir = the path to be added to Java system property java.library.path. which is used to locate native DLLs. Multiple instances of this property may be used.
• janel.main.argument = an argument to be passed to the Java main method. Multiple instances of this property may be used. The order of arguments corresponds to order in .lap file. These arguments follow any arguments passed at the actual command-line.
• janel.sysprop.process.id = true/false, yes/no to send the Java system property process.id equal to the process id. Defaults to false.
• janel.error.default.text = overrides the default error text ("Error in Java launcher.") with a custom error message.
• janel.error.show.detail = true/false, yes/no enables detailed error messages. If true, the default error message will be displayed followed by the details. Defaults to true.
• janel.debug.file = the file which will have debugging messages written to it.
• janel.memory.max.available.percent = sets the max memory via -Xmx as percent of available memory. Use only integers, no percent signs or decimals. 50 (not .50) is equal to 50 percent.
• janel.memory.init.available.percent = sets the initial memory via -Xms as percent of available memory. See above for percent explanation.
• janel.memory.max.total.percent = sets the max memory via -Xmx as percent of total physical memory. See above for percent explanation.
• janel.memory.init.total.percent = sets the initial memory via -Xms as percent of total physical memory. See above for percent explanation.
• janel.memory.max.upper.limit = sets in kilobytes the upper limit of the max memory as set by the other Janel memory custom properties.
• janel.memory.max.lower.limit = sets in kilobytes the lower limit of the max memory, similar to janel.memory.max.upper.limit.
• janel.memory.init.upper.limit = sets in kilobytes the upper limit of the initial memory, similar to janel.memory.max.upper.limit.
• janel.memory.init.lower.limit = sets in kilobytes the lower limit of the initial memory, similar to janel.memory.max.upper.limit.
• janel.memory.check.limits = true/false, yes/no to limit the maximum heap space requested by the Janel memory settings to the largest available memory block. Defaults to false.
• janel.splash = relative path to an image file (GIF, PNG, JPEG) to be displayed as a splash screen upon start up. The path is relative to the executable.

Below is an example of a custom property in a .lap file. The Janel executable will call the main method in class com.redskaper.Start.
janel.main.class=com.redskaper.Start

DETERMINING THE JVM WITH CUSTOM PROPERTIES IN A .LAP FILE
The exact path to the jvm.dll that will be used to call the main method of the Java class is determined in the following order by setting Janel's custom properties. You do not have to think through any of these steps if you just want to use the JVM that is the latest version installed on the local PC. Just be sure to NOT set janel.jvm.path, janel.java.home.path, janel.java.bundle, nor janel.bin.jvm.dir. You will still need to set janel.main.class in all cases.

1. janel.jvm.path is set to the desired existing jvm.dll. The version of JVM will not be checked.
2. janel.java.home.path is set to an existing directory. The version of JVM will not be checked.
3. janel.java.bundle is set. janel.bin.jvm.dir will be assumed to be "prefer_client". The version of JVM will be checked.
4. janel.bin.jvm.dir is set. janel.java.bundle will be assumed to be "prefer_jre". The version of JVM will be checked.
5. Both janel.java.bundle and janel.bin.jvm.dir are set. The version of JVM will be checked.
6. None of the above custom properties are set. janel.bin.jvm.dir defaults to "prefer_client". janel.java.bundle defaults to "prefer_jre". The version of JVM will be checked.

JAVA SYSTEM PROPERTIES IN A .LAP FILE
Java system properties start with a dash - and are passed directly to the JVM. For example, -Djava.class.path=C:\MyPrograms\program.jar, -verbose:gc, and -Xincgc would be passed as is to the JVM.

For a list of the Java system properties a good place to look is the J2SE Javadocs for System.getProperties(). The standard options available are the system properties that are assigned with -D and the -verbose[:class|gc|jni] options. The nonstandard options are dependent upon the JVM and begin with -X. For a list of the available nonstandard options run java.exe -X.

Below is an example of a Java system property in a .lap file. The Java system property, this one corresponding to the classpath, will be set to the named jar.
-Djava.class.path=dist\TestLaunch.jar

To send the process id of the executing process to the Java application as Java system property "process.id" set the following in the .lap file.
janel.sysprop.process.id=true
This is the same as -Dprocess.id=X, where X is the process id.

PROPERTY VALUE VARIABLES IN A .LAP FILE
Properties may also contain variables that are resolved by the Janel executable. Their format is ${property value variable}. For example, a property may be -DJAVA_HOME=${FOUND_JAVA_HOME}. Currently there are three property value variables:

• FOUND_JAVA_HOME is the Java home path that is determined by the Janel executable
• FOUND_EXE_FOLDER is the path to the Janel executable. Same as SELF_HOME but does not remove the trailing "\bin".
• SELF_HOME is the path to the Janel executable with a trailing "\bin" removed if it is present.
• CALLER_DIR is the path to the directory in which the executable was called. Calling executable C:\Dev\MyApp.exe from directory C:\Temp would place "C:\Temp" in ${CALLER_DIR}.

Any environment variable may also be used as a property value variable by prefixing it with "env.". For example, ${env.CATALINA_HOME} would resolve to the value of the environment variable CATALINA_HOME.

Below is an example of a property value variable in a .lap file. The Java system property called found.exe.folder.test will be set to the path to the Janel executable.
-Dfound.exe.folder.test=${FOUND_EXE_FOLDER}

COMMAND-LINE ARGUMENTS
Command-line arguments passed to the Janel executable will be passed as arguments to the main method of the Java class. Command-line arguments can also be specified by using multiple instances of the janel.main.argument custom property in the .LAP file. Arguments passed to the Janel executable will precede arguments specified with janel.main.argument.

Below is an example of passing arguments to the Janel executable. MyApp.exe will pass the two arguments to the main method in the Java class (provided you have a MyApp.lap file correctly setup in MyApp.exe's directory).
MyApp.exe argument1 argument2

ERROR MESSAGES
Janel has three possible parts to an error message:

1. The default text that precedes the detail of the error. This is by default "Error in Java launcher." This can be set using the janel.error.default.text custom property.
2. The details of the error which follows the default text. Whether the detail is displayed or not is set with the janel.error.show.detail custom property.
3. The outputted error message that occurs when an uncaught exception in the Java program causes it to terminate. This is written to standard error before the other two error messages are displayed.

EXECUTABLE'S RESOURCES
Resources, in this case, are the resources compiled into the executable. Examples of such resources are the icon file and version information.

To edit the resources of the executable use either Visual Studio, or possibly one of the following Open Source resource editors will work for you: ResourceExplorer or Resource Hacker.

CUSTOM ICONS
Custom icons for the executable can be set in one of two ways:

1. Use one of the resource editors mentioned above to replace the generic icons with your own custom icons.
2. Or replace the App.ico file with your own custom icon file, naming it App.ico. Then rebuild Janel following the instructions in HowToCompile_VisualStudio.html.

VERSIONING
To set the version of the executable, so that it can be viewed in the Properties of the executable using Windows Explorer, you will need to add a Version resource to the executable. Use Visual Studio or, if one is available, a resource editor that allows you to add a Version resource. The following instructions are for Visual Studio.

1. Open the executable file with Visual Studio. You will see a view of the resources.
2. Right-click the name of the executable and select Add Resource...
3. Select Version.
4. Add your version information.
5. Save All.

FREQUENTLY ASKED QUESTIONS

• Q: How to get janel.library.path.dir to include the same default paths as java.library.path normally contains?

A: The Java system property java.library.path normally includes the local directory "." and whatever is in the PATH environment variable. To include those directories when using janel.library.path.dir you will need to add them to your janel.library.path.dir specification in the .lap file. The following line would add the normal default paths and directory src\NativeTest\dist to the directories that would be searched when trying to locate native DLLs.
janel.library.path.dir=src\NativeTest\dist;.;${env.PATH}
Also multiple janel.library.path.dir can be used in the .lap file.

• Q: Which directory are relative paths in the .lap relative to?

A: Starting with Janel 3.0 relative paths within the .lap file are relative to the directory containing the executable, not relative to the directory from which the executable was launched.

• Q: Which character set does Janel use?

A: Janel uses the Unicode character set so it is compatible with most languages.