Use of JCP site is subject to the JCP Terms of Use and the Oracle Privacy Policy

Proposed Specification changes for JSR-056

Java Network Launching Protocol and API Specification

Andrew Herrick
Sun Microsystems
09/15/2003

Section 1 Specification bug fixes and clarifications

1.1)    4494529 Fix typos in specification
1.2)    4404764 DTD is not available on java.sun.com
1.3)    4391197 Clarify applet windows size specification
1.4)    4430266 Clarify signing requirements on intranet
1.5)    4648783 TCK-JNLP1.0.1: jnlp_file/resources/property/index.html
1.6)    4651285 TCK-JNLP1.0.1: jnlp_file/security/index.html
1.7)    4734863 Clarify scope of properties set in extensions
1.8)    4730088 Clarify range of kind attribute for icon element
1.9)    4928787 Clarify allowing multiple jar signatures

Section 2 Specification changes for new features

2.1)    4681907 Allow applications to hint shortcut preferences.
2.2)    4790673 Allow applications to hint desired vm args.
2.3)    4756982 Allow applications to associate with a file ext / mime-type
2.4)    4812563 Allow applications to describe a related-content hint
2.5)    4828991 Allow os, arch, and platform attributes on information element.
2.6)    4928956 Implement the "&" operator in version-ids.

Section 3 Specification changes for JNLP API extensions

3.1) 4390904 SingleInstanceService
3.2) 4467214 ExtendedService

1.1) Proposed JNLP Specification change for bug 4494529.

Overview:

The JNLP specification version 1.0.1 contains several typo's.

Justification:

Typographical errors should be addressed.

Proposed change to the specification:

1.) Section 3.4 change:

From: A JNLP Client must used the URL ...

To: A JNLP Client must use the URL ...

2.) Section 3.5 change:

From: Each locale is specified by a language identifier, a possibly country identifier, and ...

To: Each locale is specified by a language identifier, possibly a country identifier, and ...

3.) Section 4.2 change:

From: For example, given the following declarations, n the given order:

To: For example, given the following declarations, in the given order:

4.) Section 4.3 change:

From: resource element that is guarded against a particular operating ...

To: resource element that is intended for a particular operating ...

5.) Section 5.6 change:

From: An application must only be launched if it is trusted.

To: An application with unrestricted access may only be launched if it is trusted.

6.) Section 6. change:

From: The following table summarize the ...

To: The following table summarizes the ...

7.) Remove section 8, Future Directions, entirely

1.2) Proposed JNLP Specification change for bug 4404764.

Overview:

The JNLP specification version 1.0.1 in Appendix C, section C.1 says that this dtd is available at
"http://java.sun.com/products/j2se/dtds/jnlp_1_0.dtd". Since it's not there we should remove this line.

Justification:

The JNLP specification should make no claims about what is hosted on java.sun.com.

Proposed change to the specification:

1.) Change comment in section C.1

From:

<!DOCTYPE jnlp-discriptor PUBLIC "-//Sun Microsystems, Inc//DTD JNLP Discriptor 1.0//EN"
"http://java.sun.com/products/j2se/dtds/jnlp_1_0.dtd">

To:

<!DOCTYPE jnlp-discriptor PUBLIC "-//Sun Microsystems, Inc//DTD JNLP Discriptor 1.1//EN">

1.3) Proposed JNLP Specification change for bug 4391197.

Overview:

The JNLP specification version 1.0.1 Section 3.6.2 defines the width and height attributes of the applet-descriptor element. It should be noted here that the actual width and height of the applet may differ from the values supplied in as much as the JNLP Client may implement the applet container using a java Frame or other object with system dependent limits on it's size.

Justification:

TCK test writers, reading the spec as it is, assumed they could set the width and height of an applet to 100. When reading it back with Applet.getSize() they found a width of 106 on some windows platforms. This was because 106 was the minimum size for a resizable Frame on WinNT.

Proposed change to the specification:

1.) Add line to Section 3.6.2 (after width and height attributes):

The JNLP Client may set the actual size to be more or less than the specified size, to fit within the minimum and maximum dimensions for a Java Frame on each platform.

1.4) Proposed JNLP Specification change for bug 4430266.

