Using the CTP Application Server

This article describes how to use the CTP Application Server to download and launch Java applications using the Java Web Start protocol (JNLP).

Java Web Start allows Java programs to be run from a server without being installed on the client. The download is started by accessing a resource on the server through a browser. The resource is an XML structure that is served to the browser with the content type application/x-java-jnlp-file. The XML provides all the necessary information to allow Java to import the program and any resources it needs from the server and run it on the client with the necessary security constraints.

The simplest way to launch a Web Start application from the CTP server is to put the JNLP XML file, the program, and all the resources it requires in the CTP/ROOT directory or in one of its subdirectories. The program is launched simply by accessing the JNLP XML file, which must have the extension .jnlp. For example, if the JNLP XML file is located at CTP/ROOT/apps/MyApp.jnlp, the URL path would be /apps/MyApp.jnlp. In this method, it is not possible to supply parameters to the program dynamically.

The CTP Application Server is a servlet that is included in all CTP versions starting with 2012/08/15. The servlet is accessed through the URL /webstart/{name}, where {name} is the name of the application program to be launched. The purpose of the Application Server is to allow parameters to be supplied to the program from query parameters in the request.

To deploy a Java program for downloading by the Application Server servlet, the program and all the resources it uses (jar libraries, etc.) must be placed in a first-generation child directory of CTP/ROOT. The name off the directory must be the same as the name of the application. For example, the TCIASender program and all its libraries must be placed in the CTP/ROOT/TCIASender directory.

An XSL file with the name {name}.xsl must also appear in the same directory. The XSL file is used by the servlet to process a dynamically generated XML document and produce the JNLP XML structure required to trigger the download and launch the application.

The structure of the dynamically generated document is:

<jnlp>
    <environment>
        <protocol>http[s]</protocol>
        <host>{ip:port}</host>
        <application>{appname}</application>
    </environment>
    <params>
        <{param1name}><![CDATA[{param1value}]]></{param1name}>
         etc.
    </params>
</jnlp>

The values of the elements in the document are constructed by the servlet from the HTTP request. For example, to launch the TCIASender application, the URL might be:

http://nbia.somewhere.edu/webstart/TCIASender?title=My%20Institution&name=My%20Name

In this case, the document generated by the servlet will be:

<jnlp>
    <environment>
        <protocol>http</protocol>
        <host>nbia.somewhere.edu:80</host>
        <application>TCIASender</application>
    </environment>
    <params>
        <title><![CDATA[My Institution]]></title>
        <name><![CDATA[My Name]]></name>
    </params>
</jnlp>

The XSL program to launch this application would be:

<?xml version="1.0" encoding="iso-8859-1"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:output method="xml" encoding="utf-8" omit-xml-declaration="yes" />

<xsl:template match="/jnlp">
	<jnlp codebase="{environment/protocol}://{environment/host}/{environment/application}" >

		<information>
			<title>TCIA Transport Utility</title>
			<vendor>RSNA</vendor>
			<homepage href="http://mircwiki.rsna.org//index.php?title=CTP-The_RSNA_Clinical_Trial_Processor"/>
			<description>TCIA Transport Utility</description>
			<description kind="short">Java Web Start program for transmitting images to TCIA for clinical trials.</description>
		</information>

		<security>
			<all-permissions/>
		</security>

		<resources>
			<j2se version="1.5+"/>
			<jar href="TCIASender.jar"/>
			<jar href="CTP.jar"/>
			<jar href="dcm4che.jar"/>
			<jar href="log4j.jar"/>
			<jar href="util.jar"/>
		</resources>

		<application-desc main-class="tcia.TCIASender">
			<argument>"<xsl:value-of select="params/title"/>"</argument>
			<argument>"<xsl:value-of select="params/name"/>"</argument>
		</application-desc>
	</jnlp>
</xsl:template>

</xsl:stylesheet>

Notes:

• If the <all-permissions/> element is included, all the jars listed in the <resources> element must be signed by the same certificate. (If libraries signed by other certificates are required, they must be referenced by <resources> elements that point to separate JNLP files.)
• This method of launching the application does not support its being launched by the Java Application Manager off-line because there is no JNLP file available on the disk. Thus the href attribute of the <jnlp> element must not be generated by the XSL. Doing so will cause the Application Manager to be unable to launch the application.