# Jini Join Utilities
Apache River v3.0.0 Release Notes

### Description

The class `net.jini.lookup.JoinManager` is a utility class that, along with supporting interfaces and classes, encapsulates functionality that can help Jini technology-enabled services (Jini services) demonstrate good behavior in their discovery- and registration-related interactions with Jini lookup services. In particular, this utility performs functions related to lookup service discovery and registration (joining), as well as lease renewal and attribute management.

The specification for the `JoinManager` utility (join manager) is contained in the Jini Join Utilities Specification, which is available in html.

### Changes since the v2.2.0 release

None

### Changes since the v2.1.1 release

- [RIVER-25] - Improve logging for JoinManager at INFO and WARNING level
- [RIVER-213] - (DOC) - JoinManger has typo in javadoc (missing </code> termination tag)

### Changes since the v2.0.1 release

Configuration
  A new configuration entry has been added to the join manager implementation in this release: maxLeaseDuration.

  This new entry allows one to configure the maximum lease duration (in milliseconds) that is requested from each discovered lookup service on behalf of the service; both when the lease is initially requested, as well as when renewal of that lease is requested. Thus, as this value is made smaller, renewal requests will be made more frequently while the service is up, and lease expiration will occur sooner when the service goes down.

  This new configuration entry is a result of `RFE 6202650`, described below.

  A full list of supported configuration entries is given in this utility's class documentation.

Logging
  In this release, no changes have occurred with respect to the logging mechanism employed by the join manager implementation; which logs diagnostic information to the `Logger` named `net.jini.lookup.JoinManager`. For a description of the information that is logged, as well as the associated logging levels, refer to the class documentation.

New Feature Enhancements
  In this release, the following feature enhancements have been added to the join manager:

4879947: JoinManager should support changing the service proxy
  The public API of the join manager has been enhanced with a new method having two versions:

      public void replaceRegistration(Object serviceProxy) {...}
      public void replaceRegistration(Object serviceProxy, Entry[] attrSets) {...}

  Using either version of this new method, one can register a new reference to the service (optionally, with new attributes) which was previously registered, by the join manager, with all discovered lookup services. Refer to the specification of the join manager for details on the semantics of this new method.

  All necessary modifications were made to the join manager implementation to comply with this change.

5110241: JoinManager spec change - lease from discarded LUS should be cancelled, not removed (JU.5.1)
  Section JU.5.1 of the join manager specification states that when a lookup service has been discarded, the lease granted by that lookup service should be removed -- but not cancelled -- from the lease renewal manager, and the lease should be allowed to expire. That section of the spec was changed to require that the lease be ultimately cancelled rather than removed.

  All necessary modifications were made to the join manager implementation to comply with this change.

6202650: JoinManager should allow configurable control of lease renewal interval
  When a service employs a join manager to manage the service's join state, the join manager registers the service with lookup services and then manages the leases associated with each registration using a lease renewal manager. The lease renewal manager used by the join manager is either created by the join manager or supplied by the service itself.

  After registering the service with a lookup service, the join manager passes the resulting lease to the lease renewal manager, requesting that the lease be renewed at regular intervals based on the lease duration ultimately granted by the lookup service. This means that when the service goes down and the lease renewal manager is no longer available to renew the service's lease, the lookup service will not notify interested parties that the service is down until that lease duration has actually passed. Thus, the timeliness of such notifications is directly related to the maximum lease duration granted by the particular lookup service implementation with which the service was registered. If the developer of a system desires more timely notification of a service's demise, the developer either has to configure/administer the lookup service to grant shorter leases, or subclass the lease renewal manager supplied to the join manager.

  Although the lease renewal manager provides the ability for the user of the lease renewal manager to control the lease duration requested, and thus the length of the renewal interval, until now, the join manager did not provide the service with access to this functionality. Over the years, a number of users have asked for this capability. This feature enhancement is intended to satisfy that request.

  All necessary modifications were made to the join manager implementation to comply with this change.

Bug Fixes of Interest
  A number of bugs have been addressed in this release of the join manager. What follows is a description of those bugs that might be of interest:

5090332: Specifying WakeupManager in JoinManager configuration causes thread leak
  Specifying a wakeup manager in the join manager configuration causes an extra thread to be created and never destroyed for every new join manager that is created.

  This bug has been fixed.

5103210: JoinManager has race condition when a LUS is discarded/re-discovered
  If a previously discovered lookup service is discarded from the discovery manager being used by the join manager, there is a race condition in the join manager that can result in the service not re-registering with the lookup service when it is re-discovered. To understand how this race can occur, consider the following sequence:

      discard lookup service --> DiscMgrListener.discarded()
      removeTasks
      queue DiscardProxyTask

      re-discover lookup service --> DiscMgrListener.discovered()
      if(!joinSet.contains(lookup service)) --> add lookup service to joinSet
                                            --> queue RegisterTask
      DiscardProxyTask runs
      remove lookup service from joinSet
      cancel service's lease with the discarded lookup service

  Because `DiscMgrListener.discovered()` tests `joinSet` for the lookup service before `DiscardProxyTask` removes that lookup service from `joinSet` (and cancels the service's lease with the lookup service), the `RegisterTask` is not queued and run; thus, the service is never re-registered with the lookup service.

  This bug has been fixed.

6181162: JoinManager should create default LDM only when no DiscoveryManagement is configured
  Prior to interrogating the configuration for a `DiscoveryManagement` item (entry name = discoveryManager), a default `LookupDiscoveryManager` is first created. Although that manager is initialized to discover no groups and no locators, the `LookupDiscovery` instance used by the default discovery manager to perform group discovery creates a thread to listen for and process multicast announcements, as well as additional, related threads. Thus, if a deployer configures a discoveryManagement item, the creation of the default lookup discovery manager -- and the threads that manager ultimately creates -- is unnecessary, and wastes resources.

  This bug has been fixed.

6215208: JoinManager race - repeated UnknownLeaseException-Reregistration-UnknownLeaseException
  A race condition was discovered in which an `UnknownLeaseException` followed by a re-registration can repeatedly occur. This condition is intitiated by a discard of the lookup service coincident with a service lease expiration.

  This bug has been fixed.

Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.