Overview:

The JNLP specification version 1.0.1 defines (in section 5.5) the exact set of permissions that a JNLP Client must grant to an “untrusted” application or applet. It also defines (in section 5.6) the set of permissions that must be granted to a “trusted” application or applet that specifies <j2ee-application-client-permissions> or <all-permissions>. We wish to allow the client to grant more or less permissions than this specified default set, in accordance with the configured policys on the client system.

Justification:

Customers have requested the ability to restrict clients within their enterprise to running specific applications, running only applications from a particular codebase, or running only applications signed with a particular certificate. There have also been customers such as Goldman Sax requesting the ability to limit the permissions granted to trusted applications and applets. Features have been designed to address these requests, requiring these changes in the specification.

The current reference implementation conflicts with the specification in that an untrusted app is granted additional permissions as specified in the .java.policy file in his home directory.

Proposed change to the specification:

1.) Add line to end of Section 5.5:

The sandbox environment described above is the default set of permissions granted to an untrusted application or applet. The JNLP Client may allow the user or system administrator to configure alternative permission sets for untrusted applications and applets.

2.) Add line to end of Section 5.6:

The two permission sets described above are the default set of permissions granted to a trusted application or applet requesting all-permissions or j2ee-application-client-permissions. The JNLP Client may allow the user or system administrator to configure alternative permission sets for trusted applications and applets.

1.5) Proposed JNLP Specification change for bug 4648783.

Overview:

The JNLP specification version 1.0.1 section 4.2 describes how the application can set system properties by using the property element in the JNLP file. Also section 5.5 says: "A application has read and write access to all the properties in the JNLP file."

The security team determined that setting arbitrary system properties was a security risk, and that the client implementation should only allow the JNLP file to set system properties that it knows to be safe, when running an untrusted application.

Justification:

The security team required this change in version 1.0.1_02 of the reference implementation. Since then the RI has been in conflict with the specification.

Proposed change to the specification:

1.) Add paragraph to end of section 4.2:

For an untrusted application (see section 5.5) system properties set in the JNLP file may only be set by the JNLP Client if they are considered secure. At a minimum a JNLP Client will allow setting system properties whose name starts with "jnlp." .

2.) Change section 5.5:

From:

Properties: A application has read and write access to all the properties in the JNLP file. Properties specified in the JNLP file must overwrite the default value of the above properties.

To:

Properties: An untrusted application has read and write access only to those properties considered secure by the JNLP Client. At a minimum the JNLP Client will allow read and write access to properties beginning with "jnlp." .

1.6) Proposed JNLP Specification change for bug 4651285.

Overview:

The specification version 1.0.1 in section 5.5 lists permissions that must be granted to to an untrusted application's resources. Included in this list is: java.awt.AWTPermission showWindowWithoutWarningBanner. The security team determined that this was a security risk, and the permission was removed from the reference implementation.

Justification:

The security team required this permission be removed from the reference implementation, and the RI and the specification have been in conflict since Java Web Start 1.0.1_02.

Proposed change to the specification:

1.) In Section 5.5: Remove the line:

"java.awt.AWTPermission showWindowWithoutWarningBanner"

from the table of granted permissions.

1.7) Proposed JNLP Specification change for bug 4734863.

Overview:

The JNLP specification version 1.0.1 in section 4.2 defines how to set properties in a JNLP file, without clearly stating the
expected effect. There is no distinction made between extension JNLP files and main JNLP files.

The specification in section 4.6 also describes the j2se element without noting that it only has effect in a main JNLP file.

Justification:

This is only a clarification of the behavior expected by the original drafters of the spec.

Proposed change to the specification:

1.) Add to section 4.2:

Properties set in the JNLP file may be set by the JNLP Client at any time before the application's code is executed, so it cannot be assumed that they will be set during the initialization of the virtual machine.

Properties set in an extension JNLP file may be set any time before code from that extension is executed.

2.) Add to section 4.6:

The j2se element in the application descriptor defines the version of java used to run the application (or applet). Any j2se element in an extension descriptor is ignored.

1.8) Proposed JNLP Specification change for bug 4730088.

Overview:

