#
Jini(TM) Technology Starter Kit
v2.0_002 Release Notes

These release notes are organized as follows:

- What's new in v2.0?
- Bugs fixed in v2.0_002
- Changes since the v1.2.x release
- Platform dependencies
- Compatibility with v1.2.1
- JAR file structure
  - Platform JAR files
  - Service Starter JAR files
  - Service JAR files
  - Activation JAR files
  - Tools JAR files
  - Other JAR files
- Note on the API documentation

If you have comments on the Jini(TM) Technology Starter Kit ("starter kit"), you can send email to `jini-comments@java.sun.com`. If you would like to submit a bug against the starter kit, please use the Bug Parade. If you encounter problems that you would like help with, you can subscribe to the `jini-users` list by sending email to `listserv@java.sun.com`, with a message of the form: `subscribe jini-users`.

If you find a class, interface, or method that is particularly useful and you would like to see it included or enhanced in future releases, please send your suggestions to `jini-comments@java.sun.com`.

## Changes since the v1.2.x release

### Services

- Reggie
- Mahalo
- Norm
- Mercury
- Fiddler
- Outrigger

### Utilities

- Discovery Utilities
- Join Utilities
- Landlord Utilities
- Lease Utilities
- Service Discovery Utilities

### Tools

- ServiceBrowser
- `ClassDep`
- `ClassServer`
- `ServiceStarter`

## Platform dependencies

This release depends on new features included in version 1.4 of the Java(TM) 2 Platform, Standard Edition. You should not expect to be able to use the source code or JAR files from this release with earlier versions of the Java platform. This requirement also extends to clients that dynamically download code from the services provided in this release.

## Platform JAR files

In this release we have extended our platform requirements to be more than just the Java 2 Platform, Standard Edition.

`jsk-policy.jar`
  This JAR file contains a security policy provider, `DynamicPolicyProvider`, that supports dynamic granting of permissions at run time. Although use of this policy provider is not required, its use is highly recommended when deploying secure applications and services. To permit effective use of this policy provider, it must first be installed as an extension in the Java 2 SDK (or JRE) that you will be using, as described in the installation instructions. This is the only JAR file that we recommend installing as an extension.

  To use this provider, you need to define a security property (not a system property):

      policy.provider=net.jini.security.policy.DynamicPolicyProvider

  in some file (for example, named `security.properties`) and then define a system property:

      -Djava.security.properties=path-to-file/security.properties

  when running your application. If you are using a Java 2 SDK (or JRE) from a vendor other than Sun, you may also need to set a security property:

      net.jini.security.policy.PolicyFileProvider.basePolicyClass=provider-class

  in the same `security.properties` file, where provider-class is the vendor's default policy provider class, which typically can be found as the value of the `policy.provider` security property in the `jre/lib/security/java.security` file of the Java 2 SDK installation.

`jsk-platform.jar`
  This JAR file contains classes and interfaces that we have chosen to include in all of our applications, and have also chosen to assume are available in all other applications that receive objects from our applications. This JAR file primarily contains classes and interfaces that are typically referenced in:
  - service provider resources to control the configuration of `RMIClassLoader`, `TrustVerifier`, `IntegrityVerifier`, `ServerContext`, and `DiscoveryFormatProvider` providers
  - `ConfigurationFile` source files, but which are unlikely to be referenced directly by the applications and services being configured (in particular, classes for creating `Exporter` and `ProxyPreparer` instances and their components)
  - dynamically downloaded code, but which we believe are not themselves reasonable to download (in particular, because they are needed to bootstrap proxy trust verification, or because their implementations require extraordinary permissions)
  plus all of the classes and interfaces that their implementations directly or indirectly depend on.

  This JAR file contains all of the classes and interfaces in the following namespaces (including all subpackages):

  - `net.jini.activation`
  - `net.jini.config`
  - `net.jini.constraint`
  - `net.jini.core`
  - `net.jini.export`
  - `net.jini.id`
  - `net.jini.iiop`
  - `net.jini.io`
  - `net.jini.jeri`
  - `net.jini.jrmp`
  - `net.jini.loader`
  - `net.jini.security`
  - `net.jini.url`
  - `com.sun.jini.discovery`
  plus the following classes:
  - `ConstrainableLookupLocatorTrustVerifier`
  - `KeyStores`
  - `ConfigUtil`
  - `LogManager`
  Any other classes or interfaces found in this JAR file should be considered implementation details.

  This JAR file includes a protocol handler for HTTPMD URLs. To enable this handler, you need to specify the system property:

      -Djava.protocol.handler.pkgs=net.jini.url

  in any application that creates or receives such URLs. In particular, any service that uses an HTTPMD URL in its codebase, and any client that wants to download code from such a service, should set this system property.

  It is important to understand that the contents of this JAR file do not constitute a "standard" platform; this JAR file is simply our choice of a platform likely to be useful for deployments of this starter kit. Depending on your deployment requirements, you may want to alter the contents of this JAR file (but if you do so, you also might have to make changes to other JAR files).

