Dynamic Parameterisation (for Applet and JWS/JNLP replacement and Download-specific apps)
Important: the parameterisation API is available in JWrapper 00022615967 and later
Please Note: this guide assumes you have looked through:
A key feature of Java Applets and Java Web Start is that despite the code being signed, arguments can be provided along with the app that configure its behaviour. These can set important details about the app and allow it to be customised per user.
While desktop apps are able to accept arguments they have in the past been unsuitable for this type of download-specific or customer-specific parameterisation because the arguments passed in cannot be specified as part of the app itself. While the app is able to accept command line parameters the server cannot specify what these are.
The usual workaround for this is for apps to try and encode settings into the name of the app but this is cumbersome, prone to errors (when browsers or the user change the name of the downloaded app), keeps parameters in plain view and limits the amount of information that can be sent without an extremely long app name.
Unlike other multi platform installers JWrapper tackles this problem directly and gives you tools which, despite your executables being signed and verifiable, allow you to specify arbitrary key/value pairs of parameters which you can edit without resigning. This method keeps your app code signed and verified but allows you to specify inputs to the app which can be set at download time (or any other time) from within some simple Java code.
In the case of SimpleHelp's remote support software for example, when the app is downloaded the app name has no additional info on it and the customer does not need to enter in any codes to get connected. The app has already been parameterised server side specifically for that customer.
Please Note: this guide assumes you have looked through:
A key feature of Java Applets and Java Web Start is that despite the code being signed, arguments can be provided along with the app that configure its behaviour. These can set important details about the app and allow it to be customised per user.
While desktop apps are able to accept arguments they have in the past been unsuitable for this type of download-specific or customer-specific parameterisation because the arguments passed in cannot be specified as part of the app itself. While the app is able to accept command line parameters the server cannot specify what these are.
The usual workaround for this is for apps to try and encode settings into the name of the app but this is cumbersome, prone to errors (when browsers or the user change the name of the downloaded app), keeps parameters in plain view and limits the amount of information that can be sent without an extremely long app name.
Unlike other multi platform installers JWrapper tackles this problem directly and gives you tools which, despite your executables being signed and verifiable, allow you to specify arbitrary key/value pairs of parameters which you can edit without resigning. This method keeps your app code signed and verified but allows you to specify inputs to the app which can be set at download time (or any other time) from within some simple Java code.
In the case of SimpleHelp's remote support software for example, when the app is downloaded the app name has no additional info on it and the customer does not need to enter in any codes to get connected. The app has already been parameterised server side specifically for that customer.
How to parameterise your build files
Parameterisation is done via the JWParameteriser API (link below). The JWParameteriser class can be run as a main class to perform parameterisation from the command line or its methods can be used from within Java code.
Generally you should first read the parameters for a file in case JWrapper has set any launch properties already, then you can modify them and set them again on the file.
For processing downloads inside a Java Servlet or similar we would recommend initially reading and storing the Properties for the file, then copying and modifying for that specific download and setting them as the file is transferred to the HTTP stream using the JWStreamParameteriser.
How to fetch Launch Properties
Example: Using a Servlet to parameterise a downloaded App
This example shows how to parameterise a built JWrapper install/launch file upon download. The code could be used in a Java Servlet to parameterise the file as it is downloaded in order to customise it for that particular user or session.
The first step would be to read in the default Properties for the file and cache them:
The first step would be to read in the default Properties for the file and cache them:
(Servlet code...)
static Properties orig;
static {
//Read in the properties from the file JWrapper produced
orig = new JWParameteriser().getParameters(new File("MyApp-windows32.exe");
}
Next when a download occurs we would read in the file and transfer it to the OutputStream, but pass in each block to a JWStreamParameteriser so that the parameters are rewritten.
(Servlet code...)
//Clone the original properties so we retain any properties JWrapper has set
Properties custom = (Properties)orig.clone();
//Set our custom property
custom.setProperty("Download Time",""+System.currentTimeMillis());
//Create a new JWStreamParameteriser based on our custom Properties
JWStreamParameteriser sp = new JWParameteriser().newStreamParameteriser(custom);
//Transfer the data to the OutputStream and parameterise it as we go
InputStream in = new BufferedInputStream(new FileInputStream("MyApp-windows.exe"));
byte[] buf = new byte[20000];
int n = 0;
while (n != -1) {
n = in.read(buf);
if (n > 0) {
//JWStreamParameteriser will replace bytes as necessary
sp.nextBlockToBeTransferred(buf,0,n);
out.write(buf,0,n);
}
}
Once the download has occurred, the app can then use JWSystem to pick out the launch property:
(App code...)
//Retrieve the property set in the Servlet
String downloadTime = JWSystem.getAppLaunchProperty("Download Time");
Standard Launch Properties and Naming Recommendations
You should prefix your launch properties with some company or app specific string to ensure they do not interfere with any set by JWrapper.
The following launch properties are properties you can set which JWrapper will utilise:
The following launch properties are properties you can set which JWrapper will utilise:
- update_url - sets the JWrapper update URL (note that the update URL must be specified in the JWrapper XML build file as Dynamic)
- supported_langs - sets the language codes supported by your app run (can be set to a single language code to force a particular language)
Dynamic Update URL
If you plan on altering your update URL dynamically you must tell JWrapper that your app will accept a dynamic update URL.
You can do this by altering your jwrapper XML file by:
You can do this by altering your jwrapper XML file by:
- Removing the <UpdateURL>...</UpdateURL> tag entirely
- Adding a new tag <DynamicUpdateURL>true</DynamicUpdateURL> under the root document element