HOW-TO RUN JANEL

CONTENTS
SHORT ANSWER
FILES INCLUDED

WINDOWS SERVICE
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

CONFIGURING AND RUNNING A WINDOWS SERVICE
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 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 and MyExampleApp.lap 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.

WINDOWS SERVICE

The executable JanelConsole32.exe and JanelConsole64.exe can also run as a windows service. See the janel.service.* properties for the configuration (.lap) file.

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:

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:

 

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.

CONFIGURING AND RUNNING A WINDOWS SERVICE
Below is a sample .lap file for a Janel executable that operates as a service:

janel.main.class=myServiceMainClass
janel.min.java.version=1.6
janel.working.dir=${SELF_HOME}
janel.service.name=myService
janel.service.display.name=My Java-Service
janel.service.description=JANEL-powered Java-Service 1.0
janel.service.option.install=--install
janel.service.option.uninstall=--uninstall

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

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.

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. Please note that if you change to a working directory other than ${SELF_HOME} (with the custom property janel.working.dir), then you should prefix all paths with ${SELF_HOME} to make sure that all paths are resolved correctly, regardless of the current working directory.

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

A: Make sure you have implemented an initiateExit(int) static method in your main Java class. This method gets called if the service is requested to stop.

A: See the question above, first you have to implement the initiateExit(int) static method in your main class. The responsibility of this method is to shut down your Windows Service (in other words, this method has to make sure that your main static method returns). If you do anything that simply terminates the process, i.e. calling System.exit(), Janel has no chance to inform Windows that the service has successfully ended (and furthermore, for the Service Control Manager the service has ended unexpectedly which in turn triggers the "broken pipe error").

A: See the question above, it is the same reason.