logo
22.1
search
No matching documents found.
list
search
No matching documents found.
logo
Please be aware that there is newer version of documentation available for Webswing. Documentation 24.2

Swing/JavaFX

Application Setup

Swing and JavaFX applications are configured in json format and by default are saved in file webswing.config, which is by default placed in the same folder as the webswing-server.war file. This location may be changed using the -c command-line option. It is recommended to use the Administration console form based configuration screen to modify this file to avoid JSON formatting problems.

Configuration using Admin Console

The easiest way of configuring your application is using the Admin console. To access the Admin console click Manage from Webswing homepage or go to the admin console URL that you have configured in your webswing.config file under root ("/") path. Navigate to the Configuration view where you can see the list of configured applications. You can add new or edit existing applications here.

Configuration

You can edit or view the settings. These are split in logical sections. Each setting has a description, which is displayed when hovered on the question mark.

Description

JSON format description

Here is a sample webswing.config file content with demo swing application configured:

{
  "/" : {
    "path" : "/",
    "security" : {
      "module" : "EMBEDED",
      "config" : {
        "users" : [ {
          "username" : "admin",
          "password" : "pwd",
          "roles" : [ "admin" ]
        }, {
          "username" : "support",
          "password" : "pwd",
          "roles" : [ "support" ]
        }, {
          "username" : "user",
          "password" : "pwd"
        } ]
      },
      "classPath" : [ ]
    },
    "langFolder" : "${webswing.configDir}/lang",
    "homeDir" : "${user.dir}",
    "allowedCorsOrigins" : [ "*" ],
    "adminConsoleUrl" : "http://localhost:8090"
  },
  "/swingset3" : {
    "path" : "/swingset3",
    "webFolder" : "${webswing.rootDir}/apps/SwingSet3/webroot",
    "security" : {
      "module" : "INHERITED",
      "config" : null,
      "classPath" : [ ]
    },
    "icon" : "${webswing.rootDir}/apps/SwingSet3/icon.png",
    "homeDir" : "${webswing.rootDir}/apps/SwingSet3",
    "langFolder" : "${webswing.configDir}/lang",
    "swingConfig" : {
      "name" : "SwingSet3",
      "jreExecutable" : "${java.home}/bin/java",
      "javaVersion" : "${java.version}",
      "vmArgs" : "-Xmx128m -DauthorizedUser=${user}",
      "classPathEntries" : [ "${webswing.rootDir}/apps/SwingSet3/SwingSet3.jar", "${webswing.rootDir}/apps/SwingSet3/*.jar" ],
      "theme" : "Murrine",
      "fontConfig" : {
        "dialog" : "${webswing.configDir}/fonts/Roboto-Regular.ttf",
        "dialoginput" : "${webswing.configDir}/fonts/RobotoMono-Regular.ttf",
        "serif" : "${webswing.configDir}/fonts/RobotoSlab-Regular.ttf"
      },
      "maxClients" : 100,
      "sessionMode" : "CONTINUE_FOR_BROWSER",
      "swingSessionTimeout" : 300,
      "allowStealSession" : true,
      "isolatedFs" : true,
      "debug" : true,
      "javaFx" : true,
      "javaFxClassPathEntries" : [ "${webswing.rootDir}/apps/javafx/*.jar" ],
      "directdraw" : true,
      "compositingWinManager" : true,
      "allowDelete" : true,
      "allowDownload" : true,
      "allowAutoDownload" : true,
      "allowUpload" : true,
      "uploadMaxSize" : 5,
      "allowJsLink" : true,
      "jsLinkWhitelist" : [ "org.webswing.demo.jslink.JsLinkDemo.*" ],
      "launcherType" : "Desktop",
      "launcherConfig" : {
        "mainClass" : "com.sun.swingset3.SwingSet3",
        "args" : null
      },
      "userDir" : "${user}",
      "transparentFileSave" : true,
      "clearTransferDir" : true,
      "transparentFileOpen" : true,
      "autoLogout" : true,
      "transferDir" : "${user}/upload"
    }
  }
}

Configuration File Organization