`jsk-resources.jar`
  This JAR file is referenced in the `Class-Path` manifest attribute of `jsk-platform.jar`, and configures the following specific service providers to be used:
  - `RMIClassLoader` provider:
    - `PreferredClassProvider`
  - `TrustVerifier` providers:
    - `ConstraintTrustVerifier`
    - `BasicJeriTrustVerifier`
    - `SslTrustVerifier`
    - `KerberosTrustVerifier`
    - `ProxyTrustVerifier`
    - `ConstrainableLookupLocatorTrustVerifier`
    - `DiscoveryConstraintTrustVerifier`
  - `IntegrityVerifier` providers:
    - `HttpmdIntegrityVerifier`
    - `HttpsIntegrityVerifier`
    - `FileIntegrityVerifier`
  - `ServerContext` providers:
    - `JrmpServerContext`
  - `DiscoveryFormatProvider`s for the following discovery formats:
    - `net.jini.discovery.plaintext`
    - `net.jini.discovery.ssl`
    - `net.jini.discovery.kerberos`
    - `net.jini.discovery.x500.SHA1withDSA`
    - `net.jini.discovery.x500.SHA1withRSA`
  Depending on your deployment requirements, you may want to alter the contents of this JAR file to use different sets of providers.

## Service Starter JAR files

All of our services are designed to be run under the Service Starter.

`start.jar`
  This executable JAR file is the primary entry point for the Service Starter. It acts as both the class path for the container virtual machine (VM) for the Java platform that executes non-activatable services, and as the setup VM for activatable services. It has a `Class-Path` manifest attribute that references `jsk-platform.jar`.

`sharedvm.jar`
  This JAR file is used as the class path for the activation group VM (the container VM for activatable services). It has a `Class-Path` manifest attribute that references both `jsk-platform.jar` and `phoenix-init.jar`.

`destroy.jar`
  This executable JAR file can be used to destroy an existing activation group and all of the activatable services registered in that group.

`group.jar`
  This JAR file contains the implementation of an activatable service used to destroy an existing activation group. It is typically used as the class path in a `SharedActivatableServiceDescriptor` in a configuration file passed to `destroy.jar`.

`group-dl.jar`
  The codebase JAR file for `group.jar`, used in the same service descriptor as above for `group.jar`.

## Service JAR files

There are two primary JAR files for each service, a service JAR file with a name of the form `service.jar`, and a codebase JAR file with a name of the form `service-dl.jar`. The service JAR file contains the service implementation itself, and can be thought of as the class path for the service. The service JAR file generally contains three versions of the service: a transient (non-activatable, non-persistent) version; a non-activatable, persistent version; and an activatable, persistent version. In this release, Mahalo and Mercury do not yet provide transient versions. The service JAR file is designed to be run under the Service Starter, and as such is not directly executable. The codebase JAR file is used as the codebase annotation for the service; it contains classes and interfaces that are used by the service's proxies and trust verifiers, and that clients need to dynamically download. The codebase JAR file also contains a preferred list for use by clients that have the `PreferredClassProvider` enabled. Neither the service JAR file nor the codebase JAR file include any of the classes or interfaces found in `jsk-platform.jar`: the Service Starter container (either `start.jar` or `sharedvm.jar`) provides these classes for the service implementation, and clients are expected to have `jsk-platform.jar` in their class path.

`fiddler.jar`
  The service JAR file for the Fiddler implementation of the lookup discovery service.

`fiddler-dl.jar`
  The codebase JAR file for Fiddler.

`mahalo.jar`
  The service JAR file for the Mahalo implementation of the transaction manager service.

`mahalo-dl.jar`
  The codebase JAR file for Mahalo.

`mercury.jar`
  The service JAR file for the Mercury implementation of the event mailbox service.

`mercury-dl.jar`
  The codebase JAR file for Mercury.

`norm.jar`
  The service JAR file for the Norm implementation of the lease renewal service.

`norm-dl.jar`
  The codebase JAR file for Norm.

