SAS AppDev Studio 3.0 Developer's Site

JSASNetCopy Administration

Overview

JSASNetCopy provides automatic client-side installation of Java libraries. JSASNetCopy decides what to download and install based on information read from configuration files on the Web server. This document describes JSASNetCopy configuration files. For information on how to deploy JSASNetCopy files and applet files on a Web server, see Deploying with JSASNetCopy.

Background

JSASNetCopy consists of the following files:

JSASNetCopyApplet.jar — this small jar contains a proxy applet which serves as a placeholder for the target applet and is responsible for starting JSASNetCopy.
JSASNetCopy.jar — the bulk of the JSASNetCopy code. Activated by running the proxy applet, this JSASNetCopy code uses information in configuration files to download and install libraries on the client machine.
JSASNetCopyConfig.txt — the master configuration file. Lists the files (and their versions and URLs) which should be installed on the client machine. The code in JSASNetCopy.jar compares this list to what it can find on the client machine to decide whether any files need to be downloaded.

Additionally, the jars referenced by the configuration file should be available on a Web server.

Customizing What JSASNetCopy Downloads

Included with AppDev Studio is an Ant script (located at <ADS install>/Java/JSASNetCopy/build.xml) which updates the webapp/JSASNetCopyConfig.txt and JSASNetCopy.war files under <ADS install>/Java/JSASNetCopy/. When running WebAF, the Update JSASNetCopy .war item on the Tools menu is an easy way to run this Ant script.

The Ant script constructs the configuration file by examining the contents of the jars and jars203 sub-directories under <ADS install>/Java/JSASNetCopy/webapp/. Adding or removing jars from the jars directory and then using the Update JSASNetCopy .war command, is an easy way to customize JSASNetCopy's download list. You will still need to [re-]deploy the updated files (see Deploying with JSASNetCopy).

The jars203 directory contains the AppDev Studio 2.0.3 runtime jars to allow JSASNetCopy to run older AppDev Studio applets in Java 1.3 or Java 1.4 without needing to convert and re-deploy each applet using AppDev Studio 3.0.

The remainder of this document describes the format of JSASNetCopy configuration files for those who might want to edit them manually.

Configuration Files

By default, JSASNetCopy configuration files are named "JSASNetCopyConfig.txt" and list jars which should be made available to applets on the client machine. When JSASNetCopy is run, it compares the library names and version numbers listed in the configuration file with what is installed on the client machine, downloading any newer or missing entries. For this reason, the configruation file should be updated with new version number information whenever the jars it lists are updated.

Configuration files are similar in format to jar manifests or properties files, but without line-length limits or line-wrapping. They are text files separated into sections by blank lines. Like jar manifests, the first section in the file is reserved for general information that applies to the entire configuration file. All other sections represent jars, one per section. Effectively, each section represents a request to make a particular jar available to applets which JSASNetCopy launches.

Sample Configuration Data

A sample portion of a configuration file might look like this:

....

name=sas.ads.misc.jar
Specification-Version=3.1.0.0+
Implementation-Vendor-Id=com.sas
Implementation-Version=3.1.0.0.20030306.3142+
source=jars/sas.ads.misc.jar
java-version=1.4+

# we always need sas.core.jar
name=sas.core.jar
Specification-Version=3.1.0.0+
Implementation-Vendor-Id=com.sas
Implementation-Version=3.1.0.0.20030306.528+
source=jars/sas.core.jar
java-version=1.4+

....

The sample shows two sections for downloading sas.ads.misc.jar and sas.core.jar to the client machine. Lines beginning with # are comments and may appear anywhere. Non-comment lines follow a key=value pattern. While the order of lines in a section is unimportant, each jar section (jar request) must specify a jar name.

Keys and Values

In each jar request, there are potentially several keys which are processed as version strings. JSASNetCopy parses version strings as defined by the Java Network Launching Protocol (Appendix A) with the following extensions:

Version id pieces are compared numerically if they can be parsed as Java longs (rather than Java ints). Note that future versions of JSASNetCopy may elect to use numeric comparisons even when the numeric values exceed the capacity of a Java long.
A concept of ranges is introduced:
Range a..b, where a and b are version ids, is defined to match any version id x where a < x < b. Note that range a..b does not match either a or b. Additionally, open-ended ranges are possible. Range ..a matches all x such that x < a, and range a.. matches all x such that a < x. However, .. is not a legal range.
Unlike Java Web Start, the order of version ids within a version string does not matter.

The following keys are recognized by JSASNetCopy:

Key	Description
`name`	The file name of a class library (jar). If necessary, JSASNetCopy will download it from the source URL. Note that the jar file name does not need to match the filename portion of the source URL.
`source`	Download URL for the named jar. Relative URLs are interpreted as being relative to the location of the configuration file.
`java-version`	A version string indicating which Java VM versions a jar request applies to. JSASNetCopy ignores jar requests with a value for `java-version` which does not match the current Java VM version. If a request does not specify a `java-version` version string, an implicit value of `1.2 1.2..1.4` is used (1.2 ≤ java version < 1.4).
Identifying information for versioned jars. These keys correspond to jar manifest attributes defined by the Optional Package Versioning specification.
`Specification-Version`	A version string indicating acceptable specification versions for the jar. If this key is not defined, all specification versions are acceptable.
`Implementation-Vendor-Id`	If defined, the `Implementation-Vendor-Id` value a jar's manifest must have
`Implementation-Version`	A version string indicating acceptable implementation versions for the jar. If this key is not defined, all implementation versions are acceptable.
Identifying information for unversioned jars
`crc32`	32-bit CRC value for the jar file, as calculated by the `java.util.zip.CRC32` class
`size`	Jar file size in bytes
Obsolete keys used only by older versions of JSASNetCopy
`version`	Version number of the target jar. Roughly corresponds to the `Implementation-Version`, but the value of `Specification-Version` would be used if `Implementation-Version` was not defined. Somewhat ambiguous, as the specification and implementation versions are not necessarily related.
`replaceVersions`	An space-separated list of jar version numbers which would always (without additional comparison) be considered inferior to the jar version available at the source URL. Replaced by the more flexible version strings specification.
`obsolete`	Indicated that a jar name was discontinued or renamed and should be "upgraded" to an empty jar with the specified version information. Only used with AppDev Studio 3.0EA. This was necessary because older versions of JSASNetCopy downloaded jars to the extensions directory (see Optional Package Versioning). All jars in the extensions directory are visible to applets. This caused problems whenever jars were renamed because both the original and renamed versions of a jar might be visible to an applet. This is no longer an issue because JSASNetCopy No longer downloads jars (other than itself) to the extensions directory Supports installing and selecting between multiple versions of the same jar Makes specific [versions of] jars available to an applet, rather than blindly offering all available downloaded content

For each request, JSASNetCopy attempts to use the latest version of the jar which will still match the request. If more than one jar on the client machine matches, JSASNetCopy will use versioned jars (considering highest matching Specification-Version, then Implementation-Vendor-Id, then highest matching Implementation-Version) before using unversioned jars.

If a jar request contains any versioning identifiers (Specification-Version, Implementation-Vendor-Id or Implementation-Version) it must specify them all, and JSASNetCopy will ignore the request's unversioned identifiers (crc32 and/or size). If none of the versioning identifiers are specified and one or more unversioned identifiers are specified, JSASNetCopy will match the request using the unversioned identifiers. If no identifiers are specified in the request, JSASNetCopy will match the request using only the jar name.

E-mail This Page

FOCUS AREAS

Developer Resources

Products

Technologies

API Reference