The JSON configuration file is organized by the unique URL endpoints. Each URL endpoint has therefore its own configuration. This can be seen in the Webswing binary distribution webswing.config file:

{
  "/" : {
    "path" : "/",
    "security" : ...
    },
    ...
  },
  "/swingset3" : {
    "path" : "/swingset3",
    "name" : "SwingSet3",
    "security" : {...},
    ...
    "swingConfig" : {
      ...
      "launcherType" : "Desktop",
      "launcherConfig" : {
        "mainClass" : "com.sun.swingset3.SwingSet3",
        "args" : null
      },
    },
  },
  "/netbeans" : {
    "path" : "/netbeans",
    ...
  },
  "/applet" : {
    "path" : "/applet",
    ...
  },
  "/javafx" : {
    "path" : "/javafx",
    ...
}

Variable resolution

Most of the text options support variable replacement. Available variables are Java system properties, OS environment variables, and a set of special Webswing variables. Variables are specified with dollar followed by variable name in curly brackets. For example, ${variable_name}.

In additions to variables, for classPathEntries properties it is possible to use wild-card characters. Supported wild-cards are * (everything) and ? (any singe character).

Available variables:

Variable Name Description
${user} Webswing specific logged in user name.
${clientId} Webswing specific unique browser identifier.
${clientIp} IP address of browser that started this application.
${clientLocale} Locale of browser that started this application.
${clientTimeZone} Time zone of browser that started this application.
${customArgs} Custom Arguments specified in URL parameters. See details
Java system Properties All properties accessible to server's JVM using System.getProperty method
System environment variables All OS level environment variables accessible to script that started Webswing server JVM.

In Admin Console options with variable replacement support appears with a flash icon. When focused a panel with resolved value of is displayed:

Variable Resolution

Settings overview

General

Setting Description
Name Application name
Theme Select one of the default window decoration themes or a enter path to a XFWM4 theme folder
Fonts Customize logical font mappings and define physical fonts available to the application. These fonts (TTF only) will be used for DirectDraw as native fonts. Key: name of font (ie. dialog)
DirectDraw Rendering DirectDraw rendering mode uses canvas instructions to render the application instead of server-rendered png images. DirectDraw improves performance but is not recommended for applications with lot of graphics content
JavaFX Support Enables native or embedded JavaFX framework support.
Enable Debug Mode Enables remote debug for this application. To start the application in debug mode, use '?debugPort=8000' url param
Web Folder Folder to be used to store customized static web files like HTML, CSS or Javascript.
Restricted Resources Defined Path-prefix restricts access to resources only to authenticated users. Applies to static resources inside 'Web Folder' or packaged with Webswing.
Localization Folder Folder to be used to store customized messages and translations in supported languages. English is available by default.
CORS Origins If you are embedding Webswing to page on different domain, you have to enable Cross-origin resource sharing (CORS) by adding the domain in this list. Use * to allow all domains.

Security

Setting Description
Security Module Class Path Additional classpath for built-in Security module or for defining custom security module.
Security Module Name Select one of built-in modules or enter full class name of custom security module (has to implement org.webswing.server.services.security.api.WebswingSecurityModule interface). Note the class and its dependencies has to be on classpath defined above.
Security Module Config Specific configuration for the selected security module. By default EMBEDDED security module has list of Users and corresponding Roles specified here.

Java

Setting Description
Working Directory The User working directory. Path from which the application process will be started. (See the Java System Property: 'user.dir')
JRE Executable Path to Java executable that will be used to spawn application process. Java 7 and 8 is supported.
Java Version Java version of the JRE executable defined above. Expected values are starting with '1.7' or '1.8'.
Class Path Application's class path. Absolute or relative path to jar file or classes directory. At least one class path entry should be specified containing the main class. Supports ? and * wildcards
JVM Arguments Command-line arguments processed by Oracle's Java Virtual Machine (i.e. '-Xmx128m').
Launcher Type Select the application type. Applet or regular Desktop Application
Launcher Configuration Launcher type specific configuration options

Session

