The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
PAR-WebStart-0.20
River stage zero No dependents
++
/ PAR::WebStart::PNLP

NAME

PAR::WebStart::PNLP - Parse pnlp files

SYNOPSIS

  my $file = 'hello.pnlp';
  my $obj = PAR::WebStart::PNLP->new(file => $file);
  my $cfg = $obj->parse();

Description

This module is used to parse PNLP files, which are XML files whose syntax is described later in this document. The $cfg data structure returned is a hash reference, the key being the XML elements encountered. The value associated with this key are either

  • a reference to an array of hash references, in the cases of the par, argument, module, or description elements,

  • a hash reference, for all other elements.

The hash references involved in these values have keys corresponding to the names of any attributes of the element, if found, as well as a key of value, if there is a value of the element. The associated values of these keys are the corresponding values of the attributes or the element's value, as applicable. Except for the cases of par, argument, module, and description, the hash references associated with all elements seen are guaranteed to have one key of seen, of value 1, even if no attribute or value are defined.

Syntax

The syntax for a PNLP file is based liberally on the Java Network Launching Protocol and API (JNLP) Specification v1.0.1 http://java.sun.com/products/javawebstart/download-spec.html.

The PNLP file is an XML document; an example is as follows:

 <?xml version="1.0" encoding="utf-8"?>
 <!-- PNLP File for Demo Application -->
  <pnlp
    spec="1.0+"
    codebase="http://my_company.com/pnlp/apps"
    href="app.pnlp">
  <information>
    <title>App Demo Application</title>
    <vendor>Our Company</vendor>
    <homepage href="docs/help.html"/>
    <description>App Demo Application</description>
    <description kind="short">A demo of the capabilities</description>
    <icon href="images/image.jpg"/>
    <icon kind="splash" href="images/splash.gif"/>
  </information>
  <security>
      <allow-unsigned-pars />
  </security>
  <resources>
    <perlws version="0.2"/>
    <par href="lib/app.par"/>
    <par href="lib/helper.par"/>
  </resources>
  <application-desc main-par="app">
    <argument>arg1</argument>
    <argument>arg2</argument>
  </application>
 </pnlp>

This shows the basic outline of the document. The root element is pnlp, which has four subelements: information, security, resources, and application-desc. The elements are described in more detail below.

Elements

pnlp

The pnlp element can have the following attributes.

spec

This denotes the pnlp specification used.

codebase

All relative URLs specified in href attributes in the PNLP file are using this URL as a base.

href

This is a URL pointing to the location of the PNLP file itself.

information

The following elements can be specified.

title

The name of the application.

vendor

The name of the vendor of the application.

homepage

Contains a single attribute, href, which is a URL locating the home page for the application. It is used to point the user to a web page where more information about the application can be found.

description

A short statement about the application. Description elements are optional. The kind attribute defines how the description should be used. It can have one of the following values:

one-line

If a reference to the application is going to appear on one row in a list or a table, this description will be used.

short

If a reference to the application is going to be displayed in a situation where there is room for a paragraph, this description is used.

tooltip

If a reference to the application is going to appear in a tooltip, this description is used.

Only one description element of each kind can be specified. A description element without a kind is used as a default value. All descriptions contain plain text; no formatting, such as with HTML tags, is supported.

At present perlws.pl ignores the attribute of the description. In the future different descriptions may be used in different contexts.

icon

Contains an HTTP URL to an image file in either GIF or JPEG format, used to represent the application. The optional kind="splash" attribute may be used in an icon element to indicate that the image is to be used as a "splash" screen during the launch of an application.

At present the perlws.pl application only downloads the image to the specified cache directory, for possible use by the par application. In the future this image may be used in the initial welcome screen that the user is presented with.

security

Each jar file, by default, must be signed using Module::Signature before being used by the client. If an element <allow-unsigned-pars /> appears here, such signing checks will be disabled. The client will be warned that this has taken place.

resources

The resources element is used to specify the resources, normally as PAR files, that are part of the application. A resource definition can be restricted to a specific operating system, architecture, or perl version using the following attributes:

os

This corresponds to $Config{osname}.

arch

This corresponds to $Config{archname}.

version

This denotes the minimal perl version required (as given by $]) and must be given in the form, for example, 5.008006 for perl-5.8.6.

perl_version

This corresponds to $Config{PERL_VERSION}, and denotes the PERL_VERSION of Perl 5 the client must have.

The resources element has two different possible subelements: par and perlws.

par

A par element specifies a PAR file that is part of the application. The location is given by an href attribute. There must be an md5 checksum file, with the same name as the par file with an .md5 extension, present in the same location as the par file. This is used as a mild security check, as well as a test if an update to a locally cached copy of the par file is available.

The par element can optionally have any combination of os, arch, version, or perl_version, as described for the resource element; if these are present, the PAR file specified will only be used if the client's Perl configuration matches the specified attributes.

perlws

The perlws element specifies, by a version attribute, which minimal version of PAR::WebStart is required.

application-desc

The application-desc describes the application. It has an an optional attribute, main-par, which can be used to specify the name of the par file (without the .par extension) containing the main.pl script to be run. This attribute is not needed if only one PAR file is present. If it is not specified, it will be assumed that the first par file specified contains the main.pl script.

Arguments can be specified to the application by including one or more nested argument elements. For example:

  <application-desc main-par="A">
    <argument>arg1</argument>
    <argument>arg2</argument>
  </application-desc>

Additional perl modules needed by the client to run the application may be specified as

  <application-desc main-par="A">
    <module>Tk</module>
    <module>Net::FTP</module>
  </application-desc>

The running of the application will abort if these modules are not available.

For Win32, specifying a <wperl /> element within application-desc will cause the application to be launched with wperl. With this, no console window will appear, meaning the application will not have access to STDOUT, STDIN, nor STDERR.

COPYRIGHT

Copyright, 2005, by Randy Kobes <r.kobes@uwinnipeg.ca>. This software is distributed under the same terms as Perl itself. See http://www.perl.com/perl/misc/Artistic.html.

SEE ALSO

PAR::WebStart