Enterprise Manager logoEM: App Deployment > Applications

Overview and Background

In BBj 25.10 and higher, BBj offers users four options for deploying their applications from a BBjServices server to a client computer. These deployment options—BUI Web Apps, DWC Web Apps, Desktop Apps, and now WebUI—are managed through the Enterprise Manager.

BUI Web Apps run in a browser using the BBj Browser User Interface (BUI).

DWC Web Apps run in a browser using the BBj Dynamic Web Client (DWC).

Desktop Apps run as thin client deployments through the BBj runtime.

WebUI, introduced in BBj 25.10, provides a modern, browser-based framework for delivering BBj applications with enhanced performance, session control, and streamlined configuration.

BUI Web Apps, DWC Web Apps, and WebUI are truly zero-deployment—the only technology or installation needed on a client computer is a compatible web browser; no Java or BBj installation is required there.

Starting in BBj 19.20, Desktop Apps provided 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 replaced 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 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 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. BUI Web Apps, DWC Web Apps, Desktop Apps, and WebUI applications are configured for a single interface via the Enterprise Manager. Each application offers configuration properties that apply generally to all deployment types, as well as properties specific to one or more. 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 App Deployment Tutorial.

Location

Enterprise Manager logoEM Navigator → Web → App Deployment → Applications

Toolbar

Button Function
Adds a new entry and opens new application.
Modifies the configuration or details of a selected application.
Duplicates the configuration or data of a selected application.
Removes/deletes selected application(s) or files from the system.
refresh button Refreshes the displayed list of applications and their status.
Navigates up one level to the parent directory from the current folder.
Creates a new folder within the currently displayed directory.
Enables to choose a folder/file from your local system.

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.

Comparison of Java Web Start and Desktop Apps Solutions Table

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.

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 EM : Web > App Deployment > Applications nodes in the navigator, then double-click Applications, the Applications pane shows on the right.

Applications

The Applications pane in Enterprise Manager provides a centralized interface for managing and monitoring deployed BBj web and desktop applications. It lists all registered application contexts along with their corresponding deployment types and operational statuses, including BUI Web App Status, DWC Web App Status, WebUI App Status, and Desktop App Status. Administrators can review application launch details, verify deployment states, access URLs, and confirm modification timestamps. Integrated with the App Deployment framework, this pane facilitates streamlined visibility into application availability, runtime behavior, and service connectivity across all BBjServices instances.

Applications Properties List

Column Description
Name Displays the application's name, often clickable to view more details.
BUI Web App Status Displays the current status of the application when accessed via Browser User Interface (BUI).
DWC Web App Status Displays the current status of the application when accessed via Dynamic Web Client (DWC).
WebUI App Status Indicates the operational state of the WebUI application. Shows active when the application is deployed and running, or inactive when undeployed or stopped by BBjServices.
Desktop App Status Displays if desktop applications are running, stopped, or not deployed.
Modified Displays when an application was last changed, allowing you to sort and find recently updated ones.

Application Launch Details Properties

Column Description
Type Displays the category or main way to launch an application, such as Web URL or Desktop Shortcut.
URL Displays the direct web address or link needed to access or launch the application.

The icons, located in the Enterprise Manager UI's Applications and Properties action bar, provide quick, consistent control for managing your application portfolio, including adding, modifying, duplicating, removing, refreshing, navigating, and adding folder.

Click button at the top right of the section to add a new App. This will open Applications properties window, which you can proceed to fill in.

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.

BBj will publish multiple versions of this app based on checked selections among BUI Web App Enabled, DWC Web App Enabled, WebUI App Enabled, and Desktop App Enabled.

The settings under the General category apply to all deployment options.

The settings under BUI/DWC Only, Desktop Only, and WebUI Only apply to specific deployment options.

General App Deployment

The General App Deployment controls core launch/runtime for a shortcut: Application Name, Program/Config files, Working Directory, default or explicit Interpreter User (-u), Host/Port overrides, Classpath, Program Arguments, Shortcut Name/Description/Image/Load Image, Quiet mode, and enablement flags for BUI, DWC, WebUI, and Desktop apps.

General App Deployment Properties List

Settings Description

Application Name

Displays 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

Displays the main executable or program file for the application. Click to browse and select the file from your local system.

Config File

Displays the config file that the application should use. Leave blank to use the default config.bbx. Else click to select file from your local system, or click to create a new folder .

Working Directory

Displays the server directory in which BBj will start. Leave blank to use the default working directory. Click to select file from your local system, or click to create new folder. See: command line.
Use Default Interpreter User

  • When Unchecked, this enables you to manually specify a different user account in the Interpreter User (-u) field for the application to run under.

  • When Checked, the application will automatically use the current desktop user's credentials or context as the interpreter user.