Setting Description
Max. Connections Maximum number of allowed simultaneous connections for this application.
Session Mode Select session behaviour when user reconnects to application.
  1. ALWAYS_NEW_SESSION: New application is started for every Webswing session. (Session timeout will be set to 0.)
  2. CONTINUE_FOR_TAB: Webswing session can be resumed in the same browser TAB after connection is terminated. (Session timeout applies)
  3. CONTINUE_FOR_BROWSER: Webswing session can be resumed in the same browser after connection is terminated. (Session timeout applies)
  4. CONTINUE_FOR_USER: Application session can be resumed by the same user from any computer after the connection is terminated. (Session timeout applies)
Session Timeout Specifies how long (seconds) left the application will be running after the user closes the browser. User can reconnect in this interval and continue in last session
Timeout if Inactive If True, the Session Timeout will apply for user inactivity (Session Timeout has to be > 0). Otherwise, only disconnected sessions will time out.
Session Stealing If enabled, and session mode 'CONTINUE_FOR_USER' is selected, user can resume Webswing session, even if the connection is open in another browser. The former browser window will be disconnected.
Auto Logout If enabled, user is automatically logged out after the application finished.
Goodbye URL Absolute or relative URL to redirect to, when application exits. Use '/' to navigate back to Application selector.

Logging

Setting Description
Session Logging If enabled, sessions are logged into a separate log file.
Maximum Session Logs Size Maximum size of all session log files. After file size is exceeded, old log files are deleted.
Session Log Size Maximum size of a single session log file.
Statistics Logging If enabled, statistics will be logged for sessions.

Features

Setting Description
Isolated Filesystem If true, every file chooser dialog will be restricted to access only the home directory of current application
Uploading Files If selected, the JFileChooser integration will allow users to upload files to folder opened in the file chooser dialog
Deleting Files If selected, the JFileChooser integration will allow users to delete files displayed in the file chooser dialog
Downloading Files If selected, the JFileChooser integration will allow users to download files displayed in the file chooser dialog
Auto-Download from Save Dialog If selected, the JFileChooser dialog's save mode will trigger file download as soon as the selected file is available on filesystem
Transparent Open File Dialog If selected, the JFileChooser dialog's open mode will open a client side file browser and transparently upload selected files and triggers selection
Transparent Save File Dialog If selected, the JFileChooser dialog's save mode will open a client side dialog to enter the file name to be saved
Upload Folder If Isolated Filesystem is enabled. This will be the folder on the server where the user can upload and download files from. Multiple folders can be defined using path separator (${path.separator})
Clear Upload Folder If enabled, all files in the transfer folder will be deleted when the application process is terminated
Upload Size Limit Maximum size of upload for single file (in MB). Set 0 for unlimited size
Domains Allowed to Embed If you are embedding Webswing to page on different domain, you have to enable Cross-origin resource sharing (CORS) by adding the domain in this list. Use * to allow all domains
Allow JsLink If enabled, the JSLink feature will be enabled, allowing application to invoke JavaScript and vice versa. (See netscape.javascript.JSObject)
Allow Local Clipboard Enables built-in integration of client's local clipboard. Due to browser security limitations, clipboard toolbar is displayed.
Docking Mode Select the mode for undocking windows to a separate browser window: 1.ALL: all windows can be undocked. 2.MARKED: only windows marked with Dockable interface can be undocked. 3.NONE: disable undocking

Go to application configuration in Admin Console to see the complete list of configuration options with descriptions.

Fonts configuration

Selection of fonts available to any Swing application is dependent on the platform it is running on. A different set of fonts is available on the Windows system and different on Linux system. To ensure the user experience is consistent, Webswing provides an option to configure which fonts will be available for each Swing application.

Font are configured in webswing.config file as described above. This is how the configuration looks:

  "fontConfig" : {
      "dialog" : "${user.dir}/fonts/Roboto-Regular.ttf",
      "dialoginput" : "${user.dir}/fonts/RobotoMono-Regular.ttf",
      "serif" : "${user.dir}/fonts/RobotoSlab-Regular.ttf"
    },

If you omit this setting or no fonts are defined, Webswing will use the default platform specific settings.

If this setting is present, only fonts defined in this property file will be available to your Swing application.

