NBI Native Launchers

The native launchers facility in the NBI engine serves two purposes:

• we need a way to wrap NBI-based bundles into a native executable so that the user does not need to manually invoke java;
• provide the installable components' developers with an stable, tested and easy-to-use way of wrapping their java-based applications into native executables.

The main functionality of the launchers is to be able to locate an existing compatible JVM and launch java -cp <classpath> <Main-Class> on a specified jar file (either bundled or external, identified by a relative or absolute path) optionally passing in some JVM options and target application command-line parameters.

These two tasks imply the following features/functionality:

• the launcher itself is a small precompiled native binary or a script
  • 32-bit .exe on windows compilable under either cygwin/gcc or Microsoft Visual C++ 2005 Express Edititon
  • shell script (.sh) on unix
  • shell script wrapped into .app on MacOS
• the launcher is capable of detecting the existing JDK/JRE installations (i.e. JVMs) on the target system basing on:
  • system registry entries (as of 11.02.2008 - windows only)
  • a list of predefined locations on the filesystem
  • NBI registry entries (as of 11.02.2008 - not yet implemented)
• the launcher is able to validate the found JVMs by the supplied:
  • minimum version
  • maximum version
  • JVM vendor
  • JVM(system) architecture
  • whether the JVM is inside a JRE or a JDK (as of 11.02.2008 - not yet implemented)
• there is a way to point the launcher to a specific JVM that should be used for launching the target application by pointing to the corresponding "javahome"; the JVM is validated and if it's not valid an appropriate error message is shown
  • the parameter which controls this is --javahome <path>
• the launcher is able to "bundle" a JVM which is used as the fallback in case no suitable JVMs could be found on the system
• the launcher is able to "bundle" the jar file and required libraries resources, in this case they are extracted prior to being launched
• the launcher is able to work with an external jar file, in this case the launcher is responsible for verifying the presence and but not the integrity of the resources
• if there is need to extract the target jar file and its resources/libraries, the launcher is able to verify whether there is enough free disk space in the target directory; if there is not enough space, an appropriate error message is shown
• it is possible to tell the launcher where to extract the jar file and its resources (i.e. specify a local "working" directory)
  • the command-line parameter which controls this is --tempdir <path>
• it is possible to tell the launcher to extract the jar file and its resources without actually launching the application (this is not applicable in case of external jar)
  • the command-line parameter which controls this is --extract <path>
• by default the launcher operate in either a GUI or a console UI mode (as of 11.02.2008 - for windows only GUI launcher is available)
• the launcher support being executed in a silent mode
  • the command-line parameter for silent mode is --silent
  • this argument is then placed to the application arguments list
• the launcher supports being executed with non-default locale
  • the command-line parameter for setting locale is --locale <name>
  • this argument is then placed to the application arguments list
• the launcher supports redirecting the <stdin>, <stdout> and <stderr> of the underlying java process to the console and/or log file
• the launcher is able to log its actions to the console and/or log file
• the error code of the launcher is the same as of the underlying java process
• the launcher is "transparent" in terms of command-line arguments, i.e. all command line arguments passed to the launcher are transferred to the java process (-J prefix is used for JVM options, not arguments)
• the launcher supports the "default" values for command-line parameters and JVM parameters, i.e. there is a possibility to define which parameters will be defined at the launcher's "build" time
• all launcher's messages are i18n compatible, if possible within the given platform
• the launcher is able to verify the integrity of bundled resources (as of 11.02.2008 - CRC32 for windows, md5 for unixes)
• the launcher icon is configurable
  • [MacOS] using nbi.java.application.icon property otherwise blocked by nbi.not.set.dock.icon property
  • [Windows] using icon file in *.ico format and defined in resources file