Interpreter User (- u)

Enables you to specify a particular user account under which the application's interpreter will run.
Host Override

Displays the host used by the desktop application client to connect to Jetty. If undefined, the host will be the Hostname defined for the Web server. To manage servers, select BBjServices > Servers.
Port Override

Displays the port number used by the desktop application client to connect to Jetty. If undefined, the port will be the HTTP Port defined for the Web server. To manage servers, select BBjServices > Servers.

Classpath

Displays the session-specific classpath, which tells the Java Virtual Machine (JVM) where to find necessary class files and libraries for the application. Users can select <default> to use the system's global settings, or choose from other predefined options like addon,barista, basisdemos, and bbj_default to apply specific library paths. See: BBjServices > Java Settings

Value Description
<default> Uses the system's pre-configured global classpath settings for the application.
addon Classpath includes addon components or extensions for the application.
barista Classpath containing libraries or resources specific to a barista framework or application.
basisdemos Classpath includes files or examples provided by BASIS.
bbj_default Sets the default classpath specifically tailored for BBj applications.

Program Arguments

User-defined command line arguments, accessed with ARGC and ARGV().Click the button to add and click button to remove program arguments.

Shortcut Name

Displays the name for the application's shortcut, typically appearing on a desktop or in a menu. It provides a user-friendly label for quick access.

Shortcut Description

Enables adding a brief explanation or descriptive text for the application's shortcut.

Shortcut Image

Enables selecting a custom icon file to visually represent the application's shortcut. The dropdown offers predefined images, while the icon allows uploading new ones. See: Resources.

Note: Large images can negatively affect load time.

Load Image

Enables to select an image to be displayed as a splash screen or loading indicator when the application starts. Clicking button enables to upload new images. See: Resources.

Note: Large images can negatively affect load time.

Quiet

  • When unchecked, displays the start-up message and splash window.

  • When checked, suppresses the start-up message and splash window. See: command line.

BUI Web App Enabled

  • When unchecked, the application cannot be accessed through the Browser User Interface (BUI).

  • When checked, enables application access and deployment via the Browser User Interface (BUI).
DWC Web App Enabled

  • When unchecked, the application cannot be accessed through the Dynamic Web Client (DWC).

  • When checked, enables the application's deployment and access via the Dynamic Web Client (DWC).
WebUI App Enabled

  • When unchecked, the application cannot be accessed through the WebUI.

  • When checked: Enables WebUI deployment for this application.

Note: WebUI is a premium, licensed feature and isn’t available by default.
Desktop App Enabled

  • When unchecked, the application cannot be installed or run as a Desktop App.

  • When checked: Enables installation and execution as a Desktop App.

BUI/DWC Only

The BUI/DWC Only section contains configuration properties specific to BUI and DWC applications in the browser.

BUI/DWC Only Properties List

Settings Description

Show Browser Warning

Note: This setting is Obsolete.

Show Confirm Close Dialog

Displays whether a confirmation prompt appears before closing an application window or tab, preventing accidental data loss.

Value Description
<default> Configures the application to use its pre-defined, standard behavior for displaying a close confirmation dialog.
false Disables the confirmation dialog, allowing the application or window to close immediately without a prompt.
true Enables the confirmation dialog, requiring user confirmation before the application or window closes.

Note: Desktop browsers only show this warning if the user has interacted with the page. Mobile browsers never show this warning. See: beforeunload event.

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.

Value Description
<default> Configures the application to use its pre-defined, standard behavior for managing browser history.
false Disables the application's management of browser history, browsing activity will not be recorded.
true Enables the application to manage browser history, allowing it to record and utilize browsing activity.

Disallow Console

Disallow console access. This is recommended for end-user applications.

Value description
<default> Displays that the console's accessibility or output behavior is determined by the system's pre-configured settings.
false Permits full access to the console and enables its functionality.
true Restricts access to the console or disables its output.

Terminal

The alias of a terminal specified in the configuration file. FID(0) will return this alias in the Thin Client program. See: command line.

Development Mode

BUI normally suppresses the default browser handling for function keys F1-F24. When development mode is set, BUI allows the normal browser handling for those keys to take effect. See: BBjAppServer::setDevelopmentMode.

Value Description
<default> Displays that the application's behavior for Development Mode is determined by its pre-configured system settings.
false Optimizing the application for production use by prioritizing performance and security while minimizing debugging features.
true Activating features designed for rapid iteration, testing, and debugging, which may impact performance and security.