Font settings are important when DirectDraw rendering is enabled. DirectDraw will transfer configured fonts to browser (when used for the first time) and use them as native fonts.

Using too many or too large fonts may result in rendering delays.

If fonts are not configured, Webswing will use default browser fonts for rendering logical font families ( dialog, dialoginput, sansserif, serif, monospaced) and less efficient Glyph rendering for other fonts.

Provide fonts in CSS

To optimize loading fonts from server you can preload fonts using CSS. This option is available only when using DirectDraw rendering. To enable font preloading add startup parameter -Ddirectdraw.fontsProvided=true to vmArgs property in your application configuration. Next you have to add a custom.css file to your custom index.html (see Customization) which will contain the CSS styles for the fonts:

@font-face {
  font-family: "arial-unicode-ms.ttf";
  src: url("fonts/arial-unicode-ms.ttf");
}

@font-face {
  font-family: "arial.ttf";
  src: url("fonts/arial.ttf");
}

Make sure the font files are in your application webFolder and accessible. Finally add this div to your custom index.html to force browser to download the font files:

<div id="webswing-font-preload" style="position: fixed; color: transparent;">
    <span style="font-family: 'arial-unicode-ms.ttf';">a</span>
    <span style="font-family: 'arial.ttf';">a</span>
</div>

Data store

Data store is a configuration of storage of multiple types of data that Webswing is working with:

  • recordings
  • thread dumps
  • upload and download

You can configure different data store per application or configure a single data store for root ("/") and inherit the configuration by applications. By default, there is a File Store data store configuration used. This data store stores the data to file system to ${webswing.rootDir}/datastore folder.

If you need a different type of data store, please contact support@webswing.org.

Custom startup script

Sometimes, it is necessary to prepare the environment before the application process is started. This may include steps like changing the current working directory or using sudo to run application as a different user. This can be achieved by pointing the jreExecutable option to custom startup script.

Custom startup script must follow a few rules in order to work with Webswing:

  1. The last step of the script should execute Java with the arguments as passed in by Webswing. (ie. $JAVA_HOME/bin/java $@ )
  2. If the script has arguments of its own, they should be shifted before calling Java (shift 3 if your script uses 3 arguments)
  3. Be aware that variable resolution in webswing.config is done in the server's context (the environment changes will not be reflected to variables defined in webswing.config).

Here is an example of the custom script that will use sudo to run the application process as the logged in user. We assume that users defined in users.properties have OS level counterparts and the user used to start the server is properly configured in sudoers (needs NOPASSWD flag in sudoers - see man page).

Here is our application configuration:

{
    "name" : "SwingSet3",
    "jreExecutable": "startSwingSet3.sh ${user}",
    "javaVersion": "1.8",
    "mainClass" : "com.sun.swingset3.SwingSet3",
    "classPathEntries" : [ "SwingSet3.jar", "lib/*.jar" ],
    "vmArgs" : "-Xmx128m",
    "args" : "",
    "homeDir" : "demo/SwingSet3"
}

When Webswing starts an application with the above configuration, the command-line will look like this:

startSwingSet3.sh johnDoe -Xmx128m <webswing specific configuration> -cp webswing-server.war main.Main

Now the custom script demo/SwingSet3/startSwingSet3.sh that runs the Java process as the logged in user will look like this:

#!/bin/sh
#save user to temporary variable
USER=$1
#shift the arguments by one - the user
shift
#handle system events
trap : SIGTERM SIGINT
#run java with sudo 
sudo -u $USER /home/work/jdk/jdk/bin/java $@ &
#wait for java to exit or kill if signaled 
JAVA_PID=$!
wait $JAVA_PID
if [[ $? -gt 128 ]]
then
    kill $JAVA_PID
fi

JavaFX

JavaFX is not distributed with JDK. We have removed the JavaFX demo examples because the libraries are too big. You can download the required JavaFX libraries here: https://mvnrepository.com/artifact/org.openjfx. Add them to the Webswing JavaFX specific configuration:

"javaFx" : true,
"javaFxClassPathEntries" : [ "${webswing.rootDir}/apps/javafx/*.jar" ],