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

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.

#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:

In Admin Console, options which support variable replacement show with a flash icon. Click on the flash icon shows the resolved value:

#Settings overview

#General

#Security

#Java

#Session

#Logging

#Features

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 a Windows system and different on a 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 for files that are transferred between the browser and application instance.

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 jreExecutableoption 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 libraries are not distributed with JDK. If you want to run your JavaFX application with Webswing, download the required JavaFX libraries here: https://mvnrepository.com/artifact/org.openjfx and add them to the Webswing JavaFX specific configuration:

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