Omit BASIS CSS

Run BUI Web 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.

Value description
<default> Uses the system's pre-configured global setting for omitting BASIS CSS.
false Includes the default BASIS CSS.
true Omits the default BASIS CSS.

Note: This setting is intended for specialized applications. Significant BUI behavior is controlled by the default CSS; omitting it will break most applications.

CSS

The optional custom CSS file for the BUI Web App to apply interface styling. Clicking the icon opens the Select CSS File dialog, where users can browse local directories or navigate to an existing stylesheet. Selecting the icon allows the creation of a new folder through the Create New Folder dialog before file selection. Once chosen, the CSS file is applied last in the rendering sequence, overriding default GWT or BASIS CSS definitions to ensure customized, deployment-specific styling consistency. See: Resources.

Client Response Timeout

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

Specifies the operational context or environment in which the web application will run, with root being a common default. See: Context Configuration.

Value Description
root Sets the application to the default or base web context, making it accessible directly from the server's root URL.
GoldMine Sets the application's context to GoldMine, indicating it will be accessed via a URL path segment of that name.
htdocs Sets the application's context to htdocs.
BBJSP Sets the application's context to BBJSP, typically used for applications utilizing BASIS BBj Server Pages.
Secure TC Connection

Enables to set the application's Thin Client (TC) communication to use the system's pre-configured global setting (<default>), explicitly disable it false, or explicitly enable a secure encrypted connection true. See: BBjAppServer::setSecure

Value Description
<default> Enables system's pre-configured global setting for establishing a secure Thin Client Connection.
false Disables a Secure Thin Client Connection for the application.
true Enables a secure encrypted Thin Client Connection for the application.
Remote Host The hostname or IP address of a remote server that the web application connects.
Remote Port Displays the port number on the remote host that the web application will use for its connection.
End Action

Dropdown selecting termination action: NONE, DEFAULT, URL, APP, MESSAGE. DEFAULT follows configuration. URL redirects to address, APP launches app, MESSAGE shows text, NONE does nothing. See: BBjBuiCloseAction.

Value Description
NONE Specifies that no special termination action occurs. The session ends normally and no redirect, application launch, or message display is triggered.
DEFAULT Uses the context’s configured default behavior for termination, inherits global or parent-configuration action when the session ends.
URL Redirects the terminated BUI/DWC session to the specified web address. Requires entering a fully qualified URL for correct redirection.
APP Launches the specified secondary application when the session ends. Requires providing the application name; termination occurs only after that application starts.
MESSAGE Displays the specified text message to the user when the session ends. User must provide the message content for display
End Application Designates the application-name to launch when End Action: APP is selected; if blank, no additional application executes at session end.
End Message Specifies the text to present to the user when End Action: MESSAGE is selected, replacing the standard termination outcome with that message.
End URL Specifies the redirect address when End Action: URL is selected; the session navigates to this URL after termination.
Error Action

Controls how the BUI/DWC session behaves when an error occurs, inherit default action, perform no action, redirect, launch application, or display a message. See: BBjBuiCloseAction.

Value Description
NONE Indicates that no error-handling action will occur when the session fails. The session simply ends without redirect, application launch, or message.
DEFAULT Inherits the termination behavior defined at the higher-level configuration (parent or global); no specific action is executed at session end. See: BBjBuiCloseAction.
URL Redirects the session to a specified web address when Error Action: URL is selected, the URL must be provided in the field.
APP Launches a specified secondary application when “Error Action: APP” is selected; the user must provide the application name for execution.
MESSAGE Presents a custom text-message to the user when Error Action: MESSAGE is selected, requires providing the display message content.
Error Application Specifies the application to launch when Error Action: APP is selected; if left blank, no application will be triggered upon error.
Error Message Provides the custom text shown to the user when Error Action: MESSAGE is selected, replacing the default error notification display.
Error URL Specifies the web address for redirection when Error Action: URL is selected; session ends and client navigates to that URL.

Desktop App Only

The Desktop App Only section provides configuration options specific to deploying and running BBj desktop applications. It allows you to define Java Arguments, select platform-specific JREs (Linux, Windows, macOS), and configure network settings such as Remote Host and Ports. Options like Standalone JVM, Socket Compression, and Look and Feel give further control over how the desktop app runs and communicates. Additionally, settings like Create Shortcut, Display Load Image, and Display Run Message enhance the end-user experience during app startup. These configurations ensure the desktop application is optimized, portable, and tailored for the target platform and network environment.

Desktop App Only Properties List

Setting Description

Java Arguments

