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 arguments 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 child directory of CTP/ROOT. The name of the directory must be the same as the name of the application. For example, the CTPClient program and all its libraries must be placed in the CTP/ROOT/CTPClient 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>
        <param><![CDATA[{param1name}={param1value}]]></param>
         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 CTPClient application, the URL might be:

http://nbia.somewhere.edu/webstart/CTPClient?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>CTPClient</application>
    </environment>
    <params>
        <param><![CDATA[title=My Institution]]></param>
        <param><![CDATA[name=My Name]]></param>
    </params>
</jnlp>

The XSL program to launch this application would be CTP/ROOT/CTPClient/CTPClient.xsl:

<?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}" >
        <!-- href="{environment/application}.jnlp" > -->

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

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

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

        <application-desc main-class="client.CTPClient">
            <argument>"protocol=<xsl:value-of select="environment/protocol"/>"</argument>
            <argument>"host=<xsl:value-of select="environment/host"/>"</argument>
            <argument>"application=<xsl:value-of select="environment/application"/>"</argument>
            <xsl:apply-templates select="params/param"/>
        </application-desc>
    </jnlp>
</xsl:template>

<xsl:template match="param">
    <argument>"<xsl:value-of select="."/>"</argument>
</xsl:template>

</xsl:stylesheet>

Notes:

• The arguments supplied to the application will all have the form:

  "{paramname}={paramvalue}"

• This program automatically supplies the host domain name and the application name as arguments.
• The <j2se> element has the optional max-heap-size attribute. This can be used to assign the application more than the default memory allocation. The value of the attribute is specified like the Java -Xmx parameter (e.g., max-heap-size="768m").
• 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 can be re-signed by the common certificate or they can be referenced by <extension> 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 attempt to download the JNLP file, and when that access fails, it will refuse to launch the application.