Enterprise Manager: App Deployment

Overview and Background

In BBj 19.20 and later, BBj offers users two options for deploying their applications from a BBjServices server to a client computer. These App Deployments are set up and managed through the Enterprise Manager, where BBj applications can be configured as a Web App for execution in a browser as a Browser User Interface (BUI) deployment, as a Desktop App for execution as a BBj thin client deployment (replacing Java Web Start), or as both. Both Web Apps and Desktop Apps can be run from hyperlinks that are found on BBj’s Jetty Home Page.

Web Apps have been available in BBj for a number of years, and rely upon the BUI technology in BBj. Web Apps are truly zero deployment—the only technology or installation needed on a client computer is a compatible web browser; no Java or BBj is required there.

Starting in BBj 19.20, Desktop Apps provide a near-zero deployment strategy for running BBj applications on a client desktop computer. Since Java Web Start is no longer supported in Java 11+, Desktop Apps are intended to replace Java Web Start (JNLP) Applications for deploying desktop applications. They provide a straightforward system for deploying BBj applications that overcomes many of the limitations of Java Web Start.

In Desktop Apps, the client-side experience is particularly streamlined, with no configuration necessary on the desktop to run the app. The client computer does not even need a BBj installation! MacOS and Linux clients do require Java, while Windows clients do not need either BBj or Java. The URL for a Desktop App provides a download of a small, self-contained launcher program that connects to the server, downloads the Java Runtime Engine (JRE) required by the server, downloads the BBj program and any necessary BBj classes, launches the BBj program, and updates as necessary each time the program is run.

The server-side App Deployment experience is also streamlined. Web Apps (BUI) and Desktop Apps are configured for a single application via the Enterprise Manager under Web > App Deployment. Each application offers configuration properties that apply generally to both Web and Desktop Apps, as well as properties that are specific to one or the other. The Java Runtime Engine (JRE) list gives you full control over which JRE your app should use, and JREs can be added for Windows, Linux, and macOS clients. The URLs for each enabled application appear on the Jetty Home Page, and can also be provided to users directly.

For additional information, see the App Deployment Tutorial.

Desktop Apps

Comparison to Java Web Start

Java Web Start was a generic solution designed to work for many different use cases, so it was not always optimal for BBj. Because Desktop Apps are designed with BBj Applications in mind, they are able to provide several advantages over Java Web Start, and overcome some of Web Start’s limitations. The table below compares the Java Web Start and Desktop App technologies.

Java Web Start Limitations	Desktop Apps Solutions
Web Start required the creation and management of the JNLP, which could be complicated and included many settings that are not needed or used for BBj applications.	Desktop Apps only expose settings that BBj applications may need, and can share some application specifications with Web Apps.
A Web Start security certificate had to be generated and included when running the application.	A Web Start security certificate is no longer needed.
JARs had to be signed before being downloaded to client.	JARs are no longer sent to the client (just classes), so there is no longer a requirement for JAR signing.
Clients needed a Java Web Start (javaws) program, which was installed as part of Java 8 and earlier.	No existing launch program necessary, just Java.
Invalid client configuration could prevent application from working.	No client configuration needed.
Cache could prevent execution, and had to be cleared on client.	No cache for the user to clear.
Application startup included validation of JARs in cache and downloading JARs from server.	Desktop Apps utilizes the new ClassLoader to optimize the download of necessary classes (not JARs) and files at run time.

Table 1: Desktop Apps compared to Java Web Start

Comparison to JNLPExePacker

The JNLPExePacker was designed to be an interim solution to mitigate the loss of Java Web Start until the final Desktop Apps solution could be developed. It is a BBj program, installed and run via the pluginmanager program, which creates a native Windows/macOS/Linux application given a JNLP application and a JRE. It takes advantage of the new ClassLoader in BBj 19.10 and higher to dynamically download needed classes and files to the client.

The JNLPExePacker had several limitations. The JNLP application had to exist before native application generation, which is problematic because JNLP and Web Start apps are going away. Additionally, any update in the JNLP, BBj, or JRE required regeneration and redeployment of the native applications.

Creating a Desktop App

To deploy a Desktop App, first open the Enterprise Manager. Expand the Web and App Deployment nodes in the navigator, then double-click Applications. Figure 1 shows the resulting Applications tab in the EM:

Figure 1: Desktop Apps Configuration in Enterprise Manager

Click the green Plus button at the top right of the section to add a new App. This will open a blank Applications properties window as shown in Figure 2, which you can proceed to fill in.