Enables passing additional parameters to the Java Virtual Machine (JVM) when the application runs. The and icons enable adding or removing/deleting arguments.

Terminal

Enables the alias of a terminal specified in the configuration file. FID(0) will return this alias in the Thin Client program. See: command line.

Linux x64 JRE

Enables selecting the Java Runtime Environment (JRE) version for applications running on 64-bit Linux systems. The <default>, indicating that the system uses the globally configured JRE if no custom package is assigned. Clicking the icon opens the Select JRE Package dialog, allowing users to navigate directories or select a compressed JRE package (*.gz, *.tgz, .zip). Within this dialog, selecting the icon enables creating a new directory via the Create New Folder dialog before file selection. Once configured, the selected JRE package is added to the JRE configuration list and can be applied to application deployments as needed.

Windows x64 JRE

Enables selecting the Java Runtime Environment (JRE) version for applications running on 64-bit Windows systems. The <default>, indicating that the system uses the globally configured JRE if no custom package is assigned. Clicking the icon opens the Select JRE Package dialog, allowing users to navigate directories or select a compressed JRE package (*.gz, *.tgz, .zip). Within this dialog, selecting the icon enables creating a new directory via the Create New Folder dialog before file selection. Once configured, the selected JRE package is added to the JRE configuration list and can be applied to application deployments as needed.

macOS x64 JRE

Enables selecting the Java Runtime Environment (JRE) version for applications running on 64-bit macOS systems. The <default>, indicating that the system uses the globally configured JRE if no custom package is assigned. Clicking the icon opens the Select JRE Package dialog, allowing users to navigate directories or select a compressed JRE package (*.gz, *.tgz, .zip). Within this dialog, selecting the icon enables creating a new directory via the Create New Folder dialog before file selection. Once configured, the selected JRE package is added to the JRE configuration list and can be applied to application deployments as needed.
macOS aarch64 JRE

Enables selecting the Java Runtime Environment (JRE) version for applications running on 64-bit macOS (Apple Silicon) systems. The <default>, indicating that the system uses the globally configured JRE if no custom package is assigned. Clicking the icon opens the Select JRE Package dialog, allowing users to navigate directories or select a compressed JRE package (*.gz, *.tgz, .zip). Within this dialog, selecting the icon enables creating a new directory via the Create New Folder dialog before file selection. Once configured, the selected JRE package is added to the JRE configuration list and can be applied to application deployments as needed.

Name (-a)

Associates text with SysConsole settings so that window size, font, and position are saved when the session ends and restored when the SysConsole is launched using the same text. Equivalent to using the Application User (-n) setting. See: command line.

Application User (-n)

Associates arbitrary text with the SysConsole settings, saving window size, font, and position at session end and restoring them when the SysConsole is launched with the same text. Equivalent to using the Name (-a) setting. See: command line.
Secure TC Connection

Enables to set the application's Thin Client TC communication to use the system's pre-configured global setting (<default>), explicitly disable it false, or explicitly enable a secure encrypted connection true. See: BBjAppServer::setSecure .

Value Description
<default> Uses the system's pre-configured global setting for establishing a secure Thin Client Connection.
false Disables a secure Thin Client Connection for the application.
true Enables a secure encryptedThin Client Connection for the application.

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.

  • vpro5 - emulates the Visual PRO/5 look and feel on all platforms, regardless of operating system.
Standalone JVM

  • When unchecked, the Desktop Application will share JVMs with other Desktop Application and BBj Thin Clients.

  • When checked, a new JVM will be started for the Desktop Application.

TCPS Preload

  • When unchecked, The BBj process does not perform a TCPS Preload.

  • When checked, BBj checks for a PortRequestServer or ThinClientProxyServer on the specified user/host/display. If none is found, it starts a TCPS process without launching an interpreter or checking out a license.

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.
Debug

  • When unchecked, debugging is disabled; the application runs without additional diagnostic output.

  • When checked: enables debugging mode, providing extended logging for development and issue resolution.
Create Shortcut

  • When unchecked, no desktop shortcut is created during application installation.

  • When checked, automatically creates a desktop shortcut for the application upon installation.
Display Load Image

  • When unchecked, the loading image is not displayed during application startup, resulting in no visual feedback.

  • When checked, screen or loading image is displayed, providing users with visual feedback while the application initializes.
Display Load Text

  • When unchecked, no loading text is shown during the application's startup.

  • When checked, displays message that provide feedback during the application's loading process.
Run After Install

  • When unchecked, prevents the installed application from automatically launching after installation, completing setup without invoking post-install execution routines.

  • When checked, triggers post-install execution by invoking BBj’s AfterInstallCustomActionData class, enabling automatic application launch immediately after installation completes. See: AfterInstallCustomActionData.