The specification version 1.0.1 in section 3.5 describes the kind attribute of the icon element by saying: "The optional kind attribute can be used to indicate the use of the icon, such as default, selected, disabled, and rollover". However the DTD in appendix C is more stringent:

<!ATTLIST icon kind (default | selected | disabled | rollover) "default" >

We would like to allow JNLP Client to implement arbitrary values for kind, as section 3.5 implies, as well as suggesting other examples.

Justification:

The dtd in appendix C is more restrictive than the text of the specification. Customer demand for customizable splash screens caused us to implement kind="splash" in the RI. We are also looking at demand to implement kind="shortcut" for future releases.

Proposed change to the specification:

1.) In section 3.5, change the line defining kind attribute to:

The optional kind attribute can be used to indicate the use of the icon, such as default, selected, disabled, rollover, splash, and shortcut.

2.) Change line in appendix C:

From: <!ATTLIST icon kind (default | selected | disabled | rollover)"default" >

To: <!ATTLIST icon kind CDATA #IMPLIED>

1.9) Proposed JNLP Specification change for bug 4928787.

Overview:

The specification version 1.0.1 in section 5.4 defines a signed application saying: "A single certificate must be used to sign each jar file.". This has been misinterpreted to mean a jar file cannot have more than one signature. We wish to clarify this.

Justification:

Previous versions of Java Web Start implemented the restriction that no jar can be signed twice. The security team has indicated that allowing multiple signatures is preferred, and Java Plugin implements it this way.

Proposed change to the specification:

In section 5.4 change:

All the JAR files are signed (both for jar elements and nativelib elements) and can be verified. A JAR file is signed if the signature covers the entire JAR file. A single certificate must be used to sign each JAR file.

To:

All the JAR files are signed (both for jar elements and nativelib elements) and can be verified. A JAR file is signed if all the entries (excluding manifest entries, the signature itself, and empty directories) are signed.

2.1) Proposed JNLP Specification change for bug 4681907.

Overview:

The JNLP Specification version 1.0.1 does not allow the application deployer any control over the desktop integration of the application. This change is to give applications the ability to hint to the JNLP Client if and where they prefer to be integrated into the desktop. To implement this we propose adding a "shortcut" element as a sub-element of the "information" element. The element would have the possible sub-elements "desktop" and "menu", and the optional attribute "online". The "menu" element could have an optional "submenu" attribute. The "online" attribute would have the possible values "true" and "false". The "submenu" attribute would have a string value denoting the sub-menu name.

Justification:

Customers have requested a richer desktop integration experience and the ability to hint shortcut preferences.

Proposed change to the specification:

1.) Add to the bottom of the <information> section of the example at the start of section 3.5:

<shortcut online="false">
<desktop/>
<menu submenu="My Corporation Apps"/>
</shortcut>

2.) Add to the end of section 3.5:

shortcut element: The optional shortcut element can be used to indicate an application's preferences for desktop integration. The shortcut element and it's sub-elements provide hints that the JNLP Client may or may not use. The shortcut element can contain the optional online attribute, and the two optional sub-elements desktop and menu.

online attribute: The optional online attribute can be used in a shortcut element to describe the applications preference for creating a shortcut to run the application online or offline. If the value is "true" the application prefers to create a shortcut that will launch the application online. If the value is "false" the application prefers to create a shortcut that will launch the application offline.

desktop element: The optional desktop element can be used to indicate an application's preference for putting a shortcut on the users desktop.

menu element: The optional menu element can be used to indicate an application's preference for putting a menu item in the users start menus. The menu element can have a sub-menu attribute.

submenu attribute: The optional submenu attribute can be used to indicate an application's preference for where to place the menu item, and can contain any string value.

The shortcut element provides hints to the JNLP Client which may or may not be used.

3.) Change the information element in Appendix C to:

<!ELEMENT information (title?, vendor?, homepage?, description*, icon*,offline-allowed?, shortcut?)>

4.) Add the shortcut element to the dtd in Appendix C:

<!ELEMENT shortcut (desktop? menu?)>

<!ATTLIST shortcut online (true | false) "true">

<!ELEMENT desktop EMPTY>

<!ELEMENT menu EMPTY>

<!ATTLIST menu submenu CDATA #IMPLIED>

