In this guide we will show you how to create an extension that will download, configure and execute a Java based application. If you are unsure as to what an extension is, then check out this guide.

We will create an extension for the TightVNC Java application, the main difference between executable extensions and java extensions is that instead of downloading files and invoking an executable, we must set the Java classpath and invoke a main class file. For TightVNC this will mean downloading the VncViewer jar file and invoking the main class file in that jar.

Before we start I will explain some of the differences between a Java extension and a Native Executable extension.

First there is no <executable> element, as there is no binary file to execute. In order to launch the application a element is used, this java element also contains a number of additional elements and attributes that are used to specify the jar files, and the class files that are be used to launch the application.

Secondly, whilst a Java extension can make use of the <files> element it is not always necessary. This is because Java applications are normally distributed as a set of Jar files that have all of the classes and resource files needed to run the application. If you need to use separate files you can still do so however jar files are specified separately in the <classpath> element.

Finally, because this extension uses a Java application that is system independent, the extension can be used on any operating system whereas a Native Executable extension can only be used on one type of operating system (Windows only, Linux only, etc).

I have also introduced the <bundle> element in this article which can be used to create a single archive containing multiple extensions. Whilst this article only creates a single extension, the bundle element is used as it allows the option to prompt the user to accept a license file before the extension is installed. In this case, as TightVNC is licensed under GPL we will include a copy of this license and make the user accept its terms before they can install and use the extension.

Extension structure
To begin, create a new directory called 'TightVNC' on your hard drive and download the latest Java version of VNC from tightvnc.com. We are using the tightvnc-1.2.9_javabin.zip download. Once the download has completed extract the contents of the zip file into the newly created folder.



Now create a file called "extension.xml" inside the newly created TightVNC folder and paste in the following XML template.

<bundle name="TightVNC Native Viewer" id="TightVNC" type="java" version="1.2.9" requiredHostVersion="0.1.9" license="GPL" licenseAgreement="LICENSE.TXT" productURL="http://www.tightvnc.com/">

<description>
TightVNC is a free remote control software package derived from the popular VNC software. With TightVNC, you can see the desktop of a remote machine and control it with your local mouse and keyboard, just like you would do it sitting in the front of that computer.
</description>

<extension name="TightVNC" type="java" application="TightVNC">
<description>
VNC software makes it possible to view and fully-interact with one computer from any other computer or mobile device anywhere on the Internet.
</description>

</extension>
</bundle>

As stated earlier, by using the <bundle> element we are able to force the user to accept a license. To do this we create a html version of the license and then use the 'licenseAgreement' attribute in the bundle element to show the license. This ensures that the user accepts the license before the extension is installed on to the server.

Collecting information from the user
Next we must allow the user to define the parameters that will be used to create the connection between local and remote systems.

For TightVNC, as a minimum, we need to select a destination host and port of the VNC server.

<parameter name="hostname" sequence="0" type="0"/>

First the hostname parameter will be a text field, this is defined by the type attribute and has a value of "0". We also add the sequence attribute to specify the order in which parameters should be displayed, the lower the number is, the closer it is to the top.

<parameter name="port" sequence="1" type="1" default="5900"/>

The port parameter must be a number, type "1", and be displayed second with a default value of port 5900.

TightVNC also allows the user to enter their VNC password. If a value is entered into this field then the password argument is run with this value when the application is launched. This will be added to the extension using the following parameter definition.

<parameter name="password" sequence="2" type="4" optional="true"/>

By selecting the parameter as a password, type 4, any entries made into this field will be protected by a masked input so that the value cannot be read by someone looking over the users shoulder. We have also included the optional="true" attribute; this instructs SSL-Explorer not to produce an error if the user does not enter a password.

We will also add a parameter for opening the remote display in a new window. This will be done with the following element.

<parameter name="openNewWindow" sequence="3" type="2" default="true" optional="true"/>

This time we have changed the type so that a checkbox is presented to the user with a default value of "true". There are many other command line options available but we will leave those for another day. There is one final task before we move on and that is to define the messages that are presented to the user for each parameter.

<messages>
<message key="hostname.name">Hostname</message>
<message key="port.name">Port</message>
<message key="password.name">Password (CAUTION)</message>
<message key="openNewWindow.name">Operate in a separate window</message>
</messages>

Each parameter requires its own message key which is constructed in the format of PARAMETER + ".name". So if we had a parameter called "foo" the message key would be "foo.name". The contents within the <message> element will be presented to the user when they create an extension shortcut.

Setting up a secure tunnel
The user has now entered enough information to invoke the application, before we do this however we will setup a secure SSL tunnel between the client and the SSL-Explorer server over which the VNC connection will be forwarded. An extension can setup as many tunnels as it wishes however in this instance we need a single tunnel. We setup a tunnel with the <tunnel> element.

