#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" : "${webswing.admin.url}"
  },
  "/webswing-demo" : {
    "path" : "/webswing-demo",
    "enabled" : true,
    "name" : "Webswing Demo",
    "webFolder" : "${webswing.rootDir}/apps/WebswingDemo/webroot",
    "restrictedResources" : [ ],
    "langFolder" : "",
    "security" : {
      "module" : "INHERITED",
      "config" : { },
      "authorizationConfig" : {
        "users" : [ ],
        "roles" : [ ]
      }
    },
    "webHomeDir" : "${webswing.rootDir}/apps/WebswingDemo",
    "icon" : "icon.png",
    "uploadMaxSize" : 5,
    "maxClients" : 100,
    "sessionMode" : "CONTINUE_FOR_BROWSER",
    "monitorEdtEnabled" : true,
    "recordingConsentRequired" : false,
    "mirroringConsentRequired" : false,
    "loadingAnimationDelay" : 2,
    "allowStealSession" : true,
    "autoLogout" : false,
    "goodbyeUrl" : "/",
    "dataStore" : {
      "module" : "INHERITED",
      "config" : { }
    },
    "fileViewers" : [ {
      "url" : "txt-viewer/?file=${file}",
      "operation" : "open",
      "fileType" : "txt"
    }, {
      "url" : "csv-viewer/?file=${file}&operation=open",
      "operation" : "open",
      "fileType" : "csv"
    }, {
      "url" : "csv-viewer/?file=${file}&operation=edit",
      "operation" : "edit",
      "fileType" : "csv"
    }, {
      "url" : "csv-viewer/?file=${file}&operation=print",
      "operation" : "print",
      "fileType" : "csv"
    } ],
    "swingConfig" : {
      "allowUpload" : true,
      "allowDownload" : true,
      "isolatedFs" : true,
      "sessionLogging" : false,
      "allowJsLink" : true,
      "javaFx" : true,
      "javaFxClassPathEntries" : [ "${webswing.rootDir}/apps/javafx/*.jar" ],
      "homeDir" : "${webswing.rootDir}/apps/WebswingDemo",
      "theme" : "Murrine",
      "directdraw" : true,
      "debug" : true,
      "jreExecutable" : "${java.home}/bin/java",
      "javaVersion" : "${java.version}",
      "vmArgs" : "",
      "launcherType" : "Desktop",
      "launcherConfig" : {
        "mainClass" : "org.webswing.demo.WebswingDemoApp"
      },
      "swingSessionTimeout" : 300,
      "timeoutIfInactive" : false,
      "allowDelete" : true,
      "allowAutoDownload" : true,
      "allowLocalClipboard" : true,
      "allowServerPrinting" : false,
      "dockMode" : "ALL",
      "allowStatisticsLogging" : true,
      "testMode" : false,
      "jsLinkWhitelist" : [ "*" ],
      "transferDir" : "${user}/upload",
      "clearTransferDir" : true,
      "sessionLogFileSize" : "${webswing.sessionLog.size:-10MB}",
      "transparentFileSave" : true,
      "sessionLogMaxFileSize" : "${webswing.sessionLog.maxSize:-1000MB}",
      "transparentFileOpen" : true,
      "fontConfig" : { },
      "classPathEntries" : [ "WebswingDemo.jar", "lib/*.jar" ],
      "multiScreenSupportEnabled" : true
    }
  }
}

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

#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

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 javaFxClassPathEntries in app configuration. Webswing supports JavaFX versions 8, 11, 17 and 21. You can also use a JDK that has JavaFX libraries included. In such case set the configuration option javaFxEmbeddedInJdk to true, then you don't have to provide javaFxClassPathEntries or javaFxVersion.