# Jini(TM) Technology Starter Kit
Compatibility with v1.2.1

The Jini(TM) Technology Starter Kit v2.0x implementation (referred to in this document as v2.0) introduces significant new and changed functionality relative to the Jini Technology Starter Kit v1.2.1 (referred to in this document as v1.2.1). V2.0 also relies on features only provided by Java(TM) 2 platform, Standard Edition (J2SE(TM)) v1.4 and higher. The following is a summary of the changes which might impact an existing v1.2.1-based implementation.

Service deployment has changed significantly in v2.0. There have been numerous changes in the way services are configured and run:

- A different command line syntax is required for starting services.
- Most system properties affecting the behavior of Jini components have been replaced with configuration entries.
- Programmatic startup classes have changed.
- The minimum permissions required to run services have generally changed.
- The persistent storage format has changed.
- Some Admin methods and/or interfaces have been renamed or removed.

J2SE 1.4.1_02 or higher is required by all applications using v2.0 classes, including all clients of our v2.0 services. This is necessary to support the new class file version (48.0) generated by the J2SE 1.4.1_02 compiler which was used to build v2.0. It is also required to support the new APIs and features, provided by J2SE 1.4.1_02, that v2.0 relies on, such as classes in the `java.util.logging` package.

V2.0 services were packaged assuming that `jsk-platform.jar` would be included in the clients classpath. It is unlikely that `jsk-platform.jar` could be made downloadable without granting extraordinary permissions to the service proxy.

V2.0 provides upward compatible `net.jini` APIs:

- Only constructor additions were made to existing `net.jini` classes.
- It should be possible to use v2.0 `net.jini` classes without recompiling existing code. However, there are deployment changes to consider as well:
  - System properties have generally been replaced with configuration entries.
  - The v2.0 `ServiceDiscoveryManager` remote event listener defaults to exporting with Jini extensible remote invocation (Jini ERI) rather than JRMP. To be compatible, a v1.2.1 lookup service must run on J2SE 1.4.1_02 or higher and have `jsk-platform.jar` in its classpath.

Incompatible changes have been made to some `com.sun.jini` classes.

- `com.sun.jini.fiddler.FiddlerAdmin`
  - No longer extends `StorageLocationAdmin`
  - `getDebugProperty` and `setDebugProperty` methods were removed.
  - `getSnapshotWeight`, `setSnapshotWeight`, `getLogToSnapshotThreshold`, `setLogToSnapshotThreshold`, `getLeaseDurationBound`, `setLeaseDurationBound` methods were renamed.
- `com.sun.jini.lease.AbstractLeaseMap` is no longer serializable.
- `com.sun.jini.lease.BasicRenewalFailureEvent` constructor parameters and serialized fields changed from `MarshalledObject` to `MarshalledInstance`.
- `com.sun.jini.mercury.MailboxAdmin` no longer extends `StorageLocationAdmin`.
- `com.sun.jini.start` package has changed completely.
- `com.sun.jini.thread.RetryTask` 1-arg constructor has been removed.

Some `com.sun.jini` classes have been removed:

- `com.sun.jini.debug.Debug` functionality has been replaced with loggers from the `java.util.logging` package.
- `com.sun.jini.thread.ThreadDebug` functionality has been replaced with loggers from the `java.util.logging` package.
- the `com.sun.jini.lease.landlord` package has been replaced by `com.sun.jini.landlord`.
- `com.sun.jini.reggie.RegistrarAdmin` has been eliminated; equivalent functionality is provided through configuration entries.
- `com.sun.jini.norm.NormAdmin` has been eliminated; equivalent functionality is provided through configuration entries.
- `com.sun.jini.proxy.UUID` has been replaced by `net.jini.id.Uuid`.
- `com.sun.jini.proxy.UUIDFactory` has been replaced by `net.jini.id.UuidFactory`.

V1.2.1-based applications or services running on a J2SE version earlier than J2SE 1.4 are not compatible with v2.0 services. However, compatibility can be achieved by running the v1.2.1 implementation on J2SE 1.4.1_02 or later, and properly configuring the v2.0 services. The following section provides the configuration information needed to achieve compatibility between combinations of clients, services, and lookup services.

In the table below, each row has only two of the first three columns filled. When the client and service columns are filled, the client gets the proxy from service and performs some operation. When the client and lookup columns are filled, the client discovers the lookup service and performs a lookup operation. When the service and lookup columns are filled, the service discovers the lookup service and registers itself.

### Legend