Figure 2: Creating a new Desktop App, General Properties

Enter a unique name for your App, and select the BBj program file to run. Optionally, you may specify a Config File, Working Directory, the application's Interpreter User, Classpath, along with any Program Arguments needed. Configuration options are described in more detail below in the App Deployment Configuration section.

BBj will publish this app as a Desktop App if Desktop App Enabled is checked. Similarly, it will publish this app as a Web App (runnable in a browser) if Web App (BUI) Enabled is checked.

If you selected Web App (BUI) Enabled, expand the Web App Only section to review the settings that are specific to Web Apps (as shown in Figure 3).

Figure 3: Web App Only Properties

See the App Deployment Configuration section below for more information on each option.

Expand the Desktop Only section to review settings that are specific to Desktop Apps (as shown in Figure 4).

Figure 4: Desktop App Only Properties

See the App Deployment Configuration section below for detailed information on each option.

Running a Desktop App

Every BBj installation includes a Jetty Start Page, which now includes a list of Web and Desktop Apps. The Jetty Start Page can be accessed with the following URL, replacing "localhost:8888" with the appropriate host and port number if BBj is not running locally:

http://localhost:8888/basisindex.html

The Jetty Home Page displays a list of all available Web and Desktop Apps, as shown in Figure 5:

Figure 5: Web and Desktop Apps on the Jetty Home Page

Clicking the hyperlinked app name will run or download the app.

These URLs can also be found by selecting the app name under Web > App Deployment > Applications as shown in Figure 6:

Figure 6: Web and Desktop App URLs in the Enterprise Manager

Each Web App URL runs the browser-based version of an application, and abides by the Web App Only settings.

Each Desktop App URL downloads a single executable JAR called <appname>launcher.jar, which is a self-contained launcher program. It contains the launcher Java program, the JRE information, and the Desktop app information.

When the launcher JAR is run, it creates a native application to run the BBj program which is used for subsequent Desktop App invocations (either a Windows native EXE, a macOS Mac App, or a Linux shell script). It then runs the native application.

When it creates the native application, it creates an install directory under <User Home> on Windows and Linux or under /Applications on macOS. It then downloads and extracts the specified JRE for the App into the installation directory. Note that because one app per client is the norm with Desktop Apps, JRE sharing is not supported.

The native application will be created in the following format:

OS	Format
Windows	<userhome>\<appname>\bin\<appname>.exe
Linux	<userhome>/<appname>/bin/<appname>.sh
macOS	/Applications/<appname>.app

Table 2: Desktop App Native Applications

When the native application is run, it downloads and installs any needed JARs from the server, detects the JRE and installs one if needed, and updates itself as necessary. It abides by the Desktop Only settings from the Enterprise Manager and applies the specified program arguments. Activity is written to the log file, and to the console if it is available.

App Deployment Configuration

Apps can be configured on a case-by-case basis, but some settings can be applied globally under Web > App Deployment > Global Settings as shown in Figure 7:

Figure 7: App Deployment Global Settings

JREs can be assigned to Desktop Apps under Web > App Deployment > Desktop App JREs. Click the green plus button at the top right of the section, and select either macOS, Linux, or Windows depending on which JRE you are adding. Place a check next to a JRE to designate it as the default for the client. To remove a JRE, select it and click the red minus button in the top right of the section.

Figure 8: Desktop App JREs

Application-specific settings can be accessed by navigating to the list of applications under Web > App Deployment > Applications and double-clicking the application name.

General

The settings under the General category apply to both Web and Desktop Apps (See Figure 2).

Setting	Description
Application Name	The name of the application. This name must be unique in order to create a unique URL for the App. It should not contain any special characters that affect URL parsing, such as spaces, slashes, curly brackets, %’s, or #’s.
Program File	The full path and name of the BBj program that the application should run.
Config File	The config file that the application should use. Leave blank to use the default config.bbx.
Working Directory	Specifies the server directory in which BBj will start. Leave blank to use the default working directory.
Interpreter User (-u)	Specifies the user account to be used for Data Server and AppServer access. Leave blank to use the default user account.
Classpath	Specifies the session-specific classpath that the application should use. Leave blank to use the default classpath.
Program Arguments	Use the plus and minus buttons to add and remove program arguments.
Load Image	Specifies the image to display while the program is loading. When not specified, a default animated GIF is used. Supported image formats are .jpg, .png, and .gif. Note: Large images and animations can negatively affect load times.
Shortcut Image	Specifies the image that will be displayed in the application shortcut. When not specified, a default BBj "teacup" image is used. Supported image formats are .jpg and .png. Note: Large images and animations can negatively affect load times.
Quiet	Suppresses the start-up message and is useful when running from a background process.
Secure Connection	Connect to the Secure Thin Client Server. This is equivalent to the -SC command line option. See BBjAppServer::setSecure.
Web App (BUI) Enabled	Select to enable deploying this application as a BUI App. Its URL will be displayed on the Jetty Start Page under Web Apps.
Desktop App Enabled	Select to enable deploying this application as a Desktop App. Its URL will be displayed on the Jetty Start Page under Desktop Apps.

