You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@river.apache.org by th...@apache.org on 2010/01/05 18:12:27 UTC
svn commit: r896131 [3/6] - in /incubator/river/jtsk/trunk/doc: ./
release-notes/ specs/html/
Modified: incubator/river/jtsk/trunk/doc/specs/html/jini-spec.html
URL: http://svn.apache.org/viewvc/incubator/river/jtsk/trunk/doc/specs/html/jini-spec.html?rev=896131&r1=896130&r2=896131&view=diff
==============================================================================
--- incubator/river/jtsk/trunk/doc/specs/html/jini-spec.html (original)
+++ incubator/river/jtsk/trunk/doc/specs/html/jini-spec.html Tue Jan 5 17:12:26 2010
@@ -22,7 +22,7 @@
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<meta name="GENERATOR" content="Quadralay WebWorks Publisher 5.0.4">
<link rel="StyleSheet" href="standard.css" type="text/css" media="screen">
-<title>Jini Architecture Specification</title>
+<title>River Architecture Specification</title>
</head>
<body bgcolor="#ffffff">
@@ -31,7 +31,7 @@
<table width="90%">
<tr>
<td align=left><a href="../../spec-index.html">Spec Index</a></td>
-<td align=right><i>Jini Architecture Specification</i></td>
+<td align=right><i>River Architecture Specification</i></td>
</tr>
</table>
<a name="skip"></a>
@@ -46,29 +46,29 @@
</table>
<blockquote>
<h2>
- <a name="1031394"> </a>AR - Jini<font size="-1"><sup>TM</sup></font> Architecture Specification</h2>
+ <a name="1031394"> </a>AR - River Architecture Specification</h2>
<h2 class="Heading2">
<a name="1029470"> </a>AR.1 Introduction
</h2>
<p class="Body">
-This document describes the high-level architecture of system of Jini<font size="-1"><sup>TM</sup></font> technology-enabled services and/or devices (Jini system), defines the different components that make up the system, characterizes the use of those components, discusses some of the component interactions, and gives an example. This document identifies those parts of the system that are necessary infrastructure, those that are part of the programming model, and those that are optional services that can live within the system.
+This document describes the high-level architecture of system of River technology-enabled services and/or devices (River system), defines the different components that make up the system, characterizes the use of those components, discusses some of the component interactions, and gives an example. This document identifies those parts of the system that are necessary infrastructure, those that are part of the programming model, and those that are optional services that can live within the system.
</p>
<h3 class="Heading3">
<a name="1029635"> </a>AR.1.1 Goals of the System
</h3>
<p class="Body">
- <a name="998144"> </a>A Jini system is a distributed system based on the idea of federating groups of users and the resources required by those users. The overall goal is to turn the network into a flexible, easily administered tool with which resources can be found by human and computational clients. Resources can be implemented as either hardware devices, software programs, or a combination of the two. The focus of the system is to make the network a more dynamic entity that better reflects the dynamic nature of the workgroup by enabling the ability to add and delete services flexibly.
+ <a name="998144"> </a>A River system is a distributed system based on the idea of federating groups of users and the resources required by those users. The overall goal is to turn the network into a flexible, easily administered tool with which resources can be found by human and computational clients. Resources can be implemented as either hardware devices, software programs, or a combination of the two. The focus of the system is to make the network a more dynamic entity that better reflects the dynamic nature of the workgroup by enabling the ability to add and delete services flexibly.
</p>
<p class="Body">
- <a name="998145"> </a>A Jini system consists of the following parts:
+ <a name="998145"> </a>A River system consists of the following parts:
</p>
<ul>
<li class="SmartList1"><a name="998146"> </a>A set of components that provides an infrastructure for federating services in a distributed system<p>
<li class="SmartList1"><a name="998147"> </a>A programming model that supports and encourages the production of reliable distributed services<p>
- <li class="SmartList1"><a name="998148"> </a>Services that can be made part of a federated Jini system and that offer functionality to any other member of the federation
+ <li class="SmartList1"><a name="998148"> </a>Services that can be made part of a federated River system and that offer functionality to any other member of the federation
</ul>
<p class="Body">
- <a name="998149"> </a>Although these pieces are separable and distinct, they are interrelated, which can blur the distinction in practice. The components that make up the Jini technology infrastructure make use of the Jini technology programming model; services that reside within the infrastructure also use that model; and the programming model is well supported by components in the infrastructure.
+ <a name="998149"> </a>Although these pieces are separable and distinct, they are interrelated, which can blur the distinction in practice. The components that make up the River technology infrastructure make use of the River technology programming model; services that reside within the infrastructure also use that model; and the programming model is well supported by components in the infrastructure.
</p>
<p class="Body">
<a name="998150"> </a>The end goals of the system span a number of different audiences; these goals include the following:
@@ -79,25 +79,25 @@
<li class="SmartList1"><a name="998153"> </a>Simplifying the task of building, maintaining, and altering a network of devices, software, and users
</ul>
<p class="Body">
- <a name="998154"> </a>The Jini system extends the Java<font size="-1"><sup>TM</sup></font> application environment from a single virtual machine to a network of machines. The Java application environment provides a good computing platform for distributed computing because both code and data can move from machine to machine. The environment has built-in security that allows the confidence to run code downloaded from another machine. Strong typing in the Java application environment enables identifying the class of an object to be run on a virtual machine even when the object did not originate on that machine. The result is a system in which the network supports a fluid configuration of objects that can move from place to place as needed and can call any part of the network to perform operations.
+ <a name="998154"> </a>The River system extends the Java<font size="-1"><sup>TM</sup></font> application environment from a single virtual machine to a network of machines. The Java application environment provides a good computing platform for distributed computing because both code and data can move from machine to machine. The environment has built-in security that allows the confidence to run code downloaded from another machine. Strong typing in the Java application environment enables identifying the class of an object to be run on a virtual machine even when the object did not originate on that machine. The result is a system in which the network supports a fluid configuration of objects that can move from place to place as needed and can call any part of the network to perform operations.
</p>
<p class="Body">
- <a name="998155"> </a>The Jini architecture exploits these characteristics of the Java application environment to simplify the construction of a distributed system. The Jini architecture adds mechanisms that allow fluidity of all components in a distributed system, extending the easy movement of objects to the entire networked system.
+ <a name="998155"> </a>The River architecture exploits these characteristics of the Java application environment to simplify the construction of a distributed system. The River architecture adds mechanisms that allow fluidity of all components in a distributed system, extending the easy movement of objects to the entire networked system.
</p>
<p class="Body">
- <a name="998156"> </a>The Jini technology infrastructure provides mechanisms for devices, services, and users to join and detach from a network. Joining and leaving a Jini system are easy and natural, often automatic, occurrences. Jini systems are far more dynamic than is currently possible in networked groups where configuring a network is a centralized function done by hand.
+ <a name="998156"> </a>The River technology infrastructure provides mechanisms for devices, services, and users to join and detach from a network. Joining and leaving a River system are easy and natural, often automatic, occurrences. River systems are far more dynamic than is currently possible in networked groups where configuring a network is a centralized function done by hand.
</p>
<h3 class="Heading3">
<a name="998157"> </a>AR.1.2 Environmental Assumptions
</h3>
<p class="Body">
- <a name="1029658"> </a>The Jini system federates computers and computing devices into what appears to the user as a single system. It relies on the existence of a network of reasonable speed connecting those computers and devices. Some devices require much higher bandwidth and others can do with much less--displays and printers are examples of extreme points. We assume that the latency of the network is reasonable.
+ <a name="1029658"> </a>The River system federates computers and computing devices into what appears to the user as a single system. It relies on the existence of a network of reasonable speed connecting those computers and devices. Some devices require much higher bandwidth and others can do with much less--displays and printers are examples of extreme points. We assume that the latency of the network is reasonable.
</p>
<p class="Body">
- <a name="998159"> </a>We assume that each Jini technology-enabled device has some memory and processing power. Devices without processing power or memory may be connected to a Jini system, but those devices are controlled by another piece of hardware and/or software that presents the device to the Jini system and itself contains both processing power and memory. Architectures for devices not equipped with a Java virtual machine<a href="#1031063"><sup>1</sup></a> (JVM) are explored more fully in the <em class="Emphasis"><a href="devicearch-spec.html#1028364">Jini<font size="-1"><sup>TM</sup></font> Device Architecture Specification</a>.</em>
+ <a name="998159"> </a>We assume that each River technology-enabled device has some memory and processing power. Devices without processing power or memory may be connected to a River system, but those devices are controlled by another piece of hardware and/or software that presents the device to the River system and itself contains both processing power and memory. Architectures for devices not equipped with a Java virtual machine<a href="#1031063"><sup>1</sup></a> (JVM) are explored more fully in the <em class="Emphasis"><a href="devicearch-spec.html#1028364">River Device Architecture Specification</a>.</em>
</p>
<p class="Body">
- <a name="1030172"> </a>The Jini technology infrastructure is Java technology centered. The Jini architecture gains much of its simplicity from assuming that the Java programming language is the implementation language for components. The ability to dynamically download and run code is central to a number of the features of the Jini architecture. However, the Java technology-centered nature of the Jini architecture depends on the Java application environment rather than on the Java programming language. Any programming language can be supported by a Jini system if it has a compiler that produces compliant bytecodes for the Java programming language.
+ <a name="1030172"> </a>The River technology infrastructure is Java technology centered. The River architecture gains much of its simplicity from assuming that the Java programming language is the implementation language for components. The ability to dynamically download and run code is central to a number of the features of the River architecture. However, the Java technology-centered nature of the River architecture depends on the Java application environment rather than on the Java programming language. Any programming language can be supported by a River system if it has a compiler that produces compliant bytecodes for the Java programming language.
</p>
<h2 class="Heading2">
<a name="1001448"> </a>AR.2 System Overview
@@ -106,25 +106,25 @@
<a name="1001135"> </a>AR.2.1 Key Concepts
</h3>
<p class="Body">
- The purpose of the Jini architecture is to <em class="Emphasis">federate</em> groups of devices and software components into a single, dynamic distributed system. The resulting federation provides the simplicity of access, ease of administration, and support for sharing that are provided by a large monolithic system while retaining the flexibility, uniform response, and control provided by a personal computer or workstation.
+ The purpose of the River architecture is to <em class="Emphasis">federate</em> groups of devices and software components into a single, dynamic distributed system. The resulting federation provides the simplicity of access, ease of administration, and support for sharing that are provided by a large monolithic system while retaining the flexibility, uniform response, and control provided by a personal computer or workstation.
</p>
<p class="Body">
- <a name="1001137"> </a>The architecture of a single Jini system is targeted to the workgroup. Members of the federation are assumed to agree on basic notions of trust, administration, identification, and policy. It is possible to federate Jini systems themselves for larger organizations.
+ <a name="1001137"> </a>The architecture of a single River system is targeted to the workgroup. Members of the federation are assumed to agree on basic notions of trust, administration, identification, and policy. It is possible to federate River systems themselves for larger organizations.
</p>
<h4 class="Heading4">
<a name="1001138"> </a>AR.2.1.1 Services
</h4>
<p class="Body">
- <a name="1001139"> </a>The most important concept within the Jini architecture is that of a <em class="Emphasis">service</em>. A service is an entity that can be used by a person, a program, or another service. A service may be a computation, storage, a communication channel to another user, a software filter, a hardware device, or another user. Two examples of services are printing a document and translating from one word-processor format to some other.
+ <a name="1001139"> </a>The most important concept within the River architecture is that of a <em class="Emphasis">service</em>. A service is an entity that can be used by a person, a program, or another service. A service may be a computation, storage, a communication channel to another user, a software filter, a hardware device, or another user. Two examples of services are printing a document and translating from one word-processor format to some other.
</p>
<p class="Body">
- <a name="1001140"> </a>Members of a Jini system federate to share access to services. A Jini system should not be thought of as sets of clients and servers, users and programs, or even programs and files. Instead, a Jini system consists of services that can be collected together for the performance of a particular task. Services may make use of other services, and a client of one service may itself be a service with clients of its own. The dynamic nature of a Jini system enables services to be added or withdrawn from a federation at any time according to demand, need, or the changing requirements of the workgroup using the system.
+ <a name="1001140"> </a>Members of a River system federate to share access to services. A River system should not be thought of as sets of clients and servers, users and programs, or even programs and files. Instead, a River system consists of services that can be collected together for the performance of a particular task. Services may make use of other services, and a client of one service may itself be a service with clients of its own. The dynamic nature of a River system enables services to be added or withdrawn from a federation at any time according to demand, need, or the changing requirements of the workgroup using the system.
</p>
<p class="Body">
- <a name="1001141"> </a>Jini systems provide mechanisms for service construction, lookup, communication, and use in a distributed system. Examples of services include: devices such as printers, displays, or disks; software such as applications or utilities; information such as databases and files; and users of the system.
+ <a name="1001141"> </a>River systems provide mechanisms for service construction, lookup, communication, and use in a distributed system. Examples of services include: devices such as printers, displays, or disks; software such as applications or utilities; information such as databases and files; and users of the system.
</p>
<p class="Body">
- <a name="1001142"> </a>Services in a Jini system communicate with each other by using a <em class="Emphasis">service protocol</em>, which is a set of interfaces written in the Java programming language. The set of such protocols is open ended. The base Jini system defines a small number of such protocols that define critical service interactions.
+ <a name="1001142"> </a>Services in a River system communicate with each other by using a <em class="Emphasis">service protocol</em>, which is a set of interfaces written in the Java programming language. The set of such protocols is open ended. The base River system defines a small number of such protocols that define critical service interactions.
</p>
<h4 class="Heading4">
<a name="1001143"> </a>AR.2.1.2 Lookup Service
@@ -133,7 +133,7 @@
<a name="1001144"> </a>Services are found and resolved by a <em class="Emphasis">lookup service</em>. The lookup service is the central bootstrapping mechanism for the system and provides the major point of contact between the system and users of the system. In precise terms, a lookup service maps interfaces indicating the functionality provided by a service to sets of objects that implement the service. In addition, descriptive entries associated with a service allow more fine-grained selection of services based on properties understandable to people.
</p>
<p class="Body">
- <a name="1001145"> </a>Objects in a lookup service may include other lookup services; this provides hierarchical lookup. Further, a lookup service may contain objects that encapsulate other naming or directory services, providing a way for bridges to be built between a Jini lookup service and other forms of lookup service. Of course, references to a Jini lookup service may be placed in these other naming and directory services, providing a means for clients of those services to gain access to a Jini system.
+ <a name="1001145"> </a>Objects in a lookup service may include other lookup services; this provides hierarchical lookup. Further, a lookup service may contain objects that encapsulate other naming or directory services, providing a way for bridges to be built between a River lookup service and other forms of lookup service. Of course, references to a River lookup service may be placed in these other naming and directory services, providing a means for clients of those services to gain access to a River system.
</p>
<p class="Body">
<a name="1001146"> </a>A service is added to a lookup service by a pair of protocols called <em class="Emphasis">discovery </em>and <em class="Emphasis">join</em>--first the service locates an appropriate lookup service (by using the <em class="Emphasis">discovery</em> protocol), and then it joins it (by using the <em class="Emphasis">join</em> protocol).
@@ -142,22 +142,22 @@
<a name="1001147"> </a>AR.2.1.3 Java Remote Method Invocation (Java RMI)
</h4>
<p class="Body">
- <a name="1029716"> </a>Communication between services can be accomplished using <em class="Emphasis">Java Remote Method Invocation</em> (Java RMI). The infrastructure to support communication between services is not itself a service that is discovered and used but is, rather, a part of the Jini technology infrastructure. Java RMI provides mechanisms to find, activate, and garbage collect object groups.
+ <a name="1029716"> </a>Communication between services can be accomplished using <em class="Emphasis">Java Remote Method Invocation</em> (Java RMI). The infrastructure to support communication between services is not itself a service that is discovered and used but is, rather, a part of the River technology infrastructure. Java RMI provides mechanisms to find, activate, and garbage collect object groups.
</p>
<p class="Body">
- <a name="1029717"> </a>Fundamentally, Java RMI is a Java programming language-enabled extension to traditional remote procedure call mechanisms. Java RMI allows not only data to be passed from object to object around the network but full objects, including code. Much of the simplicity of the Jini system is enabled by this ability to move code around the network in a form that is encapsulated as an object.
+ <a name="1029717"> </a>Fundamentally, Java RMI is a Java programming language-enabled extension to traditional remote procedure call mechanisms. Java RMI allows not only data to be passed from object to object around the network but full objects, including code. Much of the simplicity of the River system is enabled by this ability to move code around the network in a form that is encapsulated as an object.
</p>
<h4 class="Heading4">
<a name="1001150"> </a>AR.2.1.4 Security
</h4>
<p class="Body">
- <a name="1001151"> </a>The design of the security model for Jini technology is built on the twin notions of a <em class="Emphasis">principal</em> and an <em class="Emphasis">access control list</em>. Jini services are accessed on behalf of some entity--the principal--which generally traces back to a particular user of the system. Services themselves may request access to other services based on the identity of the object that implements the service. Whether access to a service is allowed depends on the contents of an access control list that is associated with the object.
+ <a name="1001151"> </a>The design of the security model for River technology is built on the twin notions of a <em class="Emphasis">principal</em> and an <em class="Emphasis">access control list</em>. River services are accessed on behalf of some entity--the principal--which generally traces back to a particular user of the system. Services themselves may request access to other services based on the identity of the object that implements the service. Whether access to a service is allowed depends on the contents of an access control list that is associated with the object.
</p>
<h4 class="Heading4">
<a name="1001152"> </a>AR.2.1.5 Leasing
</h4>
<p class="Body">
- <a name="1001153"> </a>Access to many of the services in the Jini system environment is <em class="Emphasis">lease</em> based. A lease is a grant of guaranteed access over a time period. Each lease is negotiated between the user of the service and the provider of the service as part of the service protocol: A service is requested for some period; access is granted for some period, presumably taking the request period into account. If a lease is not renewed before it is freed--either because the resource is no longer needed, the client or network fails, or the lease is not permitted to be renewed--then both the user and the provider of the resource may conclude that the resource can be freed.
+ <a name="1001153"> </a>Access to many of the services in the River system environment is <em class="Emphasis">lease</em> based. A lease is a grant of guaranteed access over a time period. Each lease is negotiated between the user of the service and the provider of the service as part of the service protocol: A service is requested for some period; access is granted for some period, presumably taking the request period into account. If a lease is not renewed before it is freed--either because the resource is no longer needed, the client or network fails, or the lease is not permitted to be renewed--then both the user and the provider of the resource may conclude that the resource can be freed.
</p>
<p class="Body">
<a name="1029724"> </a>Leases are either exclusive or non-exclusive. Exclusive leases ensure that no one else may take a lease on the resource during the period of the lease; non-exclusive leases allow multiple users to share a resource.
@@ -166,27 +166,27 @@
<a name="1029725"> </a>AR.2.1.6 Transactions
</h4>
<p class="Body">
- <a name="1001156"> </a>A series of operations, either within a single service or spanning multiple services, can be wrapped in a <em class="Emphasis">transaction</em>. The Jini transaction interfaces supply a service protocol needed to coordinate a <em class="Emphasis">two-phase commit</em>. How transactions are implemented--and indeed, the very semantics of the notion of a transaction--is left up to the service using those interfaces.
+ <a name="1001156"> </a>A series of operations, either within a single service or spanning multiple services, can be wrapped in a <em class="Emphasis">transaction</em>. The River transaction interfaces supply a service protocol needed to coordinate a <em class="Emphasis">two-phase commit</em>. How transactions are implemented--and indeed, the very semantics of the notion of a transaction--is left up to the service using those interfaces.
</p>
<h4 class="Heading4">
<a name="1001157"> </a>AR.2.1.7 Events
</h4>
<p class="Body">
- <a name="1001158"> </a>The Jini architecture supports distributed <em class="Emphasis">events</em>. An object may allow other objects to register interest in events in the object and receive a notification of the occurrence of such an event. This enables distributed event-based programs to be written with a variety of reliability and scalability guarantees.
+ <a name="1001158"> </a>The River architecture supports distributed <em class="Emphasis">events</em>. An object may allow other objects to register interest in events in the object and receive a notification of the occurrence of such an event. This enables distributed event-based programs to be written with a variety of reliability and scalability guarantees.
</p>
<h3 class="Heading3">
<a name="1001159"> </a>AR.2.2 Component Overview
</h3>
<p class="Body">
- <a name="1030125"> </a>The components of the Jini system can be segmented into three categories: <em class="Emphasis">infrastructure</em>, <em class="Emphasis">programming model</em>, and <em class="Emphasis">services</em>. The infrastructure is the set of components that enables building a federated Jini system, while the services are the entities within the federation. The programming model is a set of interfaces that enables the construction of reliable services, including those that are part of the infrastructure and those that join into the federation.
+ <a name="1030125"> </a>The components of the River system can be segmented into three categories: <em class="Emphasis">infrastructure</em>, <em class="Emphasis">programming model</em>, and <em class="Emphasis">services</em>. The infrastructure is the set of components that enables building a federated River system, while the services are the entities within the federation. The programming model is a set of interfaces that enables the construction of reliable services, including those that are part of the infrastructure and those that join into the federation.
</p>
<p class="Body">
- <a name="1030126"> </a>These three categories, though distinct and separable, are entangled to such an extent that the distinction between them can seem blurred. Moreover, it is possible to build systems that have some of the functionality of the Jini system with variants on the categories or without all three of them. But a Jini system gains its full power because it is a <em class="Emphasis">system</em> built with the particular infrastructure and programming models described, based on the notion of a service. Decoupling the segments within the architecture allows legacy code to be changed minimally to take part in a Jini system. Nevertheless, the full power of a Jini system will be available only to new services that are constructed using the integrated model.
+ <a name="1030126"> </a>These three categories, though distinct and separable, are entangled to such an extent that the distinction between them can seem blurred. Moreover, it is possible to build systems that have some of the functionality of the River system with variants on the categories or without all three of them. But a River system gains its full power because it is a <em class="Emphasis">system</em> built with the particular infrastructure and programming models described, based on the notion of a service. Decoupling the segments within the architecture allows legacy code to be changed minimally to take part in a River system. Nevertheless, the full power of a River system will be available only to new services that are constructed using the integrated model.
</p>
<p class="Body">
- <a name="1001162"> </a>A Jini system can be seen as a network extension of the infrastructure, programming model, and services that made Java technology successful in the single-machine case. These categories along with the corresponding components in the familiar Java application environment are shown in Figure AR.2.1:<p>
+ <a name="1001162"> </a>A River system can be seen as a network extension of the infrastructure, programming model, and services that made Java technology successful in the single-machine case. These categories along with the corresponding components in the familiar Java application environment are shown in Figure AR.2.1:<p>
-<table align="center" border="1" bordercolorlight="#FFFFFF" bordercolordark="#000000" cellpadding="5" cellspacing="0" Summary="Jini Architecture Segmentation">
+<table align="center" border="1" bordercolorlight="#FFFFFF" bordercolordark="#000000" cellpadding="5" cellspacing="0" Summary="River Architecture Segmentation">
<caption><p class="Body">
<a name="1030589"> </a>
</p>
@@ -221,7 +221,7 @@
<td height="1"><br></td>
</tr>
<tr>
- <th rowspan="3">Java<br>+<br>Jini</th>
+ <th rowspan="3">Java<br>+<br>River</th>
<td>Discovery/Join</td>
<td>Leasing</td>
<td>Printing</td>
@@ -242,12 +242,12 @@
</p>
-<a name="1029549"> </a><div class="TableTitle">Figure AR.2.1: Jini Architecture Segmentation</div>
+<a name="1029549"> </a><div class="TableTitle">Figure AR.2.1: River Architecture Segmentation</div>
<h4 class="Heading4">
<a name="1001214"> </a>AR.2.2.1 Infrastructure
</h4>
<p class="Body">
- <a name="1029758"> </a>The Jini technology infrastructure defines the minimal Jini technology core. The infrastructure includes the following:
+ <a name="1029758"> </a>The River technology infrastructure defines the minimal River technology core. The infrastructure includes the following:
</p>
<ul>
<li class="SmartList1"><a name="1029759"> </a>A distributed security system, integrated into Java RMI, that extends the Java platform's security model to the world of distributed systems.<p>
@@ -255,7 +255,7 @@
<li class="SmartList1"><a name="1030178"> </a>The lookup service, which serves as a repository of services. Entries in the lookup service are objects written in the Java programming language; these objects can be downloaded as part of a lookup operation and act as local proxies to the service that placed the code into the lookup service.
</ul>
<p class="Body">
- <a name="1001219"> </a>The discovery and join protocols define the way a service of any kind becomes part of a Jini system; Java RMI defines the base language within which the Jini technology-enabled services communicate; the distributed security model and its implementation define how entities are identified and how they get the rights to perform actions on their own behalf and on the behalf of others; and the lookup service reflects the current members of the federation and acts as the central marketplace for offering and finding services by members of the federation.
+ <a name="1001219"> </a>The discovery and join protocols define the way a service of any kind becomes part of a River system; Java RMI defines the base language within which the River technology-enabled services communicate; the distributed security model and its implementation define how entities are identified and how they get the rights to perform actions on their own behalf and on the behalf of others; and the lookup service reflects the current members of the federation and acts as the central marketplace for offering and finding services by members of the federation.
</p>
<h4 class="Heading4">
<a name="1001220"> </a>AR.2.2.2 Programming Model
@@ -264,14 +264,14 @@
<a name="1001221"> </a>The infrastructure both enables the programming model and makes use of it. Entries in the lookup service are leased, allowing the lookup service to reflect accurately the set of currently available services. When services join or leave a lookup service, events are signaled, and objects that have registered interest in such events get notifications when new services become available or old services cease to be active. The programming model rests on the ability to move code, which is supported by the base infrastructure.
</p>
<p class="Body">
- <a name="1001222"> </a>Both the infrastructure and the services that use that infrastructure are computational entities that exist in the physical environment of the Jini system. However, services also constitute a set of interfaces which define communication protocols that can be used by the services and the infrastructure to communicate between themselves.
+ <a name="1001222"> </a>Both the infrastructure and the services that use that infrastructure are computational entities that exist in the physical environment of the River system. However, services also constitute a set of interfaces which define communication protocols that can be used by the services and the infrastructure to communicate between themselves.
</p>
<p class="Body">
- <a name="1001223"> </a>These interfaces, taken together, make up the distributed extension of the standard Java programming language model that constitutes the Jini programming model. Among the interfaces that make up the Jini programming model are the following:
+ <a name="1001223"> </a>These interfaces, taken together, make up the distributed extension of the standard Java programming language model that constitutes the River programming model. Among the interfaces that make up the River programming model are the following:
</p>
<ul>
<li class="SmartList1"><a name="1001224"> </a>The leasing interface, which defines a way of allocating and freeing resources using a renewable, duration-based model<p>
- <li class="SmartList1"><a name="1001225"> </a>The event and notification interfaces, which are an extension of the event model used by JavaBeans<font size="-1"><sup>TM</sup></font> components to the distributed environment, enable event-based communication between Jini technology-enabled services<p>
+ <li class="SmartList1"><a name="1001225"> </a>The event and notification interfaces, which are an extension of the event model used by JavaBeans<font size="-1"><sup>TM</sup></font> components to the distributed environment, enable event-based communication between River technology-enabled services<p>
<li class="SmartList1"><a name="1001226"> </a>The transaction interfaces, which enable entities to cooperate in such a way that either all of the changes made to the group occur atomically or none of them occur
</ul>
<p class="Body">
@@ -281,48 +281,48 @@
<a name="1029762"> </a>The event and notification interfaces extend the standard event models used by JavaBeans components and the Java application environment to the distributed case, enabling events to be handled by third-party objects while making various delivery and timeliness guarantees. The model also recognizes that the delivery of a distributed notification may be delayed.
</p>
<p class="Body">
- <a name="1029763"> </a>The transaction interfaces introduce a lightweight, object-oriented protocol enabling applications using Jini technology to coordinate state changes. The transaction protocol provides two steps to coordinate the actions of a group of distributed objects. The first step is called the <em class="Emphasis">voting phase,</em> in which each object "votes" whether it has completed its portion of the task and is ready to commit any changes it made. In the second step, a coordinator issues a "commit" request to each object.
+ <a name="1029763"> </a>The transaction interfaces introduce a lightweight, object-oriented protocol enabling applications using River technology to coordinate state changes. The transaction protocol provides two steps to coordinate the actions of a group of distributed objects. The first step is called the <em class="Emphasis">voting phase,</em> in which each object "votes" whether it has completed its portion of the task and is ready to commit any changes it made. In the second step, a coordinator issues a "commit" request to each object.
</p>
<p class="Body">
- <a name="1001230"> </a>The Jini transaction protocol differs from most transaction interfaces in that it does not assume that the transactions occur in a transaction processing system. Such systems define mechanisms and programming requirements that guarantee the correct implementation of a particular transaction semantics. The Jini transaction protocol takes a more traditional object-oriented view, leaving the correct implementation of the desired transaction semantics up to the implementor of the particular objects that are involved in the transaction. The goal of the transaction protocol is to define the interactions that such objects must have to coordinate such groups of operations.
+ <a name="1001230"> </a>The River transaction protocol differs from most transaction interfaces in that it does not assume that the transactions occur in a transaction processing system. Such systems define mechanisms and programming requirements that guarantee the correct implementation of a particular transaction semantics. The River transaction protocol takes a more traditional object-oriented view, leaving the correct implementation of the desired transaction semantics up to the implementor of the particular objects that are involved in the transaction. The goal of the transaction protocol is to define the interactions that such objects must have to coordinate such groups of operations.
</p>
<p class="Body">
- <a name="1001231"> </a>The interfaces that define the Jini programming model are used by the infrastructure components where appropriate and by the initial Jini technology-enabled services. For example, the lookup service makes use of the leasing and event interfaces. Leasing ensures that services registered continue to be available, and events help administrators discover problems and devices that need configuration. The JavaSpaces<font size="-1"><sup>TM</sup></font> service, one example of a Jini technology-enabled service, utilizes leasing and events, and also supports the Jini transaction protocol. The transaction manager can be used to coordinate the voting phase of a transaction for those objects that support transaction protocol.
+ <a name="1001231"> </a>The interfaces that define the River programming model are used by the infrastructure components where appropriate and by the initial River technology-enabled services. For example, the lookup service makes use of the leasing and event interfaces. Leasing ensures that services registered continue to be available, and events help administrators discover problems and devices that need configuration. The JavaSpaces<font size="-1"><sup>TM</sup></font> service, one example of a River technology-enabled service, utilizes leasing and events, and also supports the River transaction protocol. The transaction manager can be used to coordinate the voting phase of a transaction for those objects that support transaction protocol.
</p>
<p class="Body">
- <a name="1001232"> </a>The implementation of a service is not required to use the Jini programming model, but such services need to use that model for their interaction with the Jini technology infrastructure. For example, every service interacts with the Jini lookup service by using the programming model; and whether a service offers resources on a leased basis or not, the service's registration with the lookup service will be leased and will need to be periodically renewed.
+ <a name="1001232"> </a>The implementation of a service is not required to use the River programming model, but such services need to use that model for their interaction with the River technology infrastructure. For example, every service interacts with the River lookup service by using the programming model; and whether a service offers resources on a leased basis or not, the service's registration with the lookup service will be leased and will need to be periodically renewed.
</p>
<p class="Body">
- <a name="1001233"> </a>The binding of the programming model to the services and the infrastructure is what makes such a federation a Jini system not just a collection of services and protocols. The combination of infrastructure, service, and programming model, all designed to work together and constructed by using each other, simplifies the overall system and unifies it in a way that makes it easier to understand.
+ <a name="1001233"> </a>The binding of the programming model to the services and the infrastructure is what makes such a federation a River system not just a collection of services and protocols. The combination of infrastructure, service, and programming model, all designed to work together and constructed by using each other, simplifies the overall system and unifies it in a way that makes it easier to understand.
</p>
<h4 class="Heading4">
<a name="1001234"> </a>AR.2.2.3 Services
</h4>
<p class="Body">
- <a name="1001235"> </a>The Jini technology infrastructure and programming model are built to enable services to be offered and found in the network federation. These services make use of the infrastructure to make calls to each other, to discover each other, and to announce their presence to other services and users.
+ <a name="1001235"> </a>The River technology infrastructure and programming model are built to enable services to be offered and found in the network federation. These services make use of the infrastructure to make calls to each other, to discover each other, and to announce their presence to other services and users.
</p>
<p class="Body">
<a name="1029791"> </a>Services appear programmatically as objects written in the Java programming language, perhaps made up of other objects. A service has an interface that defines the operations that can be requested of that service. Some of these interfaces are intended to be used by programs, while others are intended to be run by the receiver so that the service can interact with a user. The type of the service determines the interfaces that make up that service and also define the set of methods that can be used to access the service. A single service may be implemented by using other services.
</p>
<p class="Body">
- <a name="1001237"> </a>Example Jini technology-enabled services include the following:
+ <a name="1001237"> </a>Example River technology-enabled services include the following:
</p>
<ul>
<li class="SmartList1"><a name="1001238"> </a>A printing service, which can print from applications written in the Java programming language as well as legacy applications<p>
<li class="SmartList1"><a name="1001239"> </a>A JavaSpaces service, which can be used for simple communication and for storage of related groups of objects written in the Java programming language<p>
- <li class="SmartList1"><a name="1001240"> </a>A transaction manager, which enables groups of objects to participate in the Jini transaction protocol defined by the programming model
+ <li class="SmartList1"><a name="1001240"> </a>A transaction manager, which enables groups of objects to participate in the River transaction protocol defined by the programming model
</ul>
<h3 class="Heading3">
<a name="1001241"> </a>AR.2.3 Service Architecture
</h3>
<p class="Body">
- <a name="1001242"> </a>Services form the interactive basis for a Jini system, both at the programming and user interface levels. The details of the service architecture are best understood once the Jini discovery and Jini lookup protocols are presented.
+ <a name="1001242"> </a>Services form the interactive basis for a River system, both at the programming and user interface levels. The details of the service architecture are best understood once the River discovery and River lookup protocols are presented.
</p>
<h4 class="Heading4">
<a name="1001244"> </a>AR.2.3.1 Discovery and Lookup Protocols
</h4>
<p class="Body">
- <a name="1030414"> </a>The heart of the Jini system is a trio of protocols called <em class="Emphasis">discovery</em>, <em class="Emphasis">join</em>, and <em class="Emphasis">lookup</em>. A pair of these protocols--discovery and join--occur when a device is plugged in. Discovery occurs when a service is looking for a lookup service with which to register. Join occurs when a service has located a lookup service and wishes to join it. Lookup occurs when a client or user needs to locate and invoke a service described by its interface type (written in the Java programming language) and possibly other attributes. Figure AR.2.2 outlines the discovery process.
+ <a name="1030414"> </a>The heart of the River system is a trio of protocols called <em class="Emphasis">discovery</em>, <em class="Emphasis">join</em>, and <em class="Emphasis">lookup</em>. A pair of these protocols--discovery and join--occur when a device is plugged in. Discovery occurs when a service is looking for a lookup service with which to register. Join occurs when a service has located a lookup service and wishes to join it. Lookup occurs when a client or user needs to locate and invoke a service described by its interface type (written in the Java programming language) and possibly other attributes. Figure AR.2.2 outlines the discovery process.
<p><img src="images/jini-spec2.gif" alt="Shows 3 boxes: Client, Lookup Service, and Service Provider (containing Service Object and Service Attributes). The Service Provider is "broadcasting" to the other services. The caption reads - A service provider seeks a lookup service." height="215" width="480" align="Center">
</p>
@@ -330,7 +330,7 @@
<a name="1030452"> </a>
</p>
<a name="1029833"> </a><div class="TableTitle">Figure AR.2.2: Discovery</div><p class="Body">
- <a name="1030015"> </a>Jini discovery/join is the process of adding a service to a Jini system. A service provider is the originator of the service--a device or software, for example. First, the service provider locates a lookup service by multicasting a request on the local network for any lookup services to identify themselves (Figure AR.2.2). Then, a service object for the service is loaded into the lookup service (Figure AR.2.3). This service object contains the Java programming language interface for the service, including the methods that users and applications will invoke to execute the service along with any other descriptive attributes.
+ <a name="1030015"> </a>River discovery/join is the process of adding a service to a River system. A service provider is the originator of the service--a device or software, for example. First, the service provider locates a lookup service by multicasting a request on the local network for any lookup services to identify themselves (Figure AR.2.2). Then, a service object for the service is loaded into the lookup service (Figure AR.2.3). This service object contains the Java programming language interface for the service, including the methods that users and applications will invoke to execute the service along with any other descriptive attributes.
</p>
<p class="Body">
<a name="1030060"> </a><img src="images/jini-speca.gif" alt="Same 3 boxes: Client, Lookup Service (now shown containing Service Object and Service Attributes), and Service Provider (containing Service Object and Service Attributes). An arrow is shown from the Service Provider contents to the Lookup Service contents. The caption reads - A service provider registers a service object (proxy) and its service attributes with the lookup service." align="Center" height="238" width="480">
@@ -362,7 +362,7 @@
<a name="1001381"> </a>Programmatic interfaces may be implemented either as Java RMI references to the remote object that implements the service, as a local computation that provides all of the service locally, or as some combination. Such combinations, called <em class="Emphasis">smart proxies</em>, implement some of the functions of a service locally and the remainder through remote calls to a centralized implementation of the service.
</p>
<p class="Body">
- <a name="1001382"> </a>A user interface can also be stored in the lookup service as an attribute of a registered service. A user interface stored in the lookup service by a Jini technology-enabled service is an implementation that allows the service to be directly manipulated by a user of the system.
+ <a name="1001382"> </a>A user interface can also be stored in the lookup service as an attribute of a registered service. A user interface stored in the lookup service by a River technology-enabled service is an implementation that allows the service to be directly manipulated by a user of the system.
</p>
<p class="Body">
<a name="1001383"> </a>In effect, a user interface for a service is a specialized form of the service interface that enables a program, such as a browser, to step out of the way and let the human user interact directly with a service.
@@ -386,19 +386,19 @@
<a name="1001488"> </a>AR.3 An Example
</h2>
<p class="Body">
- This example shows how a Jini technology-enabled printing service might be used by a digital camera to print a high-resolution color image. It will start with the printer joining an existing Jini system, continue with its being configured, and end with printing the image.
+ This example shows how a River technology-enabled printing service might be used by a digital camera to print a high-resolution color image. It will start with the printer joining an existing River system, continue with its being configured, and end with printing the image.
</p>
<h3 class="Heading3">
<a name="1001489"> </a>AR.3.1 Registering the Printer Service
</h3>
<p class="Body">
- <a name="1001490"> </a>A printer that is either freshly connected to a Jini system or is powered up once it has been connected to a Jini system grouping needs to discover the appropriate lookup service and register with it. This is the <em class="Emphasis">discovery</em> and <em class="Emphasis">join</em> phase.
+ <a name="1001490"> </a>A printer that is either freshly connected to a River system or is powered up once it has been connected to a River system grouping needs to discover the appropriate lookup service and register with it. This is the <em class="Emphasis">discovery</em> and <em class="Emphasis">join</em> phase.
</p>
<h4 class="Heading4">
<a name="1001491"> </a>AR.3.1.1 Discovering the Lookup Service
</h4>
<p class="Body">
- <a name="1001492"> </a>The basic operations of discovering the lookup service are implemented by a Jini technology infrastructure software class. An instance of this class acts as a mediator between devices and services on one hand and the lookup service on the other. In this example the printer first registers itself with a local instance of this class. This instance then multicasts a request on the local network for any lookup services to identify themselves. The instance listens for replies and, if there are any, passes to the printer an array of objects that are proxies for the discovered lookup services.
+ <a name="1001492"> </a>The basic operations of discovering the lookup service are implemented by a River technology infrastructure software class. An instance of this class acts as a mediator between devices and services on one hand and the lookup service on the other. In this example the printer first registers itself with a local instance of this class. This instance then multicasts a request on the local network for any lookup services to identify themselves. The instance listens for replies and, if there are any, passes to the printer an array of objects that are proxies for the discovered lookup services.
</p>
<h4 class="Heading4">
<a name="1001493"> </a>AR.3.1.2 Joining the Lookup Service
@@ -422,25 +422,25 @@
<a name="1001499"> </a>AR.3.1.4 Staying Alive
</h4>
<p class="Body">
- <a name="1001500"> </a>When the printer registers with the Jini lookup service it receives a <em class="Emphasis">lease</em>. Periodically, the printer will need to renew this lease with the lookup service. If the printer fails to renew the lease, then when the lease expires, the lookup service will remove the entry for it, and the printer service will no longer be available.
+ <a name="1001500"> </a>When the printer registers with the River lookup service it receives a <em class="Emphasis">lease</em>. Periodically, the printer will need to renew this lease with the lookup service. If the printer fails to renew the lease, then when the lease expires, the lookup service will remove the entry for it, and the printer service will no longer be available.
</p>
<h3 class="Heading3">
<a name="1029892"> </a>AR.3.2 Printing
</h3>
<p class="Body">
- <a name="1029893"> </a>Some services provide a user interface for interaction with them; others rely on an application to mediate such interaction. This example assumes that a person has a digital camera that has taken a picture they want to print on a high-resolution printer. The first thing that the camera needs to do after it is connected to the network is locate a Jini technology-enabled printing service. Once a printing service has been located and selected, the camera can invoke methods to print the image.
+ <a name="1029893"> </a>Some services provide a user interface for interaction with them; others rely on an application to mediate such interaction. This example assumes that a person has a digital camera that has taken a picture they want to print on a high-resolution printer. The first thing that the camera needs to do after it is connected to the network is locate a River technology-enabled printing service. Once a printing service has been located and selected, the camera can invoke methods to print the image.
</p>
<h4 class="Heading4">
<a name="1001503"> </a>AR.3.2.1 Locate the Lookup Service
</h4>
<p class="Body">
- <a name="1001504"> </a>Before the camera can use a Jini technology-enabled service, it must first locate the Jini lookup service, just as the print service needed to do to register itself. The camera registers itself with a local instance of the Jini technology infrastructure class <code>LookupDiscovery</code>, which will notify the camera of all discovered lookup services.
+ <a name="1001504"> </a>Before the camera can use a River technology-enabled service, it must first locate the River lookup service, just as the print service needed to do to register itself. The camera registers itself with a local instance of the River technology infrastructure class <code>LookupDiscovery</code>, which will notify the camera of all discovered lookup services.
</p>
<h4 class="Heading4">
<a name="1001505"> </a>AR.3.2.2 Search for Printing Services
</h4>
<p class="Body">
- <a name="1001506"> </a>Finding an appropriate service requires passing a template that is used to match and filter the set of existing services. The template specifies both the type of the required service, which is the first filter on possible services, and a set of attributes which is used to reduce the number of matching services if there are several of the right type. In this example, the camera supplies a template specifying the printer type and an array of attribute objects. The type of each object specifies the attribute type, and its fields specify values to be matched. For each attribute, fields that should be matched, such as color printing, are filled in; ones that don't matter are left null. The Jini lookup service is passed this template and returns an array of all of the printing services that match it. If there are several matching services, the camera may further filter them--in this case perhaps to ensure high print resolution--and present the user with th
e list of possible printers for choice. The final result is a single service object for the printing service.
+ <a name="1001506"> </a>Finding an appropriate service requires passing a template that is used to match and filter the set of existing services. The template specifies both the type of the required service, which is the first filter on possible services, and a set of attributes which is used to reduce the number of matching services if there are several of the right type. In this example, the camera supplies a template specifying the printer type and an array of attribute objects. The type of each object specifies the attribute type, and its fields specify values to be matched. For each attribute, fields that should be matched, such as color printing, are filled in; ones that don't matter are left null. The River lookup service is passed this template and returns an array of all of the printing services that match it. If there are several matching services, the camera may further filter them--in this case perhaps to ensure high print resolution--and present the user with t
he list of possible printers for choice. The final result is a single service object for the printing service.
</p>
<p class="Body">
<a name="1001507"> </a>At this point the printing service has been selected, and the camera and the printer service communicate directly with each other; the lookup service is no longer involved.
@@ -518,7 +518,7 @@
<a href="#skip" title="Skip navigation bar"></a>
<table width="100%"><tr>
<td align=left><a href="../../spec-index.html">Spec Index</a>
-<td align=right><em>Jini Architecture Specification</em></td>
+<td align=right><em>River Architecture Specification</em></td>
</tr></table>
<a name="skip"></a>
Modified: incubator/river/jtsk/trunk/doc/specs/html/joinutil-spec.html
URL: http://svn.apache.org/viewvc/incubator/river/jtsk/trunk/doc/specs/html/joinutil-spec.html?rev=896131&r1=896130&r2=896131&view=diff
==============================================================================
--- incubator/river/jtsk/trunk/doc/specs/html/joinutil-spec.html (original)
+++ incubator/river/jtsk/trunk/doc/specs/html/joinutil-spec.html Tue Jan 5 17:12:26 2010
@@ -22,7 +22,7 @@
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<meta name="GENERATOR" content="Quadralay WebWorks Publisher 5.0.4">
<link rel="StyleSheet" href="standard.css" type="text/css" media="screen">
-<title>Jini Join Utilities Specification </title>
+<title>River Join Utilities Specification </title>
</head>
<body bgcolor="#ffffff">
@@ -32,7 +32,7 @@
<table width="100%">
<tr>
<td align=left><a href="../../spec-index.html">Spec Index</a></td>
-<td align=right><i>A Collection of Jini Technology Helper Utilities and Services Specifications</i></td>
+<td align=right><i>A Collection of River Technology Helper Utilities and Services Specifications</i></td>
</tr>
</table>
<br clear="all">
@@ -47,12 +47,12 @@
<a name="skip"></a>
<blockquote>
<h2>
- <a name="1015487"> </a>JU - Jini<font size="-1"><sup>TM</sup></font> Join Utilities Specification</h2>
+ <a name="1015487"> </a>JU - River Join Utilities Specification</h2>
<h3 class="Heading2">
<a name="1015667"> </a>JU.1 Introduction
</h3>
<p class="Body">
- <a name="1015702"> </a>This specification defines helper utility classes, along with supporting interfaces and classes, that encapsulate functionality that can help Jini<font size="-1"><sup>TM</sup></font> technology-based services (Jini services) demonstrate good behavior in their discovery and registration related interactions with Jini lookup services. In particular, the Jini join utilities perform functions related to lookup service discovery and registration (joining), as well as lease renewal and attribute management, which the Jini technology programming model requires of a well-behaved Jini service. Currently, this specification defines only one helper utility class:
+ <a name="1015702"> </a>This specification defines helper utility classes, along with supporting interfaces and classes, that encapsulate functionality that can help River technology-based services (River services) demonstrate good behavior in their discovery and registration related interactions with River lookup services. In particular, the River join utilities perform functions related to lookup service discovery and registration (joining), as well as lease renewal and attribute management, which the River technology programming model requires of a well-behaved River service. Currently, this specification defines only one helper utility class:
</p>
<ul>
@@ -63,22 +63,22 @@
<a name="1015670"> </a>JU.2 The <code>JoinManager</code>
</h3>
<p class="Body">
- <a name="1016181"> </a>The goal of any well-behaved Jini service, implemented within the bounds defined by the Jini technology programming model, is to advertise the service it provides by requesting residency within at least one Jini lookup service. Making such a request of a Jini lookup service is known as registering with, or <em class="Emphasis">joining</em>, a lookup service. To demonstrate this good behavior, a service must comply with both the multicast discovery protocol and the unicast discovery protocol to discover the lookup services it is interested in joining. The service must also comply with the join protocol to register with the desired lookup services. The details of the discovery and join protocols are described in the <a href="discovery-spec.html"><em class="Emphasis">Jini Technology Discovery and Join Specification</em></a>.
+ <a name="1016181"> </a>The goal of any well-behaved River service, implemented within the bounds defined by the River technology programming model, is to advertise the service it provides by requesting residency within at least one River lookup service. Making such a request of a River lookup service is known as registering with, or <em class="Emphasis">joining</em>, a lookup service. To demonstrate this good behavior, a service must comply with both the multicast discovery protocol and the unicast discovery protocol to discover the lookup services it is interested in joining. The service must also comply with the join protocol to register with the desired lookup services. The details of the discovery and join protocols are described in the <a href="discovery-spec.html"><em class="Emphasis">River Technology Discovery and Join Specification</em></a>.
</p>
<p class="Body">
<a name="1016156"> </a>For the service to maintain its residency in the lookup services it has joined, the service must provide for the coordination, systematic renewal, and overall management of all leases on that residency. In addition to handling all discovery and join duties, as well as managing all leases on lookup service residency, the service must provide for the coordination and management of any attribute sets with which it may have registered.
</p>
<p class="Body">
- <a name="1016215"> </a>With respect to the duties described above, a Jini service may perform all but the attribute set management duties by using the helper utility classes <code>LookupDiscoveryManager</code> and <code>LeaseRenewalManager</code>. (For information on these classes, refer to the <a href="discoveryutil-spec.html"><em class="Emphasis">Jini Discovery Utilities Specification</em>, Section DU.5, "The LookupDiscoveryManager Utility"</a>, and the <a href="leaseutil-spec.html"><em class="Emphasis">Jini Lease Utilities Specification</em>, Section LM.2, "The LeaseRenewalManager"</a>).
+ <a name="1016215"> </a>With respect to the duties described above, a River service may perform all but the attribute set management duties by using the helper utility classes <code>LookupDiscoveryManager</code> and <code>LeaseRenewalManager</code>. (For information on these classes, refer to the <a href="discoveryutil-spec.html"><em class="Emphasis">River Discovery Utilities Specification</em>, Section DU.5, "The LookupDiscoveryManager Utility"</a>, and the <a href="leaseutil-spec.html"><em class="Emphasis">River Lease Utilities Specification</em>, Section LM.2, "The LeaseRenewalManager"</a>).
</p>
<p class="Body">
- <a name="1002807"> </a>Rather than writing a service to use these classes in a coordinated fashion (in addition to providing for attribute management), the service may be written to employ the <code>JoinManager</code> class from the <code>net.jini.lookup</code> package. This utility class performs all of the functions related to discovery, joining, service lease renewal, and attribute management that the Jini technology programming model requires of a well-behaved Jini service. Each of these activities is intimately involved with the maintenance of a service's residency in one or more lookup services (the service's <em class="Emphasis">join state</em>), hence the name <code>JoinManager</code>.
+ <a name="1002807"> </a>Rather than writing a service to use these classes in a coordinated fashion (in addition to providing for attribute management), the service may be written to employ the <code>JoinManager</code> class from the <code>net.jini.lookup</code> package. This utility class performs all of the functions related to discovery, joining, service lease renewal, and attribute management that the River technology programming model requires of a well-behaved River service. Each of these activities is intimately involved with the maintenance of a service's residency in one or more lookup services (the service's <em class="Emphasis">join state</em>), hence the name <code>JoinManager</code>.
</p>
<p class="Body">
<a name="1002812"> </a>The <code>JoinManager</code> class provides an implementation of the functionality described above. The use of this class in a wide variety of services can help minimize the work resulting from having to repeatedly implement this required functionality in each service.
</p>
<p class="Body">
- <a name="1001884"> </a>The <code>JoinManager</code> is a utility class, not a remote service. Jini services that wish to use this utility will create an instance of the <code>JoinManager</code> in the service's address space to manage the entity's join state locally.
+ <a name="1001884"> </a>The <code>JoinManager</code> is a utility class, not a remote service. River services that wish to use this utility will create an instance of the <code>JoinManager</code> in the service's address space to manage the entity's join state locally.
</p>
<p class="Body">
<a name="1003456"> </a>Note that when either the term <em>service</em> or the term <em>entity</em> is used, it refers to the object that has created an instance of the <code>JoinManager</code> and avails itself of the public methods of that utility class.
@@ -209,7 +209,7 @@
<a name="1016267"> </a>A constructor from the first category is typically used by services that have not yet been assigned a service ID, but that have been pre-configured to join lookup services that the service identifies through the initialization of a discovery manager.
</p>
<p class="Body">
- <a name="1002941"> </a>The constructors from the second category each take the same arguments as the constructors from the first category, except that an instance of <code>ServiceID</code> replaces the instance of <code>ServiceIDListener</code>. Note that the <code>ServiceID</code> class is defined in the <a href="lookup-spec.html"><em class="Emphasis">Jini Technology Lookup Service Specification</em></a>, and the <code>ServiceIDListener</code> interface is described later in this document.
+ <a name="1002941"> </a>The constructors from the second category each take the same arguments as the constructors from the first category, except that an instance of <code>ServiceID</code> replaces the instance of <code>ServiceIDListener</code>. Note that the <code>ServiceID</code> class is defined in the <a href="lookup-spec.html"><em class="Emphasis">River Technology Lookup Service Specification</em></a>, and the <code>ServiceIDListener</code> interface is described later in this document.
</p>
<p class="Body">
<a name="1002065"> </a>Constructors from the second category each apply the same semantics to the <code>serviceProxy</code>, <code>attrSets</code>, <code>discoveryMgr</code>, and <code>leaseMgr</code> arguments as is applied by the constructors from the first category.
@@ -260,7 +260,7 @@
<p class="Body">
An invocation of either form of this method with duplicate elements in the <code>attrSets</code> parameter (where duplication means attribute equality as defined by calling the <code>MarshalledObject.equals</code> method on field values) is equivalent to performing the invocation with the duplicates removed from that parameter. If <code>null</code> is passed in as the value of this parameter, a <code>NullPointerException</code> will be thrown.
<p class="Body">
-The second form of this method also takes as input a flag indicating whether or not this method should determine if the attributes in the input set are instances of the <code>ServiceControlled</code> interface, which is a marker interface that is used to control which entities may modify a service's attribute set. For more information on this interface, refer to the <a href="schema-spec.html"><em>Jini Lookup Attribute Schema Specification</em>, Section LS.4.1, "Indicating User Modifiability"</a>. If the value of this flag is true and at least one of the attributes to be added is an instance of the <code>ServiceControlled</code> interface, a <code>SecurityException</code> will be thrown and propagated through this method.
+The second form of this method also takes as input a flag indicating whether or not this method should determine if the attributes in the input set are instances of the <code>ServiceControlled</code> interface, which is a marker interface that is used to control which entities may modify a service's attribute set. For more information on this interface, refer to the <a href="schema-spec.html"><em>River Lookup Attribute Schema Specification</em>, Section LS.4.1, "Indicating User Modifiability"</a>. If the value of this flag is true and at least one of the attributes to be added is an instance of the <code>ServiceControlled</code> interface, a <code>SecurityException</code> will be thrown and propagated through this method.
<p class="Body">
Note that because there is no guarantee that attribute propagation will have completed upon return from this method, services that invoke this method must take care not to modify the contents of the input array. Doing so could cause the service's attribute state to be corrupted or inconsistent on a subset of the lookup services with which the service is registered as compared with the state reflected on the remaining lookup services. It is for this reason that the effects of modifying the contents of the input array, after this method is invoked, are undefined.
<p class="Body">
@@ -279,7 +279,7 @@
<a name="1003738"> </a>For the same reason as noted above in the description of the <code>addAttributes</code> method, the effects of modifying the contents of the input array after the method <code>setAttributes</code> is invoked, are undefined.
</p>
<p class="Body">
- <a name="1000720"> </a>The <code>modifyAttributes</code> method changes the service's current set of attributes using the same semantics as the <code>modifyAttributes</code> method of the class <code>ServiceRegistration</code> (see the <a href="lookup-spec.html"><em class="Emphasis">Jini Technology Lookup Service Specification</em></a>). This method has two forms. The first form takes two arguments, the second form takes three arguments. Both forms will take an array of templates in the first argument and an array of attributes in the second argument. The templates are used to identify which elements to modify from the service's current set of attributes. If any element of the array of templates is <code>null</code>, a <code>NullPointerException</code> is thrown. The attribute array contains the actual modifications to be made. The additional argument in the signature of the second form of <code>modifyAttributes</code> is a flag indicating whether or not this method should
determine if the attributes in the input set are instances of the <code>ServiceControlled</code> interface, which is a marker interface used to control which entities may modify a service's attribute set (see the <a href="schema-spec.html#31204"><em class="Emphasis">Jini Lookup Attribute Schema Specification</em>, Section LS.4.1, "Indicating User Modifiability"</a>). If the value of this flag is true and at least one of the attributes to be modified is an instance of the <code>ServiceControlled</code> interface, a <code>SecurityException</code> will be thrown and propagated through this method.
+ <a name="1000720"> </a>The <code>modifyAttributes</code> method changes the service's current set of attributes using the same semantics as the <code>modifyAttributes</code> method of the class <code>ServiceRegistration</code> (see the <a href="lookup-spec.html"><em class="Emphasis">River Technology Lookup Service Specification</em></a>). This method has two forms. The first form takes two arguments, the second form takes three arguments. Both forms will take an array of templates in the first argument and an array of attributes in the second argument. The templates are used to identify which elements to modify from the service's current set of attributes. If any element of the array of templates is <code>null</code>, a <code>NullPointerException</code> is thrown. The attribute array contains the actual modifications to be made. The additional argument in the signature of the second form of <code>modifyAttributes</code> is a flag indicating whether or not this method shoul
d determine if the attributes in the input set are instances of the <code>ServiceControlled</code> interface, which is a marker interface used to control which entities may modify a service's attribute set (see the <a href="schema-spec.html#31204"><em class="Emphasis">River Lookup Attribute Schema Specification</em>, Section LS.4.1, "Indicating User Modifiability"</a>). If the value of this flag is true and at least one of the attributes to be modified is an instance of the <code>ServiceControlled</code> interface, a <code>SecurityException</code> will be thrown and propagated through this method.
</p>
<p class="Body">
<a name="1001414"> </a>The association of the new set of attributes with the service will be propagated to each lookup service with which the service is registered. This propagation must be performed asynchronously. Because of this asynchronous behavior, there is no guarantee that the propagation of the attributes to all lookup services with which the service is registered will have completed upon return from this method.
@@ -325,7 +325,7 @@
<a name="1000770"> </a>JU.5.1 The <code>DiscoveryManagement</code> Interface
</h4>
<p class="Body">
- <a name="1002984"> </a>Although it is not necessary for the <code>JoinManager</code> itself to execute the discovery process, it does need to be notified when one of the lookup services it wishes to join is discovered or discarded. Thus, at a minimum, the <code>JoinManager</code> requires access to the discovery events sent to the listeners registered with the discovery process' event mechanism. The instance of <code>DiscoveryManagement</code> that is passed as an argument to the constructor of the <code>JoinManager</code> provides a mechanism for acquiring access to those events. For a complete description of the semantics of the methods of this interface, refer to the <em class="Emphasis"><a href="discoveryutil-spec.html">Jini Discovery Utilities Specification</a></em>.
+ <a name="1002984"> </a>Although it is not necessary for the <code>JoinManager</code> itself to execute the discovery process, it does need to be notified when one of the lookup services it wishes to join is discovered or discarded. Thus, at a minimum, the <code>JoinManager</code> requires access to the discovery events sent to the listeners registered with the discovery process' event mechanism. The instance of <code>DiscoveryManagement</code> that is passed as an argument to the constructor of the <code>JoinManager</code> provides a mechanism for acquiring access to those events. For a complete description of the semantics of the methods of this interface, refer to the <em class="Emphasis"><a href="discoveryutil-spec.html">River Discovery Utilities Specification</a></em>.
</p>
<p class="Body">
<a name="1003002"> </a>One noteworthy item about the semantics of the <code>JoinManager</code> is the effect that invocations of the <code>discard</code> method of <code>DiscoveryManagement</code> will have on any discovery listeners created by the <code>JoinManager</code>. The <code>DiscoveryManagement</code> interface specifies that the <code>discard</code> method will remove a particular lookup service from the managed set of lookup services that have already been discovered, allowing that lookup service to be rediscovered. Invoking this method will result in the flushing of the lookup service from the appropriate cache, ultimately causing a discard notification to be sent to all <code>DiscoveryListener</code> objects registered with the event mechanism of the discovery process, including all listeners registered by the <code>JoinManager</code>.
@@ -407,7 +407,7 @@
<table width="100%">
<tr>
<td align=left><a href="../../spec-index.html">Spec Index</a>
-</td><td align=right><i>A Collection of Jini Technology Helper Utilities and Services Specifications</i></td>
+</td><td align=right><i>A Collection of River Technology Helper Utilities and Services Specifications</i></td>
</tr>
</table>
<a name="skip"></a>