HOW-TO RUN JANEL

CONTENTS
FILES INCLUDED

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

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.main.argument = arguments passed to the Janel executable. For details see below.
• 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.7.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.classpath.jars.dir.recursive = like janel.classpath.jars.dir, but the specified directory is scanned recursively for jar files. Please note that the order of the jars on the classpath is undefined!
• 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.library.path.dir.recursive = like janel.library.path.dir, but also all subdirectories of the specified directory are added to the library path. Please note that the order of the directories is undefined!
• janel.working.dir = just before the main class gets called, Janel will change the current working directory to the specified directory. Normally you should specify only one of the supported property value variables like ${CALLER_DIR} or${SELF_HOME}. Starting with Janel 3.0 the default is ${SELF_HOME}. • 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. • janel.service.name = name of the windows service to be used. If this property is specified, Janel will behave as a windows service. • janel.service.display.name = The display name of the windows service. If this property is not specified, janel.service.name will be used. • janel.service.description = A detailed description of the service. If this property is not specified, no description will be set. Janel will update the description on every start of the service. A recommended part of description would be release number. • janel.service.option.install = If present, Janel will install the started executable as a windows service. The property janel.service.name must also be specified. • janel.service.option.uninstall = If present, Janel will uninstall the windows service with the name specified in the property janel.service.name. 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.

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 • In this example running the Janel executable with the command line parameter "--install" will install a new service named "myService" with the display name "My Java-Service" and the specified description. Please note that all arguments that follow the "--install" will be passed to the service every time the service is started. • The service can now be started. For example from the command line issue "sc start myService" to start the myService service. • The service can be stopped in the same way. For example from the command line issue "sc stop myService" to stop the myService service. • When the service is requested to stop (either by the user or due to a system shutdown) the static method "initiateExit(int)" in the main class is invoked. This method is responsible for ending the service gracefully (return from the "main()" method). • When the JVM terminates the process, i.e. if "System.exit()" is invoked, the service will stop with an error message (error code 109, broken pipe). • In this example running the Janel executable with the command line argument "--uninstall" will uninstall the service. Note that the service must not be started at the time of uninstalling. • Error messages will be shown if the Janel executable is started as a console program. 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. 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.

• Q: Which character set does Janel use?

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

• Q: Why does my Windows Service not end?

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.

• Q: Why do I get a "broken pipe error" when I try to stop my Windows Service with the command line utility “sc”?

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").

• Q: When I try to stop my service (by using the GUI) it takes very long and finally ends in an error message "the service did not respond" - why?

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