<tunnel name="tightvnc" hostname="${shortcut:hostname}" port="${shortcut:port}" usePreferredPort="false"/>

This element instructs the client to setup an SSL tunnel from the localhost to the SSL-Explorer server with a final destination of ${shortcut:hostname} and port ${shortcut:port}. These special tokens will be replaced by the server with the values entered into the 'hostname' and 'port' parameters we defined earlier. We also gave the tunnel a name of "tightvnc" and this will be used later to reference the listening interface and port.

We have also specified the "usePreferredPort=false" attribute. When an SSL tunnel is created we are actually opening up a socket on the local machine to accept connections, this instructs the tunnel to select a random port instead of using the same port as ${shortcut:port}. This is advisable as sometimes you may be running a VNC server on your workstation.

Another function that has been added to the 0.2.0 branch is the ability to force a tunnel to remain open and accept further connections. If you wish to add this command to tunnel then simply add the following attribute to the tunnel element: singleConnection="false"

If you use this feature then you must close the tunnel manually using the SSL-Explorer Agent tunnel manager.

Specifying the main class and its arguments
Now that the tunnel is established we can configure the elements unique to a Java extension. All of these elements are contained with a element. Because there are many different version of Java we have to specify the minimum version of java that is needed to run the application. TightVNC only needs a minimum of JRE 1.1 so to specify this you would add the following element:

<java jre="1.1">

</java>

All of the remaining elements are entered between the <java> element and the next thing to define is the classpath. The classpath is the location of the main java class, the one that can launch the application. In our extension this is defined with the following.

<classpath>
<jar>classesVncViewer.jar</jar>
</classpath>

The main java class is located inside of the VncViewer.jar file inside the 'classes' directory. If you open this file in an archiving application such as WinZip you will find that there are a number of files inside. There should be one file called Manifest.mf which if opened in a text editor you will find a line that says something like:

Main-Class: VncViewer.

This is the main class that you will need to enter this into the extension. You can use the following style and you must use the exact class name.

<main class="VncViewer">

</main>

Now we can add our arguments between the <main> elements. This is achieved through using nested <arg> elements with one element for each argument.

If we examine the command line options for TightVNC we can see that we want to specify the hostname and port to connect to. Since we are using an SSL tunnel we need to find out what interface and port the tunnel is listening upon and this is achieved with the following argument element:

<arg>HOST</arg>
<arg>${tunnel:tightvnc.hostname}</arg>
<arg>PORT</arg>
<arg>${tunnel:tightvnc.port}</arg>

First the host argument is set and followed by the value ${tunnel:tightvnc.hostname} which identifies the listening interface (which will always be localhost). Then we have the port argument followed by and ${tunnel:tightvnc.port} which identifies the randomly generated port.

If the user selected the 'Open new window' parameter then we will want to include this command line option. Here we use a conditional <if> element to determine if the option should be included.

<arg>Open new window</arg>
<if parameter="OpenNewWindow" value="true">
<arg>Yes</arg>
</if>
<if parameter="OpenNewWindow" value="true" not="true">
<arg>No</arg>
</if>

Here the first part of the argument will always be provided but the option will change depending on the setting, if it is true then the Yes option is included, if it is false then the No option is included. We also want to perform a similar check on the password parameter, if the user supplied a password then we should include the password option. This can be achieved with a similar statement.

<if parameter="password" value="" not="true">
<arg>password</arg>
<arg>${param:password}</arg>
</if>

This time the argument will only be included if the value is not an empty string, this is done by using value="" and adding the not="true" attribute.

Packaging up the extension
And that's the basic extension created, the only thing left to do is to package up the extension so that it can be deployed to SSL-Explorer. Our system has WinZip installed on it so the easiest method is to locate the TightVNC folder we created earlier, select, right click and select the "Add to TightVNC.zip" option.

This creates a file called TightVNC.zip which when extracted will extract to a folder called TightVNC which contains the extensions contents and this is the format that SSL-Explorer expects. To install simply logon to SSL-Explorer and navigate to the extensions management page and upload using the form provided.

If you wish to you can extend the TightVNC extension further to support some of the other command line options that are available, if you do then please dont forget to submit your amendments to 3SP so that we can publish them for all SSL-Explorer users.

And theres more...
This article has been an introduction to the java extension architecture. There are more articles in the knowledge base that explain the other extension types and also the more advanced features that are available.

If you have any comments or suggestions on the extension architecture you can contact me via email ashleygrant at users dot sourceforge dot net.

If you have any completed extensions that you would like us to publish on our Extension Store then please send them to support@3sp.com.