Running BBj Thin Client with Java Web Start

As of Java 11+, Java Web Start is no longer supported, and JNLP Applications are superseded by Desktop Apps in BBj 19.20 and later.

Configure Web Start Overview

To configure Web Start, follow the steps listed below:

1. Prepare the Web server to deliver Web Start files in the appropriate form.

2. Prepare the Web Start files.

BBj supports JAR indexing with BBj 7.0 and Java 1.6 or greater. Additionally, JAR requirements can change with each revision of BBj. For more information, see BBj Classpath Overviews.

For BBj Revs 9.x - 11.x and above, see Enterprise Manager - JNLP Configuration.

For BBj Rev 12.x and above, see Enterprise Manager - JNLP: Applications.

I. Prepare the Web Server

Add a new MIME type

A MIME type tells the server what kind of file is associated with a particular extension. For example, the type image/gif is associated with gif graphics. The Java Web Start MIME type is an application/x-java-jnlp file. The jnlp extension is associated with a Java Network Launch Protocol type.

The process of setting up a new MIME type varies, depending on the type of Web server. Follow the instructions below to configure each type of server.

Server Type	Instructions
Apache	1. Edit the /etc/mime.types by adding the line: application/x-java-jnlp-file jnlp 2. After adding this line, restart the server.
Windows 2000 Internet Information Services (IIS)	Start the IIS Management Console and perform the following steps: 1. Right-click server computer in left pane, then select Properties from the drop-down menu. 2. In the 'Computer MIME Map,' click the [Edit] button. 3. The File Types window is displayed. Click New Type. 4. In the File Type box, enter the following in the Associated Extension edit box: jnlp 5. In the Content Type (MIME) box, enter: Application/x-java-jnlp-file jnlp 6. Click [Ok] to close the File Type box. Click [Ok] again to close the File Types Window. Click [Ok] in the Server properties window to save the changes. Restart the IIS Admin Service.
Windows XP/2003 Internet Information Services (IIS)	Start the IIS Management Console and perform the following steps: 1. Right-click server computer in left pane, then select Properties from the drop-down menu. 2. In the HTTP Headers tab, click [MIME Types]. 3. The MIME Types window displays. Click [New]. 4. In the MIME Type box, enter the following in the Extension edit box: jnlp 5. In the MIME type box, enter: Application/x-java-jnlp-file jnlp 6. Click [OK] to close the MIME Type box. Click [OK] again to close the MIME Types Window. Click [OK] in the Server properties window to save the changes. Restart the IIS Admin Service.
Windows Vista/Windows 7/Windows 2008 Internet Information Services (IIS)	Start the IIS Management Console and perform the following steps: 1. Double-click the MIME Types module. 2. The MIME Types window displays. Click [Add] in the Action panel. 3. The Add MIME Type window displays. Enter the following in the File Name Extension box: jnlp 4. In the MIME Type box, enter: Application/x-java-jnlp-file jnlp 5. Click [OK] to close the MIME Type window. Restart the IIS Admin Service.

II. Prepare the Web Start Files

As noted above, the jar file information changes with each revision of BBj. See BBj Classpath Overview.

A. Create the jnlp file

The jnlp file, written in XML, specifies how Web Start will run the application. The simplest way to create this file is to modify an existing file. The following example is from a file named ec.jnlp, the file BASIS uses for its b-commerce application.

<?xml version="1.0" encoding="utf-8"?>

<jnlp spec="1.0+" codebase="https://poweredbybbj.com/jnlp/" href="ec.jnlp">
<information>
<title>BASIS b-commerce Application</title>
<vendor>BASIS International Ltd.</vendor>
<description>BASIS b-commerce Application</description>
<description kind="short">A b-commerce connection to BASIS.</description>
</information>
<security>
<all-permissions/>
</security>
<resources>
<j2se version="1.6+" initial-heap-size="24m" max-heap-size="24m"/>
<jar href="BBjThinClient.jar"/>
<jar href="BBjUtil.jar"/>
</resources>
     <resources os="Windows">
           <nativelib href="webstart2166.jar"/>
     </resources
     <resources os="Mac">
           <nativelib href="webstart2120.jar"/>
    </resources>

<application-desc main-class="com.basis.bbj.client.comm.WebStartLauncher">
<argument>-q</argument>
<argument>-SC</argument>
<argument>-unobody</argument>
<argument>-c/usr/local/ec/config.bbx</argument>
<argument>-RHpoweredbybbj.com</argument>
<argument>/usr/local/ec/ec.bbj</argument>
</application-desc>
</jnlp>

Here is an explanation of the code from the example above:

<?xml version="1.0" encoding="utf-8"?>

This is an xml specification line, which is required by xml parsers because the parser needs to know to what specification the file is conforming.

Comments begin with . Comments may not nest (this is illegal:  -->). Comments may span multiple lines. There is no limit to the number comments and they may be included in any location within the jnlp file.

