5.12.2.4.3 Developer Tips - Web Start Client

This section provides developer tips related to the Java Web Start client.

General Tips

When I tried connecting with the host name "localhost", it throws AccessControlException in the Web Start Log console, Why?

This might be due to the DNS resolution problem. Java Web Start imposes Security restrictions (security sandbox) upon the applications launched through it. By this security restriction, the client application, namely the Web NMS Java client, can only connect to the exact server machine from which it was downloaded.

In this scenario, if you have connected and downloaded the Web NMS Client from the server running in a machine named say john, to the same machine (john) itself then, when you try to connect the client to the server specifying localhost (where logically localhost is equal to john) Web Start might throw a AccessControlException. This is due to the DNS resolution problem of mapping 'localhost' to 'john'. The Web Start plug-in will assume 'localhost' to be a different machine than 'john' hence, due to the security restriction to access resources on machines apart from where it was downloaded, it will throw a AccessControlException.

To circumvent this problem, it is always recommended to connect to Web NMS Server (from where the client jars were downloaded) specifying the exact host name

How to enable the Web Start console?

You could activate the Web Start Log console, from the Web Start Application Manager. This could be done by selecting the "Show Java Console" option under the "Advanced" tab present in the "Preferences Dialog", which can be invoked from the "File" Menu.

Web Start Log console has options to even store logs into a file for future references.

Where are the jar files of the downloaded client application stored in the local machine?

The downloaded jar files of the Client application will be stored under the sub-directory javaws/cache, present under the directory where the Java Web Start plug-in is installed.

How to customize the Java Client application icon, title, description, homepage etc., displayed in the Web Start Application Manager?

The information displayed about the Web NMS Java Client in the Web Start Application Manager is specified in the file WebNms.jnlppresent under <Web NMS Home>/conf directory. These information is specified within the <information>..</information>tags. You can modify the corresponding entries specified within this tag to customize the information provided.

Please refer to Customizing the JNLP file for additional information on JNLP customization.

How to programatically invoke a URL in the browser, in the Web Start mode from my application?

You can use the method public boolean showDocument(java.net.URL url), present in the API interface javax.jnlp.BasicService. This method will open the specified URL in the default browser setup in your system.

How to open and save a file in the Web Start Client?

You can use the JNLP service APIs javax.jnlp.FileOpenService and javax.jnlp.FileSaveService for opening and saving a file respectively. You can read about using them by following this link.

What is the workaround to be done for launching Web Start Client in Netscape 6.2, Mozilla, Konqueror and Opera browsers?

Previously, the script (generated by the Login.jsp file present under <Web NMS Home>/jsp directory) to identify whether Java Web Start is installed or not was not working properly in Netscape 6.2 , Mozilla, Konqueror, and Opera browsers. Hence by default, it used to wrongly identify that Java Web Start in not installed in your machine thereby throwing out an error notification page saying "Java Web Start is not installed in this machine".

Now, a workaround is provided which involves changing the following .jsp files (specified with the directory of their location) as per your requirement. The contents of the files must be edited in such a manner such that the framework overlooks installation of the Java Web Start client in the machine. It must be ensured that the changes in the file is done before invoking the WebNMS.jnlp file located in <Web NMS HOME>/conf directory.

<WEBNMS_HOME>/jsp/Login.jsp
<WEBNMS_HOME>/jsp/WebStart.jsp

The portion of code snippet that is to be edited in Login.jsp file is given below (highlighted in bold)

<form method=get action="../conf/WebNMS.jnlp" name="webstartform"> <BR>
<INPUT TYPE="SUBMIT" NAME="webstartclient" VALUE="Web Start Client">

<INPUT TYPE=HIDDEN NAME="webstart" >
</form></td>

Besides, the tags <SCRIPT LANGUAGE= "Javascript"> and <SCRIPT LANGUAGE="VBScript"> that appear in Login.jsp file is to be commented.

Once these files are edited they must be compiled using compileJSP.bat or compileJSP.sh located in <Web NMS Home>/bin directory.

When does JNLP file corruption take place throwing a NullPointerException while trying to access "Java Web Start" through the browser?

By default the startnms.bat/startnms.sh file (present under <Web NMS Home>/bin directory) contains an entry which is as follows

-Dwebserver.port=%WEBSERVER_PORT% (Full Entry : %JAVA_HOME%\bin\java

-cp %CLASS_PATH% -Dmysql.home=%MYSQL_HOME%
-Dwebserver.port=%WEBSERVER_PORT% -Xmx100m
-Dresource_check="%WEBSERVER_PORT%,%WEBCONTAINER_PORT%"

-Dtomcat.home=%TOMCAT_HOME%
-Dwebserver.rootdir=%WEBSERVER_HOME%
-Djava.rmi.server.codebase=%CODEBASE_LIST%
com.adventnet.nms.startnms.NmsMainBE NMS_BE_PORT 2000 ROOT_DIR
%NMS_HOME% NATIVE_PING true )

This property specifies the webserver port. The value of the WEBSERVER_PORT is specified in the setEnv.bat/setEnv.sh file located in <Web NMS Home> directory as

set WEBSERVER_PORT=9090

If this property is removed or given wrongly in the startnms.bat/startnms.sh file or if the entry WEBSERVER_PORT in setEnv.bat/setEnv.sh is removed, this exception will occur.

What is the specific function of the JnlpFileUpdater?