2.2) Proposed JNLP Specification change for bug 4790673.

(also covers 4625809, 4670925, and 4491200)

Overview:

The JNLP specification version 1.0.1 section 4.6 describes the j2se element with the two possible attributes "initial-heap-size" and "max-heap-size". We would like to add the attribute "java-vm-args" to allow arbitrary vm args that the JNLP Client considers secure.

Justification:

Customers have requested we add specific new attributes to the j2se element in the JNLP Specification to allow them to run: "-server", "-client", "-Xint", "-verbose", "-Xincgc", "-Xnoclassgc", and "-Xssn". This proposal covers all of these as well as any additional arguments requested in the future, without a specific specification change for each one.

Proposed change to the specification:

1.) Section 4.6, add:

java-vm-args: Indicates an additional set of standard and non-standard virtual machine arguments that the application would prefer the JNLP Client to use when launching Java, such as: -server, -client, -Xint, -Xincgc, -Xnoclassgc, and -Xssn. The JNLP Client may honor this preference only if it considers each argument to be secure.
when invoking java if the JNLP Client determines them to be secure, such as: -server, -client, -verbose, -Xint, -Xincgc, -Xnoclassgc, and -Xssn.

2.) Appendix C add:

<!--

The java-vm-args attribute of the j2se element specifies a preferred set of virtual machine arguments to use when launching java.
-->
<!ATTLIST j2se java-vm-args CDATA #IMPLIED>

2.3) Proposed JNLP Specification change for bug 4756982.

Overview:

The JNLP Specification does not allow an application any method of hinting to the JNLP Client that it wishes to be invoked as the primary handler of a specific file extensions and a mime-type. Installed applications can commonly register themselves with the operating system as the handler of specific extensions and mime-types, and we wish to provide the same capability to jnlp applications. We propose adding the element association, as a sub-element of the information element, with attributes extension and mime-type.

Justification:

We have received several internal and external requests for this feature.

Proposed change to the specification:

1.) Add to the end of section 3.5:

association element: The optional association element is a hint to the JNLP client that it wishes to be registered with the operating system as the primary handler of certain extensions and a certain mime-type. The association element must have the extensions and mime-type attributes.

extensions attribute: The extensions attribute contains a list of file extensions (separated by spaces) that the application requests it be registered to handle.

mime-type attribute: The mime-type attribute contains a mime-type that the application requests it be registered to handle.

An application making such a request should be prepared to have its main method invoked with the arguments "-open filename" and "-print filename" instead of any arguments listed in the argument attribute of the application-desc element.

2.) Change the information element in Appendix C to:

<!ELEMENT information (title?, vendor?, homepage?, description*, icon*,offline-allowed?, association?)>

4.) Add the association element to the dtd in Appendix C:

<!ELEMENT association EMPTY>

<!ATTLIST association extensions CDATA #REQUIRED>

<!ATTLIST association mime-type CDATA #REQUIRED>

2.4) Proposed JNLP Specification change for bug 4812563.

Overview:

The JNLP Specification does not allow an application any method of hinting to the JNLP Client that it wishes to include content related to the application in any desktop integration of the application. This proposal adds the related-content element to the information element. The related-content element has an href attribute to specify the content, along with sub-elements title, description, and icon, to aid in desktop integration.

The related-content element is a hint that may be ignored by the JNLP Client.

Justification:

We have received internal requests that jnlp be sufficient to fully describe an application and it's related materials.

Proposed change to the specification:

1.) Add to the end of section 3.5:

related-content element: The optional related-content element describes an additional piece of related content, such as a readme file, help pages, or links to registration pages, as a hint to the JNLP Client. The application is asking that this content be included in its desktop integration . The related-content element has a mandatory href attribute. It can contain any of the following three sub-elements:

title element: The name of the related content.

description element: A short description of the related content.

icon element: The icon can be used by the JNLP Client to identify the related content to the user.

example of related-content elements:

<information>
    ...
    <related-content href="readme.html">
        <title>README</title>
        <description>The README file contains additional information about the product </description>
        <icon href="readme.jpg"/>
    </related-content>
    <related-content href="register.html">
        <title>Program Registration</title>
        <description>Register this product to receive support and valuable discounts of other
             products</description>
    </related-content>
