content/release-doc/2.2.2/release-notes/join.html - river-site - Git at Google

 <!--
  ! 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.
  !-->
 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
 <html>
 <body text="#000000" bgcolor="#ffffff" link="#9b37cc"
       vlink="#cc1877" alink="#ffffff">


 <title>Jini Join Utilities Release Notes</title>

 <center><h1>Jini Join Utilities
   <BR>Apache River v2.2.0 Release Notes
 </h1></center>
 <HR>
 <UL>
 <H3>Description</H3>

 The class
 <a href="../api/net/jini/lookup/JoinManager.html"> <code>net.jini.lookup.JoinManager</code></a>
 is a utility class that, along with supporting interfaces and classes,
 encapsulates functionality that can help Jini technology-enabled services
 (<i>Jini services</i>) 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 (<i>joining</i>), as well as lease
 renewal and attribute management.
 <p>
 The specification for the
 <a href="../api/net/jini/lookup/JoinManager.html"> <code>JoinManager</code></a>
 utility (join manager) is contained in the  <i>Jini Join Utilities Specification</i>,
 which is available in <a href="../specs/html/joinutil-spec.html">html</a>.
 <p>
 <H3>Changes since the v2.2.0 release</H3>

 <dl>

 <dt><b>None</b></dt>

 </dl>
 <H3>Changes since the v2.1.1 release</H3>
 <li>[<a href='https://issues.apache.org/jira/browse/RIVER-25'>RIVER-25</a>] -
 Improve logging for JoinManager at INFO and WARNING level
 </li>
 <li>[<a href='https://issues.apache.org/jira/browse/RIVER-213'>RIVER-213</a>] -
 (DOC) - JoinManger has typo in javadoc (missing &lt;/code&gt; termination tag)
 </li>

 <H3>Changes since the v2.0.1 release</H3>

 <dl>
   <dt> <b>Configuration</b>
   <dd> A new configuration entry has been added to the join manager implementation
        in this release: <b>maxLeaseDuration</b>.
        <p>
        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.
        <p>
        This new configuration entry is a result of <code>RFE 6202650</code>,
        described <a href="#rfe6202650"> below</a>.
        <p>
        A full list of supported configuration entries is given in this utility's
        <a href="../api/net/jini/lookup/JoinManager.html#jmConfigEntries"> class
 documentation</a>.
        <p>

   <dt> <b>Logging</b>
   <dd> 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
        <a href="http://java.sun.com/j2se/1.4/docs/api/java/util/logging/Logger.html"> <code>Logger</code></a>
        named <code>net.jini.lookup.JoinManager</code>. For a description of the
        information that is logged, as well as the associated logging levels, refer to the
        <a href="../api/net/jini/lookup/JoinManager.html#jmLogging"> class documentation</a>.
        <p>

   <dt> <b>New Feature Enhancements</b>
   <dd> In this release, the following feature enhancements have been added to
        the join manager:
   <p>
   <dt><b>4879947: JoinManager should support changing the service proxy</b><dt>
   <dd> The <a href="../api/net/jini/lookup/JoinManager.html"> public API</a> of
 the
        join manager has been enhanced with a new method having two versions:

 <pre><code>public void replaceRegistration(Object serviceProxy) {...}
 public void replaceRegistration(Object serviceProxy, Entry[] attrSets) {...}</code></pre>

        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 <a href="../specs/html/joinutil-spec.html"> specification</a>
        of the join manager for details on the semantics of this new method.
        <p>
        All necessary modifications were made to the join manager
        implementation to comply with this change.
   </dd>
   <p>
   <dt><b>5110241: JoinManager spec change - lease from discarded LUS should be cancelled, not removed (JU.5.1)</b><dt>
   <dd> Section JU.5.1 of the join manager <a href="../specs/html/joinutil-spec.html"> specification</a>
        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.
        <p>
        All necessary modifications were made to the join manager
        implementation to comply with this change.
   </dd>
   <p>

 <a name="rfe6202650">
   <dt><b>6202650: JoinManager should allow configurable control of lease renewal interval</b><dt>
   <dd> 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.
        <p>
        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.
        <p>
        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.
        <p>
        All necessary modifications were made to the join manager
        implementation to comply with this change.
   </dd>
   <p>

   <dt> <b>Bug Fixes of Interest</b>
   <dd> 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:
   <p>

   <dt><b>5090332: Specifying WakeupManager in JoinManager configuration causes thread leak</b><dt>
   <dd> 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.
        <p>
        This bug has been fixed.
   </dd>
   <p>
   <dt><b>5103210: JoinManager has race condition when a LUS is discarded/re-discovered</b><dt>
   <dd> 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:
 <pre><code>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</code></pre>

        Because <code>DiscMgrListener.discovered()</code> tests <code>joinSet</code> for
        the lookup service before <code>DiscardProxyTask</code> removes that lookup
        service from <code>joinSet</code> (and cancels the service's lease with
        the lookup service), the <code>RegisterTask</code> is not queued and run;       thus, the service is never re-registered with the lookup service.
        <p>
        This bug has been fixed.
   </dd>
   <p>
   <dt><b>6181162: JoinManager should create default LDM only when no DiscoveryManagement is configured</b><dt>
   <dd> Prior to interrogating the configuration for a
        <a href="../api/net/jini/discovery/DiscoveryManagement.html"> <code>DiscoveryManagement</code></a>
        item (entry name = <b><i>discoveryManager</i></b>), a default
        <a href="../api/net/jini/discovery/LookupDiscoveryManager.html"> <code>LookupDiscoveryManager</code></a>
        is first created. Although that manager is initialized to discover no groups and no locators,
        the <a href="../api/net/jini/discovery/LookupDiscovery.html"> <code>LookupDiscovery</code></a>
        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 <i>discoveryManagement</i>
        item, the creation of the default lookup discovery manager -- and the threads
        that manager ultimately creates -- is unnecessary, and wastes resources.
        <p>
        This bug has been fixed.
   </dd>
   <p>
   <dt><b>6215208: JoinManager race - repeated UnknownLeaseException-Reregistration-UnknownLeaseException</b><dt>
   <dd> A race condition was discovered in which an
        <a href="../api/net/jini/core/lease/UnknownLeaseException.html"> <code>UnknownLeaseException</code></a>
        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.
        <p>
        This bug has been fixed.
   </dd>


 </dl>


 <!-- No issues for now
 <p>
 <H3>Known Issues (& Workarounds)</H3>
     Currently, there are no known issues regarding the
     <a href="../api/net/jini/lookup/JoinManager.html"> <code>JoinManager</code></a>
     utility.
 <p>
 -->

 </ul>
 <hr>
 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
 <ul>
      <a href="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</a>
 </ul>
 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.

 </body>
 </html>
	<!--
	! 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.
	!-->
	<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
	<html>
	<body text="#000000" bgcolor="#ffffff" link="#9b37cc"
	vlink="#cc1877" alink="#ffffff">


	<title>Jini Join Utilities Release Notes</title>

	<center><h1>Jini Join Utilities
	<BR>Apache River v2.2.0 Release Notes
	</h1></center>
	<HR>
	<UL>
	<H3>Description</H3>

	The class
	<a href="../api/net/jini/lookup/JoinManager.html"> <code>net.jini.lookup.JoinManager</code></a>
	is a utility class that, along with supporting interfaces and classes,
	encapsulates functionality that can help Jini technology-enabled services
	(<i>Jini services</i>) 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 (<i>joining</i>), as well as lease
	renewal and attribute management.
	<p>
	The specification for the
	<a href="../api/net/jini/lookup/JoinManager.html"> <code>JoinManager</code></a>
	utility (join manager) is contained in the <i>Jini Join Utilities Specification</i>,
	which is available in <a href="../specs/html/joinutil-spec.html">html</a>.
	<p>
	<H3>Changes since the v2.2.0 release</H3>

	<dl>

	<dt><b>None</b></dt>

	</dl>
	<H3>Changes since the v2.1.1 release</H3>
	<li>[<a href='https://issues.apache.org/jira/browse/RIVER-25'>RIVER-25</a>] -
	Improve logging for JoinManager at INFO and WARNING level
	</li>
	<li>[<a href='https://issues.apache.org/jira/browse/RIVER-213'>RIVER-213</a>] -
	(DOC) - JoinManger has typo in javadoc (missing </code> termination tag)
	</li>

	<H3>Changes since the v2.0.1 release</H3>

	<dl>
	<dt> <b>Configuration</b>
	<dd> A new configuration entry has been added to the join manager implementation
	in this release: <b>maxLeaseDuration</b>.
	<p>
	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.
	<p>
	This new configuration entry is a result of <code>RFE 6202650</code>,
	described <a href="#rfe6202650"> below</a>.
	<p>
	A full list of supported configuration entries is given in this utility's
	<a href="../api/net/jini/lookup/JoinManager.html#jmConfigEntries"> class
	documentation</a>.
	<p>

	<dt> <b>Logging</b>
	<dd> 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
	<a href="http://java.sun.com/j2se/1.4/docs/api/java/util/logging/Logger.html"> <code>Logger</code></a>
	named <code>net.jini.lookup.JoinManager</code>. For a description of the
	information that is logged, as well as the associated logging levels, refer to the
	<a href="../api/net/jini/lookup/JoinManager.html#jmLogging"> class documentation</a>.
	<p>

	<dt> <b>New Feature Enhancements</b>
	<dd> In this release, the following feature enhancements have been added to
	the join manager:
	<p>
	<dt><b>4879947: JoinManager should support changing the service proxy</b><dt>
	<dd> The <a href="../api/net/jini/lookup/JoinManager.html"> public API</a> of
	the
	join manager has been enhanced with a new method having two versions:

	<pre><code>public void replaceRegistration(Object serviceProxy) {...}
	public void replaceRegistration(Object serviceProxy, Entry[] attrSets) {...}</code></pre>

	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 <a href="../specs/html/joinutil-spec.html"> specification</a>
	of the join manager for details on the semantics of this new method.
	<p>
	All necessary modifications were made to the join manager
	implementation to comply with this change.
	</dd>
	<p>
	<dt><b>5110241: JoinManager spec change - lease from discarded LUS should be cancelled, not removed (JU.5.1)</b><dt>
	<dd> Section JU.5.1 of the join manager <a href="../specs/html/joinutil-spec.html"> specification</a>
	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.
	<p>
	All necessary modifications were made to the join manager
	implementation to comply with this change.
	</dd>
	<p>

	<a name="rfe6202650">
	<dt><b>6202650: JoinManager should allow configurable control of lease renewal interval</b><dt>
	<dd> 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.
	<p>
	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.
	<p>
	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.
	<p>
	All necessary modifications were made to the join manager
	implementation to comply with this change.
	</dd>
	<p>

	<dt> <b>Bug Fixes of Interest</b>
	<dd> 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:
	<p>

	<dt><b>5090332: Specifying WakeupManager in JoinManager configuration causes thread leak</b><dt>
	<dd> 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.
	<p>
	This bug has been fixed.
	</dd>
	<p>
	<dt><b>5103210: JoinManager has race condition when a LUS is discarded/re-discovered</b><dt>
	<dd> 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:
	<pre><code>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</code></pre>

	Because <code>DiscMgrListener.discovered()</code> tests <code>joinSet</code> for
	the lookup service before <code>DiscardProxyTask</code> removes that lookup
	service from <code>joinSet</code> (and cancels the service's lease with
	the lookup service), the <code>RegisterTask</code> is not queued and run; thus, the service is never re-registered with the lookup service.
	<p>
	This bug has been fixed.
	</dd>
	<p>
	<dt><b>6181162: JoinManager should create default LDM only when no DiscoveryManagement is configured</b><dt>
	<dd> Prior to interrogating the configuration for a
	<a href="../api/net/jini/discovery/DiscoveryManagement.html"> <code>DiscoveryManagement</code></a>
	item (entry name = <b><i>discoveryManager</i></b>), a default
	<a href="../api/net/jini/discovery/LookupDiscoveryManager.html"> <code>LookupDiscoveryManager</code></a>
	is first created. Although that manager is initialized to discover no groups and no locators,
	the <a href="../api/net/jini/discovery/LookupDiscovery.html"> <code>LookupDiscovery</code></a>
	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 <i>discoveryManagement</i>
	item, the creation of the default lookup discovery manager -- and the threads
	that manager ultimately creates -- is unnecessary, and wastes resources.
	<p>
	This bug has been fixed.
	</dd>
	<p>
	<dt><b>6215208: JoinManager race - repeated UnknownLeaseException-Reregistration-UnknownLeaseException</b><dt>
	<dd> A race condition was discovered in which an
	<a href="../api/net/jini/core/lease/UnknownLeaseException.html"> <code>UnknownLeaseException</code></a>
	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.
	<p>
	This bug has been fixed.
	</dd>


	</dl>


	<!-- No issues for now
	<p>
	<H3>Known Issues (& Workarounds)</H3>
	Currently, there are no known issues regarding the
	<a href="../api/net/jini/lookup/JoinManager.html"> <code>JoinManager</code></a>
	utility.
	<p>
	-->

	</ul>
	<hr>
	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
	<ul>
	<a href="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</a>
	</ul>
	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.

	</body>
	</html>