This is the root tag in every jnlp file. The attributes of this tag specify which version of the Web Start protocol being used (1.0+), as well as information about where the file is located. The codebase attribute specifies what protocol to use, (http) what machine the file is hosted on, (poweredbybbj.com) and what directory the file resides in (jnlp). The href attribute specifies the actual file name.

In BBj 8.0 and higher, a developer can alternatively use file:// instead of http:// when not using a Web Server to specify the codebase.

<information>
<title>Basis B-commerce Application</title>
<vendor>Basis International Ltd.</vendor>
<description>Basis B-commerce Application</description>
<description kind="short">An B-commerce connection to basis.</description>
</information>

This section is general information that will be presented to the user during installation. The <title> element will become the name of the icon on the users desktop. The vendor and description will be available to the user through the Web Start launcher.

This section requests complete access to the users machine. The user is prompted to request access. If the user does not grant access, the application will not run. In the 1.0+ specification, there is no middle ground. In other words, a request for only network access or only disk access cannot be made.

The code above describes the required version of Java, the initial and maximum memory sizes, and the required jars necessary to run the application. See the BBj Classpath Overview document for your revision of BBj to see which jars are required.

Note: Beginning with 1.6.0_18, Java includes a ‘zero setting’ option which dynamically allocates memory to the Web Start application, based on the hardware profile of the client and the memory needs of the application. BASIS highly recommends taking advantage of this setting. Simply modify the Java version element as follows:

This includes all Platform specific code for Windows platforms. Java Web Start is available on other operating systems. For Linux, the webstart2145.jar is provided. For Solaris, x86 webstart2169.jar is provided. For Solaris SPARC, use webstart2179.jar.

Specifies the Main Java class to run as well as the arguments. For thin client, the main class will always be com.basis.bbj.comm.WebStartLauncher. The arguments will vary depending on the application.

In this example:

q	Specifies no splash screen
SC	Specifies Secure Connection
unobody	Tells the BBj Server to connect as user nobody
c/usr/local/ec/config.bbx	Specifies which configuration file to use and where it resides on the server
RHpoweredbybbj.com	Specifies which remote host to connect with when starting
/usr/local/ec/ec.bbj	Specifies what BBj application to run
-	Specifies the BBj application has arguments that follow
arg1	This is the first argument for the BBj application
arg2	This is the second argument for the BBj application

</jnlp>

End of the file. </jnlp> closes out the opening <jnlp> from section 3.

Replace the parameters within ec.bbj to suit the needs of an application. Ensure that the filename changed from section 3 to match the new jnlp file name.

B. Prepare the jar files

To prepare the jars, they must be signed for Web Start in order to get access to all-permissions in the security section of the jnlp file.

All of the tools needed to sign jars are provided with the Java developers' kit. The two tools BASIS requires are the keytool and the jarsigner. First, create a keystore. A keystore is a file that contains all of the information contained within the jars signed. To create a new keystore, use the following command:

keytool -genkey -keystore LocalKeyStore -alias testing

This command creates a new keystore named LocalKeyStore in the current directory. There may be many types of keys in your keystore. The -alias testing specifies creating a new type called testing. A prompt will appear requesting a keystore passphrase. Select one and remember it because this password will be needed to sign jars. There will also be a prompt for name and organization. The user will be presented with this information when asked to grant full access to their computer.

For each jar to be signed into this keystore, run the following command:

jarsigner -keystore LocalKeyStore BBjThinClient.jar testing

The -keystore specifies which keystore to use, the full path can be provided if it is not in the local directory. BBjThinClient.jar is the first JAR to be signed. It is important to note that each jar may only be signed once. Keep the originals safe and only sign copies. The testing argument signs the jar into the testing alias created earlier.

Testing is now ready to be run. If prompted with the security request, the security manager will strongly recommend not to continue. The reason for this recommendation is that the jarsigner was not validated by a trusted server.

Any provider can be used to validate JARs (BASIS uses Verisign). The process of signing JARs when backed by Verisign is slightly different. For further information, see https://www.verisign.com.

Note: Obtaining a secure certificate from Verisign takes about 8-14 days.

Remark 1

Web Start tries to share resources with any BBjServices jvm running on the client machine. In some cases, the Web Start's ThinClient.jar is incompatible with BBjService's ThinClient.jar. To avoid this problem, use the additional argument –INF(marker). Web Start only shares resources with other virtual machines containing the same marker.

In #8 of the example above, add the following argument:

<argument>-INFbcommerce</argument>

Remark 2

Some Java implementations use port 113 (associated with the ident service) for authentication purposes. If port 113 is blocked, Java Web Start may take several minutes to launch, or fail completely.

Additional information

For the Java Web Start Developers Guide, visit java.sun.com.

For further information about MIME types and content negotiation, visit httpd.apache.org.

Web Server (Jetty) Overview