`outrigger.jar`
  The service JAR file for the Outrigger implementation of the JavaSpaces(TM) service.

`outrigger-dl.jar`
  The codebase JAR file for Outrigger.

`reggie.jar`
  The service JAR file for the Reggie implementation of the lookup service.

`reggie-dl.jar`
  The codebase JAR file for Reggie.

## Activation JAR files

This release contains a configurable RMI activation system daemon implementation named Phoenix that we recommend using instead of `rmid` when deploying activatable versions of services.

`phoenix.jar`
  This executable JAR file is used to run Phoenix.

`phoenix-dl.jar`
  The codebase JAR file for Phoenix. Unlike `rmid`, Phoenix requires clients to dynamically download code.

`phoenix-init.jar`
  This JAR file (or its contents) must be included in the class path of any activation group VM that is created by Phoenix to run activatable objects.

`phoenix-group.jar`
  This JAR file contains the default `ActivationGroup` implementation for Phoenix. Normally it is not referenced explicitly, but is instead loaded automatically from the same directory as `phoenix.jar`.

## Tools JAR files

`tools.jar`
  This JAR file contains tools for: checking configuration files; checking for missing `serialVersionUID` fields; computing class dependencies; providing HTTP service; generating message digests; generating HTTPMD URLs; and generating wrapper JAR files. When used as an executable JAR file, it runs the ClassServer.

`browser.jar`
  This executable JAR file is used to run the example Service Browser.

`browser-dl.jar`
  The codebase JAR file for the Service Browser.

## Other JAR files

`jini-core.jar`
  This JAR file contains all of the classes and interfaces in the `net.jini.core` namespace. No direct use of this JAR file is made in this release; it is simply provided as a possible convenience to developers.

`jini-ext.jar`
  This JAR file contains all of the classes and interfaces in the `net.jini` namespace, plus all of the classes and interfaces that their implementations directly or indirectly depend on, including service providers in the `com.sun` namespace that might want to be configured in resources. The classes and interfaces in the `net.jini.core` namespace are not included directly; instead this JAR file has a `Class-Path` manifest attribute that refers to `jini-core.jar`. Note that the `Class-Path` manifest attribute does not refer to `jsk-resources.jar`, so no service providers are configured by default when using this JAR file at runtime. Any classes or interfaces in the `com.sun` namespace that appear in this JAR file should be considered implementation details. No direct use of this JAR file is made in this release; it is simply provided as a possible convenience to developers.

`outrigger-logstore.jar`
  A secondary JAR file referenced by the `Class-Path` manifest attribute of `outrigger.jar`, containing classes for the default storage implementation used by the persistent versions of Outrigger. In practice you should not need to refer directly to this JAR file.

`prebuilt-outrigger-logstore.jar`
  A secondary JAR file containing specially postprocessed classes in `outrigger-logstore.jar`. This JAR file is never used a runtime, it is only used if you attempt to rebuild the starter kit from sources and do not have the necessary ObjectStore PSE Pro for Java postprocessor tool. In practice you should not need to refer directly to this JAR file.

`pro.zip`
  A secondary JAR file referenced by the `Class-Path` manifest attribute of `outrigger-logstore.jar`, containing the ObjectStore PSE Pro for Java classes used by the default storage implementation of the persistent versions of Outrigger. In practice you should not need to refer directly to this JAR file.

`sdm-dl.jar`
  This JAR file contains proxy and trust verifier classes that generally need to be included in the codebase of any application that uses the implementation of the `ServiceDiscoveryManager` provided in this release.

`sun-util.jar`
  This JAR file contains various classes and interfaces in the `com.sun.jini` namespace that developers might want to reference. Of particular interest are the non-standard administrative interfaces implemented by our services, as well as the interfaces needed by services that want to run under the Service Starter. We make no claims about the API stability of these classes and interfaces. No direct use of this JAR file is made in this release; it is simply provided as a possible convenience to developers.

## Note on the API documentation

The on-line API documentation (generated by the Javadoc(TM) tool) provided in this release does not include every class and interface in the `com.sun.jini` packages. This omission was intentional; we only produced on-line API documentation for the classes and interfaces that we think might be important or useful to you. However, almost all of our classes and interfaces have documentation comments, so if you wish, you can produce API documentation for them yourself. Please let us know how you feel about this documentation approach by sending email to `jini-comments@java.sun.com`, with the subject: API documentation.

## Additional resources

Please visit jini.org to explore the many resources provided by the Jini Community(SM).

Copyright 2004 Sun Microsystems, Inc. All Rights Reserved.