Display Run Message

  • When unchecked, runtime status messages are not shown during application execution.

  • When checked, displays messages reflecting the application's runtime activity.
Use Socket Compression

  • When unchecked, socket communication occurs without data compression.

  • When checked, enables GZIP compression for socket communication to reduce bandwidth usage and improve transmission efficiency

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:

Jetty Home page

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 EM: Web > App Deployment > Applications.

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

WebUI Only

The WebUI Only section defines configuration properties exclusive to BBj WebUI applications, controlling runtime display, virtual display setup, and secure communication for headless or browser based execution. The section includes options such as Java arguments, terminal designation, connection parameters, and user credentials. This section references key BBjServices properties including webui.enabled, webui.display, and webui.virtualdisplay.prog, which determine whether BBjServices runs in graphical or headless mode. When the DISPLAY environment variable is not set, BBj automatically invokes xheadless/xvfb to create a virtual display, ensuring proper WebUI initialization on UNIX and AIX platforms. By default, xheadless is used on Linux systems and xvfb on AIX. Note that xheadless requires glibc 2.18 or later; on older Linux distributions using glibc 2.17, administrators must set the WebUI Virtual Display Program to xvfb using /usr/bin/xvfb-run. On UNIX systems, this section visually displays configuration fields such as WebUI Enabled, WebUI Context Mapping, WebUI Display, and WebUI Virtual Display Program, providing administrators with clear control over headless WebUI operation and system-level display handling. See: Global Settings.

WebUI Only Settings List

Settings Description
Java Arguments

Enables passing additional parameters to the Java Virtual Machine (JVM) when the application runs. The icon adds a new argument line, allowing multiple entries to be defined, while the icon removes selected arguments.

Terminal

Enables the alias of a terminal specified in the configuration file. FID(0) will return this alias in the Thin Client program. See: command line.
Name(-a)

Associates text with SysConsole settings so that window size, font, and position are saved when the session ends and restored when the SysConsole is launched using the same text. Equivalent to using the Application User (-n) setting. See: command line.
Application User(-n)

Associates arbitrary text with the SysConsole settings, saving window size, font, and position at session end and restoring them when the SysConsole is launched with the same text. Equivalent to using the Name (-a) setting. See: command line.
Goodbye URL

Specifies the endpoint that BBjServices redirects to when a WebUI session ends. Used for session termination and user redirection after logout. This setting applies to all supported platforms and is not related to DISPLAY or xheadless/xvfb configuration. Accepts the following values:

  • <empty> Displays the application has been closed and offers a new session option.

  • / Displays a list of available WebUI applications and offers a logout option.

  • /goodbye Goes to the Jetty home page. If this home page is the default BASIS provided page it will show the Apps section.
Secure TC Connection

Enables to set the application's Thin Client TC communication to use the system's pre-configured global setting (<default>), explicitly disable it false, or explicitly enable a secure encrypted connection true. See: BBjAppServer::setSecure.

Value Description
<default> Uses the default configuration when no explicit setting is defined
false Disables a secure Thin Client Connection for the application.
true Enables a secure encrypted Thin Client Connection for the application.
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.

  • vpro5 - emulates the Visual PRO/5 look and feel on all platforms, regardless of operating system.
TCPS Preload

  • When unchecked, delays initialization of TCPS drivers and SSL certificates until a secure WebUI session begins, which may increase initial connection latency.

  • When checked, preloads BBjServices TCPS resources and certificates during system startup to optimize secure connection readiness and responsiveness. It is used in UNIX and Linux WebUI deployments when the DISPLAY environment variable is not set.
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.
Debug

  • When unchecked, debugging is disabled; the application runs without additional diagnostic output.

  • When checked, enables debugging mode, providing extended logging for development and issue resolution.

Other settings

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

Other Settings Table

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.
BBJ_PRELOAD_JAR_DIR

Defines a preload JAR directory for the internal classpath. The Desktop App classloader looks for JARs in this directory and preferentially uses any classes that are already on the client before dynamically downloading them from the server to cache separately.

When using an SSCP, the classloader looks in this directory for a subdirectory with the same name as the SSCP, and uses that directory as the preload JAR directory.

The default location for this directory is remotelauncher.<user>/jars.
BBJ_REMOTE_CLASSLOADER_LOGGING=cache Setting this environment variable will enable logging for when classes are loaded, and whether they come from "PRELOAD JAR" or "CACHE".

See Also

BBjAdminBase

Desktop App JREs

Global Settings

Demos