The JnlpFileUpdater performs the following jobs:
- Updates the hostname and port: By default, the hostname and port in WebNMS.jnlp file is "localhost" and "9090" respectively. If the user connects the Web Start client to a server running in another machine (i.e. the user first displays the login page and clicks the Web Start button, then the hostname and port is updated by this JnlpFileUpdater.
- Updates the jar files, which are used by Web Start client: Clicking the Web Start button, WebNMS.jnlp is invoked using the javaws and the Java Web Start client tries to download the jar files from the localhost. As the default code base is <jnlp codebase="http://localhost:9090" href="conf/WebNMS.jnlp"> hence, if the server is not running in the machine where the Web Start client is invoked, it throws exceptions. To overcome this, you need to hard code the hostname and port of the server in the WebNMS.jnlp file. Here, the JnlpFileUpdater updates the hostname and port, every time the Web Start client is started.
  
  This JnlpFileUpdater class resides in the server machine, and the hostname is retrieved using InetAddress class.

Updating hostname and port is valid when the Web Start client is connected for the first time, then why is it updated every time?

Updating the jar files in WebNMS.jnlp file: To include a class file in Applet client, it has to be made as a jar file and must be specified in NMS_ARCHIVE or ARCHIVE attribute in clientparameters.conf file (present in <Web NMS_Home>/conf directory). In case of Web Start client, it must be specified in the jar attribute of WebNMS.jnlp file. This methodology makes you to enter the client-side jar entries in two files. To enable flexibility, the JnlpFileUpdater file reads the contents of NMS_ARCHIVE and ARCHIVE attributes of the clientparameters.conf file and updates the WebNMS.jnlp file. Therefore to integrate a client-side class in the Applet client and Web Start client, you need to specify entry in clientparameters.conf file (i.e. in NMS_ARCHIVE & ARCHIVE) alone.

For example :

If your NMS_ARCHIVE & ARCHIVE entry in clientparameters.conf file is like this,

NMS_ARCHIVE="../classes/NmsClientClasses.jar,../classes/Netrake.jar"
ARCHIVE="../classes/Archive1.jar,../classes/Archive2.jar"

Then the generated resource tag in WebNMS.jnlp file will be like this,

<resources>
<j2se version="1.3+" initial-heap-size="100M" max-heap-size="200M" />
<jar href="classes/NmsClientClasses.jar"/>
<jar href="classes/Netrake.jar"/>
<jar href="classes/Archive1.jar"/>
<jar href="classes/Archive2.jar"/>
</resources>

How to integrate a new class file in Web Start client?

To integrate a new class file (e.g. NewFile.class) in Web Start client, please do the following:
1. Create a jar file (NewFile.jar) for the class file (NewFile.class),which is to be integrated in the Web Start client.
2. Put this jar file in the <Web NMS_Home>/classes directory.
3. Put the jar file entry in the clientparameters.conf file as given here;

NMS_ARCHIVE="../classes/NmsClientClasses.jar,../classes/Netrake.jar,../classes/NewFile.jar"

ARCHIVE="../classes/Archive1.jar,../classes/Archive2.jar,../classes/NewFile.jar"

ARCHIVE="../classes/NewFile.jar,../classes/Archive1.jar,../classes/Archive2.jar"

Note: While specifying the user jar files in clientparameters.conf file, it should not be specified as a first entry, since in java web start, the file jar file should contain the main method. Our NmsClientClasses.jar file contains that main method, which invokes the Client Authentication Dialog.

1. Connect web start client.
  
  If you do not want to regenerate the WebNMS.jnlp, when the web start button is clicked then change the <Web NMS_Home>/jsp/WebStart.jsp as per your need. In the WebStart.jsp file, follow the below given code snippet,

String webstart = request.getParameter("webstart");

if(webstart != null)

{

if(webstart.equals("installed"))

{

JnlpFileUpdater parser = new

JnlpFileUpdater(null);

response.sendRedirect("../conf/WebNMS.jnlp");

}

else if(webstart.equals("notinstalled"))

{

}

comment or remove the line "JnlpFileUpdater parser = new JnlpFileUpdater(null);"

and compile the jsp file using <Web NMS Home>/bin/compileJSP.bat / sh file.

Trouble Shooting Tips

I downloaded all the Java Client jars from machine A (where Web NMS Server is running) and then I tried to connect the client to Machine B, it this throws >AccessControlException in the Web Start Log console, Why?

This due to Java Web Start Security restrictions (security sandbox). Any client application launched form Web Start can only connect (or access any resource) only from the server machine from which it was downloaded. If any downloaded client application breaks this rule, a AccessControlException will be thrown.

In this case, as the Web NMS Java Client jars are downloaded from Web NMS server running in machine A, hence when you try to connect your client to the Web NMS Server running on machine B, Web Start will throw a AccessControlException. This is due to the fact that the Java Client will try to establish a socket connection to machine B, which is not the machine from which it was downloaded from. Hence this exception is thrown. Do also refer to a related question discussed below

When does the java.lang.NoClassDefFoundError javax/jnlp/UnavailableServiceExceptiongets thrown?

For this feature, jnlp.jar ( in /classes directory) must be present in the client class path (i.e. in your case this jar file must be found in the JBuilder's classpath). As you can see in the error sent by you (java.lang.NoClassDefFoundError javax/jnlp/UnavailableServiceException), indicates that the client needs UnavailableServiceException class, which is contained in jnlp.jar.This exception is caused due to jnlp.jar is not in the client classpath. So kindly make sure this jar file (jnlp.jar) is in the JBuilder's classpath, where your WebNMS client is invoked.