Notes for JNLP Server CGI Program
---------------------------------
$Id: README.txt 4600 2013-01-15 10:25:25Z svn $
INTRODUCTION
------------
The Java programming language and execution environment provide an excellent
and portable way to implement a GUI (Graphical User Interface) client program
for a networked embedded device. If the embedded network device includes a
web server, the user interface client programs can be stored on the device and
downloaded as necessary by the user client web browser.
The Java language originally included the Applet class specifically for
the implementation of Java programs to be executed in a protected web browser
environment or sandbox. However, the difficulty in supporting applets in a
portable way led to the design of the Java Web Start environment that allows
execution of Java applications (not just applets) by a client web browser.
The Java Web Start client (built into the browser and/or Java extension) relies
on a JNLP (Java Network Launching Protocol) metadata file that describes the
Java application, where to retrieve it, and how to execute it. In large scale
installations, the JNLP metadata file is typically generated on the fly by a
Python or Perl script or some similar method. However, very small embedded
network devices may not have resources to run a Python or Perl interpreter.
This JNLP server is a CGI program that can be run from an embedded system
web server such as that included in the BusyBox suite. It will generate a
JNLP file on the fly, based on both compile time constants and query
parameters.
BUILDING:
---------
Download and unpack the source tarball. Switch to the source directory
and run make.
Some make macros can change the behavior of jnlp-server:
CROSS_COMPILE
Linux kernel style cross compiler prefix. Add something like:
CROSS_COMPILE=/usr/local/arm-2010.09/bin/arm-none-linux-gnueabi-
to the make invocation to cross compile jnlp-server.
VENDOR
Sets the vendor field in the JNLP file. Default is "Unknown".
DONOTACCESSJAR
If defined, don't try to verify existence/readability of the Java jar file.
So jnlp-server will generate a JNLP file even if the requested jar file is
unavailable. If not defined, jnlp-server will return an error message
instead of a JNLP file if the requested jar file is unavailable. Default
is undefined.
JAR_REPOSITORY
The location to search for jar files, from the CGI program process's
perspective. Not used if DONOTACCESSJAR is defined. Default is "java"
(which would imply the jar files are in cgi-bin/java).
JAR_REPOSITORY_EXTERNAL
The location to search for jar files, from the web client's perspective.
Default is "java" (which would imply the jar files are in
http://servername/java).
Example make invocation (note the double quoting):
make VENDOR='"Munts Technologies"' JAR_REPOSITORY='"/www/java"'
USAGE:
------
The jnlp-server CGI program is largely controlled by appending query
parameters to the URL. The following query parameters are recognized:
APPLICATION=<jarname> where jarname.jar is the name of the application JAR
file.
Writes jarname.jar into the JNLP file, to tell the Webstart client to
fetch jarname.jar and execute it.
OFFLINE=yes|no
Determines whether <offline-allowed/> is written to the JNLP file.
SECURITY=all
Determines whether <all-permissions/> is written to the JNLP file.
ARGn=<string> where n=1 to 100
The ARGn strings are written to the JNLP file and passed by the Webstart
environment to the Java main() method. JNLP will transform certain argument
strings: @@HOSTNAME@@ will be replaced by the web server name (from the
HTTP_HOST parameter) and @@APPNAME@@ will be replaced by the application name
(from the APPLICATION query parameter). So the Java application program can
discover the web server it came from and its own application name.
Here is an example URL for a Java application program that connects to a TCP/IP
server process on the server it came from:
<a href="/cgi-bin/jnlp-server?APPLICATION=rpc_example_client&
ARG1=%40%40HOSTNAME%40%40">HTTP GET Java Client</a>
When the user clicks on this URL from his web browser, a query will be sent to
the web server. The web server will run jnlp-server which will generate a JNLP
file on the fly and return it to the user's web browser. The Webstart code
within the browser will recognize the JNLP file and dispatch it to the Webstart
client module. The Webstart client module will download rpc_example_client.jar
from the web server and then execute it with the java interpreter, passing the
name of the web server as the first command line argument to the Java main()
method.
LINKS:
------
http://download.oracle.com/javase/tutorial/deployment/webstart/
http://tech.munts.com/MCU/Frameworks/ARM-Linux/example/
COPYRIGHT:
----------
Copyright (C)2013, Philip Munts, President, Munts AM Corp.
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification,are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
* Neither the name of Munts AM Corp. nor the names of its contributors may
be used to endorse or promote products derived from this software without
specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