Table 3: General App Deployment Properties

Web App Only

The settings under the Web App Only section only apply to Web Apps. (See Figure 3).

Setting	Description
Show Browser Warning	This setting is obsolete and ignored.
Show Confirm Close Dialog	Display a confirmation dialog when the user attempts to leave the application's page. Some browsers, including Mobile Safari on iOS, never prompt the user when navigating away from a page.
Manage Browser History	BUI apps tend to be stateful; data can be lost if the user accidentally presses the browser 'back' button. When this mode is set, BUI manages browser history and the 'back' button. See BBjAppServer::setManageBrowserHistory.
Disallow Console	Disallow console access. This is recommended for end-user production applications.
Terminal	The alias of a terminal specified in the configuration file. FID(0) will return this alias in the Thin Client program.
Development Mode	BUI normally suppresses the default browser handling for function keys F1-F12. When development mode is set, BUI allows the normal browser handling for those keys to take effect.
Omit BASIS CSS	Run BUI apps without the default BASIS CSS. By default, BUI apps are deployed with a complex CSS file defining detailed rules for each BBjControl. When this mode is set, that default CSS file is omitted, and the developer is responsible for providing all necessary CSS rules. See BBjAppServer::setOmitBasisCSS.
CSS	The optional custom CSS file for the Web App (BUI) to use. This custom CSS is applied last, providing the ability to override CSS entries in either the GWT or BASIS CSS files.
Client Response Timeout	This sets the length of time in seconds a non-responsive BUI session will be considered active. If the session expires without response, the web tier will send a NET_DROPPED error back to the server. A value of -1 means no timeout. The default value is 300.
Context	Select the Jetty web server context for this application from those defined in the Enterprise Manager.

Table 4: Web App Only Properties

Desktop Only

The settings under the Desktop Only section will only apply to Desktop Apps.