</information>

2.) Change the information element in Appendix C to:

<!ELEMENT information (title?, vendor?, homepage?, description*, icon*,offline-allowed?, shortcut?, association?, related-content*)>

3.) Add the related-content element to the dtd in Appendix C:

<!ELEMENT related-content (title?, description*, icon*)>

<ATTLIST related-content href CDATA #REQUIRED>

2.5) Proposed JNLP Specification change for bug 4828991.

Overview:

The JNLP Specification allows an application to specify platform and os specific resources, but not platform and os specific information elements. This prevents supplying icons in platform specific formats.
We propose adding os, arch, and platform arguments to the information element, and softening the wording defining icons to allow platform specific formats.

Justification:

This is a requirement for madhatter.

Proposed change to the specification:

1.) Insert to section 3.5, before locale attribute:

os attribute: Specifys the operating system for which the information element should be considered. If the value is a prefix of the os.name system property, then the information element can be used. If the attribute is not specified it matches all operating systems.

arch attribute: Specifys the architecture for which the information element should be considered. If the value is a prefix of the os.arch system property, then the information element can be used. If the attribute is not specified it matches all architectures.

platform attribute: Specifys the platform for which the information element should be considered. If the value is a prefix of the os.platform system property, then the information element can be used. If the attribute is not specified it matches all platforms.

2.) change section 3.5

from:

The JNLP Client may assume that a typical JNLP file will have at least an icon of 32x32 pixels in 256 colors of the default kind. The image file can be either GIF or JPEG format.

to:

The image file can be either GIF or JPEG format, or other (possibly platform dependent) formats. The JNLP Client may assume that a typical JNLP file will have at least an icon in GIF or JPEG format of 32x32 pixels in 256 colors of the default kind

3.) add after the information element in Appendix C :

<!ATTLIST information os CDATA #IMPLIED>

<!ATTLIST information arch CDATA #IMPLIED>

<!ATTLIST information platform CDATA #IMPLIED>

4.) in Appendix C, in the comment for the href attribute of the icon element:

Remove the sentence"The file must be in either JPEG or GIF format."

2.6) Proposed JNLP Specification change for bug 4928956.

Overview:

The JNLP Specification doesn't allow a version-id specification to contain an "and" operator. An "and" operator is necessary to specify a range of versions expected to be common (specifically, "any member of a Minor release family that is not less than a lower bound within that Minor release family"). We propose adding the binary "&" operator to provide this functionality.

Justification:

This is a requirement of the "Multiple JRE Delivery Model" project, and adds functionality not previously available in JNLP.

Proposed change to the specification:

1.) Change the last two paragraphs in section 3.4 to:

The version attribute can not only specify an exact version, as shown above, but can also specify a list of versions, called a version string. A version string is an ordered list of version-ranges separated by spaces. A version range is either a version-id, a
version-id followed by a star (*), a version-id followed by a plus sign (+) , or two version-ranges combined using an ampersand (&). The star means prefix match, the plus sign means this version or greater, and the ampersand means the logical anding of the two version-ranges. For example:

<jar href="classes/MyApp.jar" version = "1.4.0_04 1.4*&1.4.1_02+" />

The meaning of the above is: the JAR file at the given URL that either has the version-id 1.4.0_04, or has a version-id with 1.4 as a prefix, and not less than 1.4.1_02. The exact syntax and definition of version-ids and version strings is given in appendix A.

2.) Change Appendix A from:

char ::= any ASCII character except a space, a separator, or a modifier.

to:

char ::= any ASCII character except a space, an ampersand, a separator, or a modifier.

3.) Change Appendix A from:

version-string     ::= element ( " " element) *
element                ::= version-id | version-id modifier
modifier               ::= `+` | '*'

to :

version-string     ::= version-range ( " " element) *
version-range     ::= simple-range ( "&" simple-element) *
simple-range      ::= version-id | version-id modifier
modifier             ::= `+` | '*'

4.) Add to end of Appendix A:

A.4 Version Selection

If two or more available resources match the given version-string, the JNLP Client should use the one matching the earlier version-range in the version-string.
If two or more available resources match a given version-range, the JNLP Client should use the one with the highest version-id.