- 1.2 - v1.2.1_01 component running on J2SE 1.2.2 or higher without classpath modifications
- 1.2modified - v1.2.1_01 component running on J2SE 1.4.1_02 or higher with `jsk-platform.jar` added to the classpath or correct classloader (as required to preserve correct codebase annotation of classes that are in both client/service/lookup codebase and `jsk-platform.jar`). In some cases, it may also be necessary to define the system property `-Djava.rmi.server.RMIClassLoaderSpi=default` to force the use of the default provider rather than the preferred class provider.
- 2.0 - v2.0 component built with version 48.0 class files running on J2SE 1.4.1_02 or higher with `jsk-platform.jar` added to the classpath.

- White row - indicates configurations where `jsk-platform.jar` is installed only in v2.0 components.
- Grey row - indicates configurations where `jsk-platform.jar` is installed everywhere.

Client | Service | Lookup | Compatibility Comments
--- | --- | --- | ---
1.2 | 2.0 |  | Incompatible because: `UnsupportedClassVersionError` will be thrown by the client if the client does not use J2SE 1.4. `NoClassDefFoundError` will be thrown by the client because the service's proxy has `jsk-platform.jar` dependencies that it expects to have available in the client.
2.0 | 1.2 |  | Compatible if one of the following is true: No code is downloaded into the service. Code is downloaded into the service AND all required code is in the client's codebase (with no dependence on `jsk-platform.jar`) AND service uses J2SE 1.4. Code is downloaded into the service AND all required code is in the client's codebase (with no dependence on `jsk-platform.jar`) AND client uses JRMP stubs only.
1.2 |  | 2.0 | Incompatible because: `UnsupportedClassVersionError` will be thrown by the client if the client does not use J2SE 1.4. `NoClassDefFoundError` will be thrown by v1.2 discovery utilities (and possibly other utilities) that are not resilient to errors.
2.0 |  | 1.2 | Compatible if one of the following is true: Event notification isn't used. Theclient uses JRMP remote event listener for event notification.
| 1.2 | 2.0 | Incompatible because: `UnsupportedClassVersionError` will be thrown by the service if the service does not use J2SE 1.4. `NoClassDefFoundError` will be thrown by v1.2 discovery utilities (and possibly other utilities) that are not resilient to errors.
| 2.0 | 1.2 | Compatible if one of the following is true: Event notification isn't used. The service uses JRMP remote event listener for event notification. except for one special case. If a v2.0 implementation of reggie is configured to discover and register with other lookup services, it will fail to discover a v1.2 implementation of reggie.
1.2modified | 2.0 |  | Compatible if the service does not the require the client to authenticate and one of the following is true: The client does not pass a `Remote` object to the service. The client explicitly passes the stubs of `Remote` objects to the service, or the `Remote` object implementation includes a `writeReplace` method that returns the object's stub. The client passes a reference to an exported `Remote` object implementation or an object containing such a reference and the service is exported with JRMP.
2.0 | 1.2modified |  | Compatible if the following is true: The client does not require the service to implement `RemoteMethodControl`.
1.2modified |  | 2.0 | Compatible if lookup does not require the client to authenticate and one of the following is true: The client does not pass a `RemoteEventListener` to the LUS. The client explicitly passes the stub of a `RemoteEventListener` to the LUS, or the `RemoteEventListener` implementation includes a `writeReplace` method that returns the stub. The client passes a `RemoteEventListener` implementation to the LUS and the LUS is exported with JRMP.
2.0 |  | 1.2modified | Compatible if the following is true: The client does not require the service to implement `RemoteMethodControl`.
| 1.2modified | 2.0 | Compatible if the lookup does not require the service to authenticate and one of the following is true: The service does not use a smart proxy and either: Explicitly passes the `Remote` stub to the `JoinManager` or the LUS register method. Defines the system property `com.sun.jini.reggie.enableImplToStubReplacement=true` in the service virtual machine. The service uses a smart proxy that explicitly references the stub of its underlying `Remote` object, or the underlying `Remote` object implementation includes a `writeReplace` method which returns the stub. The service uses a smart proxy and the LUS is exported with JRMP. In all cases, if a `Remote` object is used as an entry field for a service attribute, then the stub must be used as the value of that field, or the `Remote` object must implement a `writeReplace` method that returns the stub.
| 2.0 | 1.2modified | Compatible if the following is true: The client does not require the service to implement `RemoteMethodControl`. except for one special case. If a v2.0 implementation of reggie is configured to discover and register with other lookup services, it will fail to discover a v1.2 implementation of reggie.

Copyright 2004 Sun Microsystems, Inc. All Rights Reserved.