Setting	Description
Java Arguments	Use the plus and minus buttons to add and remove arguments.
Terminal	The alias of a terminal specified in the configuration file. FID(0) will return this alias in the Thin Client program.
Linux JVM	Specify the JRE to deploy on Linux clients.
Windows JVM	Specify the JRE to deploy on Windows clients.
macOS JVM	Specify the JRE to deploy on macOS clients.
Name (-a)	Arbitrary text to associate with the Sysconsole settings so that the size, font, and position of the Sysconsole are saved when the session and is closed and recalled when the Sysconsole is invoked again with the same text. Equivalent to using the Application User (-n) setting.
Application User (-n)	Arbitrary text to associate with the Sysconsole settings so that the size, font, and position of the Sysconsole are saved when the session and is closed and recalled when the Sysconsole is invoked again with the same text. Equivalent to using the Name (-a) setting.
Remote Host	Specifies the machine name or IP address of the server on which the ThinClientServer (TCS) or SecureThinClientServer (STCS) if using the -SC argument resides. The BBj process connects to the ThinClientProxyServer (TCPS) on the local machine (refer to -LP<local port number>). The TCPS connects to the TCS (or STCS) on the machine specified by this argument using either the default port or the port specified with the option -RP<remote port number>.
Remote Port	Specifies the ThinClientServer's (TCS) port on the remote machine. The BBj process connects to the ThinClientProxyServer (TCPS) on the local machine (see -LP<local port number>). The TCPS makes the connection to the remote machine (specified with the -RH<host name> argument) using the remote port number. If no remote port number is specified, the default port, 2003, is used. When using the -SC flag, the TCPS connects to the SecureThinClientServer (STCS). The STCS default port is 2103. The ports used by TCS and STCS can be changed using Enterprise Manager.
Local Port	Specifies the Port Request Server's (PRS) port. The BBj process connects to the PRS to get the appropriate port to use to connect to the ThinClientProxyServer. By default, the PRS uses port 2008. The PRS's port may be changed using the Enterprise Manager.
Look and Feel	Specifies the look and feel the BBj session uses. Valid options are: default - uses the look and feel of the native operating system; Windows look and feel when running Windows; Mac look and feel running on a Mac, "cross" for cross-platform, etc. For example: bbj -Lfdefault cross - uses the default Java look and feel; "ocean" in JVMs 1.5 and higher, and "metal" in JVMs prior to 1.5. none - do not attempt to set or change the look and feel in any way. This is intended for use with a launcher program such as skinit, which sets the look and feel before BBj is started. skinlf:theme (deprecated) - use the skinlf.jar look and feel. You may use a filename or a URL to specify the specific theme, but you must use forward slashes for the path separator regardless of platform. For example, to use a file: bbj -LFskinlf:themepack.zip To use a URL: bbj -LFskinlf:http://mydomain.com/themepack.zip vpro5 - emulates the Visual PRO/5 look and feel on all platforms, regardless of operating system.
INF (JVM sharing)	Any BBj Thin Client JVM started with an INF tag will attempt to share resources with any other BBj Thin Client started with the same tag.
TCPS Preload	The BBj process checks with the PortRequestServer to see if a ThinClientProxyServer for the user/host/display is running. If one is not running, the BBj process starts up the TCPS. In either case, whether it starts a TCPS or one is already running, the BBj process terminates without starting an interpreter. (Note: no license is checked out since no interpreter is started.)
TCPS Timeout	If the TCPS is started by this invocation of the BBj process, this value is passed to the TCPS as the "death wait" timeout. The "death wait" timeout is how long the TCPS stays up with no clients connected before terminating. This can be used to keep the TCPS up and running so it is not restarted each time a new BBj session is started. This overrides the property com.basis.bbj.comm.ThinClientProxyServer.waitTime found in the BBj.properties file. This allows the timeout to be set differently for individual TCPS's. The wait time for the first client connection is 5 minutes and 1 millisecond, even if this value is set to a shorter time. If this value is higher than 5 minutes and 1 millisecond, the higher value is used.
TCPS Heartbeat	In BBj 17.00 and higher, if the TCPS is started by this invocation of the BBj process, this value is passed to the TCPS as the "heartbeat" timeout. The "heartbeat" timeout is used by the TCPS to check the status of the ProxyManagerServer (PMS). If the PMS goes down, then the TCPS shuts down. Normally, the PMS is started as part of BBjServices, so when BBjServices is shutdown the PMS is also shutdown.

Table 5: Desktop App Only Properties

Other Settings

Some less common Desktop App settings can be set via the following environment variables on the client machine:

Environment Variable	Description
BBJ_CACHE_DIR	Set this to a directory to use the specified directory for the cache, rather than the default directory. The default cache locations for different platforms are listed below: Windows: From the environment "LOCALAPPDATA", or "APPDATA" in the Local subdirectory. If these are not set, then the default is: ~/AppData/Local Mac: ~/Library/Caches Other: ~/.cache
BBJ_CACHE_SHARED	In BBj 22.00 and higher, this setting can set the permissions on the cache files to be readable and writable by all users, allowing multiple users to share a cache directory. This can help save disk space if multiple users are using desktop apps on the same machine. true = Creates and stores the cache in a directory named "remoteclassloader-shared". false = Stores the cache in a directory named "remoteclassloader-<user>". This is the behavior by default.

Environment Variable

Description

BBJ_CACHE_DIR

Set this to a directory to use the specified directory for the cache, rather than the default directory.

The default cache locations for different platforms are listed below:

Windows: From the environment "LOCALAPPDATA", or "APPDATA" in the Local subdirectory. If these are not set, then the default is: ~/AppData/Local
Mac: ~/Library/Caches
Other: ~/.cache

BBJ_CACHE_SHARED

In BBj 22.00 and higher, this setting can set the permissions on the cache files to be readable and writable by all users, allowing multiple users to share a cache directory. This can help save disk space if multiple users are using desktop apps on the same machine.

true = Creates and stores the cache in a directory named "remoteclassloader-shared".
false = Stores the cache in a directory named "remoteclassloader-<user>". This is the behavior by default.

Summary

As of BBj 19.20, Deployment Apps offer you two choices of how to deploy your BBj programs to client computers:

Web Apps (for GUI BBj programs running in a web browser as BUI apps)
Desktop Apps (as BBj thin client programs, replacing the Java Web Start remote deployment)

These deployment options are managed from the Enterprise Manager, under Web > App Deployment.