3.1) Proposed JNLP Specification change for bug 4390904

Single InstanceService

Overview:

The object of the SingleInstance Service is to Allow applications launched under Java Web Start to register themselves as singletons, and to be passed in new parameter sets when user attempts to launch new instances of them.

Justification:

We have had several requests for this service, including from Solomon Smith Barney.

Proposed change to the specification:

1.) Add section 7 as follows:

SingleInstanceService, which provides a set of methods for applications to register themselves as singletons, and to register listener(s) for handling arguments passed in from different instances of the application. This service is optional.

2.) Add section 7.9 as follows:

7.9 The SingleInstanceService

The javax.jnlp.SingleInstanceService provides a set of methods for applications to register themselves as singletons, and to register listener(s) for handling arguments passed in from different instances of the application. The application can register and unregister itself with the following two methods:

addSingleInstanceListener(javax.jnlp.SingleInstanceListener listener)

removeSingleInstanceListener(javax.jnlp.SingleInstanceListener listener)

The addSingleInstanceListener method adds the specified SingleInstanceListener to handle how the application should behave when another instance of the same application is invoked. If the SingleInstanceListener is null, no exception is thrown and no action is performed. Multiple listeners can be added for the application. If the same listener is added twice, no action is performed.

The removeSingleInstanceListener method removes the specified SingleInstanceListener. This method performs no function, nor does it throw an exception, if the listener specified by the argument was not previously added to the application. If listener is null, no exception is thrown and no action is performed. It is recommended that if an application registered any SingleInstanceListener(s), it should call this method to remove all listeners upon exit .

The javax.jnlp.SingleInstanceListener is the interface for the SingleInstanceListener. The application requesting SingleInstanceService should implement this interface, providing an implementation of the following method:

newActivation(String[] params)

Arguments from the instances of the application will be passed in to the newActivation method, and application developer can decide on how to handle the arguments passed in by implementating this method.

3.) Add to the table in section D.1:

SingleInstanceService javax.jnlp.SingleInstanceService no
SingleInstanceListener <not a service> n/a

4.) Add section D.16 as follows:

D.16 SingleInstanceService

public interface SingleInstanceService
public void addSingleInstanceListener(javax.jnlp.SingleInstanceListener listener);
public void removeSingleInstanceListener(javax.jnlp.SingleInstanceListener listener);

4.) Add section D.17 as follows:

D.17 SingleInstanceListener

interface javax.jnlp.SingleInstanceListener
public void newActivation(String[] params);

3.2) Proposed JNLP Specification change for bug 4467214

(also including RFE 4436034)

Extended Service

Overview:

Because several of the existing JNLP Services are missing needed API's, we propose to add a new Service, ExtendedService, containing the new api's which logically belong to the existing services. We propose the following two methods: openFile(File file), and openFiles(File[] files).

Justification:

These methods are being requested by many customers, and address problems overlooked in the original specification.

Proposed change to the specification:

1.) Add to section 7 as follows:

ExtendedService, which provide additional support to the existing APIs. This service is optional.

2.) Add section 7.10 as follows:

7.10 The ExtendedService Service

The javax.jnlp.ExtendedService provides additional support to the current JNLP API. It allows applications to open specific file(s) in the client's file system.

The application can request access to specific file(s) using the following two methods:

openFile(File file)

openFiles(File[] files)

A dialog should be presented to the user asking for permissions to access the specific file(s). The JNLP client can render the dialog in any way it sees fit.

The contents of the file(s) are returned in a FileContents object. A FileContents encapsulates the name of the selected file and provides metered access to the contents. The contents can be accessed using input streams, output streams or random access. The JNLP client might enforce size limits on the amount of data that can be written.

The methods will return null if the user choose to cancel the operation or user pass in null as argument. An IOException will be thrown if the operation failed.

3.) Add line to table in section D.1:

ExtendedService javax.jnlp.ExtendedService no

4.) Add section D.18 as follows:

D.18 ExtendedService

public interface ExtendedService
public FileContents openFile(java.io.File file) throws IOException;
public FileContents[] openFiles(java.io.File[] files) throws IOException;