You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@river.apache.org by bu...@apache.org on 2010/12/08 12:35:43 UTC
svn commit: r780268 [24/28] - in
/websites/staging/river/trunk/content/river/docs: ./ release-notes/ specs/
specs/images/
Added: websites/staging/river/trunk/content/river/docs/specs/mailbox-spec.html
==============================================================================
--- websites/staging/river/trunk/content/river/docs/specs/mailbox-spec.html (added)
+++ websites/staging/river/trunk/content/river/docs/specs/mailbox-spec.html Wed Dec 8 11:35:41 2010
@@ -0,0 +1,574 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<!--
+
+ 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.
+-->
+
+ <link href="/river/css/site.css" rel="stylesheet" type="text/css">
+ <link href="/river/css/type-settings.css" rel="stylesheet" type="text/css">
+
+ <title>Apache River - </title>
+
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+</head>
+<body>
+<div class="white_box">
+<div class="header">
+ <div class="header_l">
+ <div class="header_r">
+ </div>
+ </div>
+</div>
+<div class="content">
+ <div class="content_l">
+ <div class="content_r">
+ <div>
+
+<!-- Banner -->
+
+
+ <div id="header_background">
+ <div id="river_logo">
+ <a href="/river"><img src="/river/images/apache_river_v2b_small.png"/></a>
+<img src="/river/images/apache-incubator-logo.png"/>
+
+ </div>
+ </div>
+
+ <table border="0">
+ <tbody>
+ <tr>
+ <td style="overflow: hidden;" valign="top" width="100%">
+ <div class="wiki-content">
+<!--
+ ! 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.
+ !-->
+
+<html>
+
+<p><head>
+<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 Event Mailbox Service Specification </title>
+</head></p>
+<body bgcolor="#ffffff">
+
+<p> </p>
+
+<p><a href="#skip" title="Skip navigation bar"></a>
+<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>
+</tr>
+</table>
+<a name="skip"></a>
+<br clear="all"></p>
+<p><hr align="left">
+<table width="90%">
+<tr>
+<td align="right" font size="4"><b>Version 2.0</b></td>
+</tr>
+</table>
+<blockquote>
+<h2>
+ <a name="1005479"> </a>EM - Jini<font size="-1"><sup>TM</sup></font> Event Mailbox Service Specification
+</h2>
+<h3 class="Heading2">
+ <a name="1000110"> </a>EM.1 Introduction
+</h3>
+<p class="Body">
+ <a name="1001466"> </a>The <a href="event-spec.html"><em class="Emphasis">Jini<font size="-1"><sup>TM</sup></font> Distributed Events Specification</em></a> states the ability to interpose third-party objects, or "agents," into an event notification chain as one of its design goals. This specification also describes a notification mailbox object, which stores and forwards event notifications on behalf of other objects, as an example of a useful third-party agent. These mailbox objects can be particularly helpful for objects that need more control over how and when they receive event notifications.
+</p>
+<p class="Body">
+ <a name="1009565"> </a>For example, it would be impossible to send event notifications to a transient entity that has detached itself from a system of Jini<font size="-1"><sup>TM</sup></font> technology-enabled services and/or devices (<em class="Emphasis">Jini system</em>). In such a situation an entity could employ the services of an event mailbox to store event notifications on its behalf before leaving the system. Upon rejoining the Jini system, the entity could then contact the event mailbox to retrieve any collected events that it would otherwise have missed. Similarly, an entity that wishes to deactivate could use an event mailbox to collect event notifications on its behalf while dormant.
+</p>
+<p class="Body">
+ <a name="1005881"> </a>Like other Jini technology-enabled services (<em class="Emphasis">Jini services</em>), the event mailbox service will grant its services only for a limited period of time without an active expression of continuing interest. Therefore, event mailbox clients still need to renew their leases if they intend to maintain the mailbox's services beyond the initially granted lease period. Any resources (for example, remote objects or storage space) associated with a particular client can be freed once the client's lease has expired or been cancelled. In the previous usage scenarios, it might also benefit a transient or deactivatable entity to employ the services of a lease renewal service (see the <a href="lrs-spec.html"><em class="Emphasis">Jini Lease Renewal Service Specification</em></a>) to help mitigate the issue of lease maintenance.
+</p>
+<p class="Body">
+ <a name="1009032"> </a>The remainder of this specification defines the requirements, interfaces, and protocols of the event mailbox service.
+</p>
+<h4 class="Heading3">
+ <a name="1000115"> </a>EM.1.1 Goals and Requirements
+</h4>
+<p class="Body">
+ <a name="1000303"> </a>The requirements of the set of interfaces specified in this document are:
+</p>
+<ul></p>
+<p><li class="SmartList1"><a name="1000304"> </a>To define a service that is capable of storing event notifications on behalf of its clients and capable of delivering stored event notifications to those clients upon request<p>
+ <li class="SmartList1"><a name="1005900"> </a>To provide this service in such a way that it can be used by entities that are temporarily unable or unwilling to receive event notifications<p>
+ <li class="SmartList1"><a name="1000305"> </a>To provide a service that complies with the policies embodied in the Jini technology programming model
+</ul></p>
+<p class="Body">
+ <a name="1005921"> </a>The goals of this specification are:
+</p>
+
+<ul>
+
+<li class="SmartList1"><a name="1005926"> </a>To describe the event mailbox service<p>
+ <li class="SmartList1"><a name="1005931"> </a>To provide guidance in the use and deployment of the event mailbox service
+</ul>
+
+<h4 class="Heading3">
+ <a name="1000302"> </a>EM.1.2 Other Types
+</h4>
+
+<p class="Body">
+ <a name="1000008"> </a>The types defined in the specification of the event mailbox service are in the <code>net.jini.event</code> package. This specification assumes knowledge of the <a href="event-spec.html"><em class="Emphasis">Jini Distributed Events Specification</em></a> and the <a href="lease-spec.html"><em class="Emphasis">Jini Distributed Leasing Specification</em></a>. The following object types may be referenced in this chapter. Whenever referenced, these object types will be referenced in unqualified form:
+</p>
+<p class="Body">
+ <a name="1009048"> </a>
+</p>
+<pre class="Preformatted">
+java.rmi.NoSuchObjectException
+java.rmi.RemoteException
+net.jini.core.event.RemoteEvent
+net.jini.core.event.RemoteEventListener
+net.jini.core.lease.Lease
+net.jini.core.lease.LeaseDeniedException
+</pre>
+<h3 class="Heading2">
+ <a name="1001523"> </a>EM.2 The Interface
+</h3>
+<p class="Body">
+ <a name="1009792"> </a>The <code>EventMailbox</code> defines the interface to the event mailbox service. Through this interface, other Jini services and clients may request that event notification management be performed on their behalf. This interface belongs to the <code>net.jini.event</code> package, and any service implementing this interface must comply with the definition of a Jini service. This interface is not a remote interface; each implementation exports a proxy object that implements this interface local to the client, using an implementation-specific protocol to communicate with the actual remote server. All of the proxy methods obey normal Java<font size="-1"><sup>TM</sup></font> Remote Method Invocation (Java RMI) interface semantics and can therefore be implemented directly using Java RMI (except where explicitly noted). Two proxy objects are equal (using the <code>equals</code> method) if they are proxies for the same event mailbox service.
+</p>
+
+<pre class="Preformatted">
+package net.jini.event;
+
+public interface EventMailbox
+{
+ MailboxRegistration register(long leaseDuration)
+ throws RemoteException, LeaseDeniedException;
+}
+</pre>
+<p class="Body">
+ <a name="1002029"> </a>
+</p>
+<p class="Body">
+ <a name="1009773"> </a>Event mailbox clients wishing to use the mailbox service first register themselves with the service using the <code>register</code> method. Clients then use the methods of the returned <code>MailboxRegistration</code> object (a <em class="Emphasis">registration</em>) in order to:
+</p>
+<ul>
+
+<p><li class="SmartList1"><a name="1006019"> </a>Manage the lease for this particular registration<p>
+ <li class="SmartList1"><a name="1006024"> </a>Obtain a <code>RemoteEventListener</code> reference that can be registered with <em class="Emphasis">event generators</em> (that is, objects that support event notification for changes in their abstract state). This listener will store any received notifications for this particular registration.<p>
+ <li class="SmartList1"><a name="1006029"> </a>Enable or disable the delivery of any stored notifications for this particular registration
+</ul></p>
+<h3 class="Heading2">
+ <a name="1002030"> </a>EM.3 The Semantics
+</h3>
+<p class="Body">
+ <a name="1009820"> </a>To employ the event mailbox service, a client must first register with the event mailbox service by invoking the <code>EventMailbox</code> interface's only method, <code>register</code>. Each invocation of the <code>register</code> method produces a new registration.
+</p>
+<p class="Body">
+ <a name="1009847"> </a>The <code>register</code> method may throw a <code>RemoteException</code> or a <code>LeaseDeniedException</code>. Typically, a <code>RemoteException</code> occurs when there is a communication failure between the client and the event mailbox service. If this exception does occur, the registration may or may not have been successful. A <code>LeaseDeniedException</code> is thrown if the event mailbox service is unable or unwilling to grant the registration request. It is implementation specific as to whether or not subsequent attempts (with or without the same argument) are likely to succeed.
+</p>
+<p class="Body">
+ <a name="1001539"> </a>Each registration with the event mailbox service is persistent across restarts or crashes of the event mailbox service, until the lease on the registration expires or is cancelled.
+</p>
+<p class="Body">
+ <a name="1001803"> </a>The <code>register</code> method takes a single parameter of type <code>long</code> that represents the requested initial lease duration for the registration, in milliseconds. This duration value must be positive (except for the special value of <code>Lease.ANY</code>). Otherwise, an <code>IllegalArgumentException</code> is thrown.
+</p>
+<p class="Body">
+ <a name="1008949"> </a>Every method invocation on an event mailbox service (whether the invocation is directly on the service, or indirectly on a <code>MailboxRegistration</code> that the service has created) is atomic with respect to other invocations.
+</p>
+<p class="Body">
+ <a name="1008947"> </a>
+</p>
+<h3 class="Heading2">
+ <a name="1009616"> </a>EM.4 Supporting Interfaces and Classes
+</h3>
+
+<p class="Body">
+ <a name="1009617"> </a>The <code>register</code> method returns an object that implements the interface <code>MailboxRegistration</code>. It is through this interface that the client controls its registration and notification management with the event mailbox service.
+</p>
+
+<pre class="Preformatted">
+package net.jini.event;
+
+public interface MailboxRegistration
+{
+ Lease getLease();
+ RemoteEventListener getListener();
+ void enableDelivery(RemoteEventListener target)
+ throws RemoteException;
+ void disableDelivery() throws RemoteException;
+}
+</pre>
+<p class="Body">
+ <a name="1002176"> </a>The <code>MailboxRegistration</code> interface is not a remote interface. Each implementation of the event mailbox service exports proxy objects that implement this interface local to the client. These proxies use an implementation-specific protocol to communicate with the remote server. All of the remote proxy methods obey normal Java RMI interface semantics and can therefore be implemented using Java RMI. Two proxy objects are equal (using the <code>equals</code> method) if they are proxies for the same registration, created by the same event mailbox service.
+</p>
+<p class="Body">
+ <a name="1002187"> </a>Each remote method of this interface may throw a <code>RemoteException</code>. Typically, this exception occurs when there is a communication failure between the client and the event mailbox service. Whenever a method invocation results in a <code>RemoteException</code>, the method may or may not have successfully completed.
+</p>
+<p class="Body">
+ <a name="1006083"> </a>Any invocation of a remote method defined in this interface will result in a <code>NoSuchObjectException</code> if the client's registration with the event mailbox service has expired or has been cancelled. Note that upon receipt of a <code>NoSuchObjectException</code>, the client can assume that the registration no longer exists; the client cannot assume that the event mailbox service itself no longer exists.
+</p>
+<h4 class="Heading3">
+ <a name="1006088"> </a>EM.4.1 The Semantics
+</h4>
+<p class="Body">
+ <a name="1009632"> </a>The <code>getLease</code> method returns the <code>Lease</code> object associated with the registration. The client can renew or cancel the registration with the mailbox service through the <code>Lease</code> object returned by this method (see the <a href="lease-spec.html"><em class="Emphasis">Jini Distributed Leasing Specification</em></a>). This method is not remote and takes no arguments.
+</p>
+<p class="Body">
+ <a name="1006102"> </a>The <code>getListener</code> method returns an object that implements the interface <code>RemoteEventListener</code>. This object, referred to as a <em class="Emphasis">mailbox listener</em>, can then be submitted as the <code>RemoteEventListener</code> argument to an event generator's registration method(s) (see the <a href="event-spec.html"><em class="Emphasis">Jini Distributed Events Specification</em></a>). Subsequent calls to this method will return equivalent objects (in the <code>equals</code> sense). Note that mailbox listeners generated by different registrations will not be equal. This method is not remote and takes no arguments.
+</p>
+<p class="Body">
+ <a name="1006111"> </a>The valid period of use for a mailbox listener is tied to the associated registration's lease. A <code>NoSuchObjectException</code> will be thrown if an attempt is made to invoke the <code>notify</code> method on a mailbox listener whose associated lease has terminated.
+</p>
+<p class="Body">
+ <a name="1006116"> </a>Mailbox listener references, just like their associated registrations, are persistent across server restarts or crashes until their associated registration's lease terminates.
+</p>
+<p class="Body">
+ <a name="1006123"> </a>The <code>enableDelivery</code> method allows a client to initiate delivery of event notifications (received on its behalf by this particular registration) to the client-specified listener, referred to as the <em class="Emphasis">target listener</em>. This method takes a single argument of type <code>RemoteEventListener</code>. Subsequent calls to this method simply replace the registration's existing target listener, if any, with the specified target listener. Passing <code>null</code> as the listener argument has the same effect as disabling delivery (see below).
+</p>
+<p class="Body">
+ <a name="1006135"> </a>Resubmitting a mailbox listener back to the same mailbox service that generated it will result in an <code>IllegalArgumentException</code> being thrown. This is necessary to prevent a recursive event notification chain. Therefore, the event mailbox service must keep track of any listener objects that it generates and reject the resubmission of those objects.
+</p>
+<p class="Body">
+ <a name="1006124"> </a>Once enabled, event delivery remains enabled until it is disabled. Any events received while delivery is enabled will also be scheduled for delivery.
+</p>
+<p class="Body">
+ <a name="1006145"> </a>Event delivery guarantees with respect to exception handling, ordering, and concurrency are implementation specific and are not specified in this document. However, implementations are encouraged to support the following functionality. If an event delivery attempt produces an exception that indicates future attempts might be successful (an indefinite exception), then reasonable efforts should be made to successfully redeliver the event until the associated registration's lease terminates. On the other hand, if an event delivery attempt produces an exception that indicates future attempts will be unsuccessful (a definite exception), then event delivery should be disabled for the associated registration until it is explicitly enabled again.
+</p>
+<p>
+The algorithm used to classify exceptions as definite or indefinite is implementation specific.
+</p>
+<p class="Body">
+ <a name="1009346"> </a>Also, implementations may concurrently deliver event notifications to the same target listener, which implies that events may be sent in a different order than the order in which they were originally received. Hence, it is the target listener's responsibility to guard against potential concurrent, out-of-order event delivery.
+</p>
+<p class="Body">
+ <a name="1006146"> </a>Similarly, implementations are encouraged to support this method's intended semantics regarding listener replacement. That is, a mailbox client can reasonably assume that listener replacement has occurred upon successful return from this method and can therefore safely unexport the previous listener object. This also implies that any in-progress delivery attempts to the previous listener are either successfully cancelled before returning from this method (blocking), or subsequently retried using the replacement listener after returning from this method (non-blocking). Note that the non-blocking case can potentially allow the previous listener to be notified after successfully returning from this method.
+</p>
+<p class="Body">
+ <a name="1006158"> </a>The <code>disableDelivery</code> method allows the client to cease event delivery to the existing target listener, if any. It is acceptable to call this method even if no target listener is currently enabled. This method takes no arguments.
+</p>
+<p class="Body">
+ <a name="1006159"> </a>Again, event delivery guarantees are implementation specific and are not specified in this document. Implementations are encouraged to support the method's intended semantics regarding delivery suspension. That is, a mailbox client can reasonably assume that event delivery has been suspended upon successful return from this method and can therefore safely unexport the previously enabled listener object if desired. This also implies that any in-progress delivery attempts to the previously enabled listener are either successfully cancelled before returning from this method (blocking), or subsequently retried using the next enabled listener after returning from this method (non-blocking). Note that the non-blocking case can potentially allow the previously enabled listener to be notified after successfully returning from this method.
+</p>
+<p class="Body">
+ <a name="1006161"> </a>The event mailbox service does not normally concern itself with the attributes of the <code>RemoteEvent</code>s that it receives. The one circumstance about which it must concern itself is when a target listener throws an <code>UnknownEventException</code> during an event delivery attempt. The event mailbox service must maintain a list, on a per-registration basis, of the particular combinations of event identifier and source reference (obtained from the offending <code>RemoteEvent</code> object) that produced the exception. The event mailbox must then propagate an <code>UnknownEventException</code> back to any event generator that attempts to deliver a <code>RemoteEvent</code> with an identifier-source combination held in a registration's unknown exception list. The service will also skip the future delivery of any stored events that have an identifier-source combination held in this list.
+</p>
+<p class="Body">
+ <a name="1009476"> </a>A registration's unknown exception list is cleared upon re-enabling delivery with any target listener. This list is persistent across service restarts or crashes, until the associated registration's lease terminates.
+</p>
+<p class="Body">
+ <a name="1009474"> </a>Note that the act of comparing event source objects for equality may pose a security risk because source objects are potentially given references to other source objects that are currently using the same mailbox. If security is a concern, then care should be taken to prevent independent event sources from obtaining information about each other, for example by using a separate mailbox for each source.
+</p>
+<p class="Body">
+ <a name="1006191"> </a>The event mailbox does not support multiple, concurrent notification targets per registration. As a result, the interface supports only a set/clear model rather than the more common add/remove model.
+</p>
+<p class="Body">
+ <a name="1009395"> </a>Event persistence guarantees are not specified in this document because no single policy can cover all the possible design trade-offs between reliability, efficiency, and performance. It is expected that operational parameters--controls for how the event mailbox deals with issues such as persistence guarantees, storage quotas, and low space behavior--will be exposed through an administration interface, which can vary across different event mailbox implementations.
+</p>
+<h3 class="Heading2">
+ <a name="1009616"> </a>EM.5 The Interface
+</h3>
+<p class="Body">
+The <code>PullEventMailbox</code> defines the interface to the pull event mailbox service (the mailbox service). Through this interface, other Jini technology-enabled services and clients may request that event notification management be performed on their behalf. This interface belongs to the <code>net.jini.event</code> package. This interface is not a remote interface; each implementation exports a proxy object that implements this interface local to the client, using an implementation-specific protocol to communicate with the actual remote server. All of the proxy methods obey normal Java RMI interface semantics and can therefore be implemented directly using Java RMI. Two proxy objects are equal (using the <code>equals</code> method) if they are proxies for the same mailbox service.
+<pre>
+package net.jini.event;
+
+<p>public interface PullEventMailbox extends EventMailbox
+{
+ MailboxPullRegistration pullRegister(long leaseDuration)
+ throws RemoteException, LeaseDeniedException;
+}</p>
+<p></pre>
+<p class="Body">
+Clients wishing to use the mailbox service first register themselves with the service using the <code>pullRegister</code> method. Clients then use the methods of the returned <code>MailboxPullRegistration</code> object (a registration) to:
+<UL>
+<LI>Manage the lease for this particular registration.
+<LI>Obtain a <code>RemoteEventListener</code> reference that can be registered with event generators (that is, objects that support event notification for changes in their abstract state). This listener will store event notifications on behalf of this particular registration.
+<LI>Synchronously or asynchronously collect any event notifications stored by this particular registration.
+</UL>
+<h3 class="Heading2">
+ <a name="2031"> </a>EM.6 The Semantics
+</h3>
+<p class="Body">
+To employ the mailbox service, a client must first register with the mailbox service by invoking the <code>pullRegister</code> method. Each invocation of the <code>pullRegister</code> method produces a new registration object. Each registration is persistent across restarts or crashes of the mailbox service until the registration's lease expires or is canceled.
+<p class="Body">
+The <code>pullRegister</code> method takes a single parameter of type <code>long</code> that represents the requested initial lease duration for the registration, in milliseconds. This duration value must be positive (except for the special value of <code>Lease.ANY</code>). Otherwise, an <code>IllegalArgumentException</code> is thrown.
+<p class="Body">
+The <code>pullRegister</code> method may throw a <code>RemoteException</code> or a <code>LeaseDeniedException</code>. Typically, a <code>RemoteException</code> occurs when there is a communication failure between the client and the event mailbox service. If this exception does occur, the registration may or may not have been successful. A <code>LeaseDeniedException</code> is thrown if the mailbox service is unable or unwilling to grant the registration request. If <code>LeaseDeniedException</code> is thrown, it is implementation specific as to whether or not subsequent attempts (with the same or a different argument value) are likely to succeed.
+<p class="Body">
+Every method invocation on a mailbox service (whether the invocation is directly on the service, or indirectly on a registration that the service has created) is atomic with respect to other invocations.</p>
+<h3 class="Heading2">
+ <a name="2032"> </a>EM.7 Supporting Interfaces and Classes
+</h3>
+
+<p class="Body">
+The <code>pullRegister</code> method returns an object that implements the <code>MailboxPullRegistration</code> interface. It is through this interface that the client controls its registration and notification management with the mailbox service.
+
+</p>
+<pre class="Preformatted">
+package net.jini.event;
+
+public interface MailboxPullRegistration extends
+ MailboxRegistration
+{
+ RemoteEventIterator getRemoteEvents()
+ throws RemoteException;
+ void addUnknownEvents(Collection unknownEvents)
+ throws RemoteException;
+}
+public interface RemoteEventIterator
+{
+ RemoteEvent next(long timeout)
+ throws RemoteException, InvalidIteratorException;
+ void close() throws InvalidIteratorException;
+}
+public class InvalidIteratorException extends Exception
+{
+ public InvalidIteratorException(String reason);
+ public InvalidIteratorException();
+}
+</pre>
+<p class="Body">
+The <code>MailboxPullRegistration</code> and the <code>RemoteEventIterator</code> interfaces are not remote interfaces. Each implementation of the mailbox service exports proxy objects that implement these interfaces locally to the client. These proxies use an implementation-specific protocol to communicate with the remote server. All of the remote proxy methods obey normal Java RMI interface semantics and can therefore be implemented using Java RMI. Two proxy objects are equal (using the <code>equals</code> method) if they are proxies for the same registration, created by the same mailbox service.
+<p class="Body">
+Each remote method of these interfaces may throw a <code>RemoteException</code>. Typically, this exception occurs when there is a communication failure between the client and the mailbox service. Whenever a method invocation results in a <code>RemoteException</code>, the method may or may not have successfully completed.
+<p class="Body">
+Any invocation of a remote method defined in this interface will result in a <code>NoSuchObjectException</code> if the client's registration with the mailbox service has expired or has been canceled. Note that upon receipt of a <code>NoSuchObjectException</code>, the client can assume that the registration no longer exists; the client cannot assume that the mailbox service itself no longer exists.
+<h4 class="Heading3">
+ <a name="20321"> </a>EM.7.1 The Semantics
+</h4>
+
+<p class="Body">
+The <code>getRemoteEvents</code> method returns a <code>RemoteEventIterator</code> object (an iterator) associated with the registration. The client can retrieve event notifications (received on its behalf by this particular registration) from the mailbox service through the iterator returned by this method.
+
+<p class="Body">
+Each invocation of the <code>getRemoteEvents</code> method produces a new iterator. Each new iterator will invalidate all previous iterators produced by the same registration. An invalidated iterator's methods must eventually throw an <code>InvalidIteratorException</code> to indicate this condition.
+
+<p class="Body">
+Calling <code>getRemoteEvents</code> also effectively calls <code>disableDelivery</code> for the associated registration. This will disable the registration's associated target listener, if any. Conversely, calling <code>enableDelivery</code> will, in turn, invalidate any existing iterators produced by the same registration.
+
+<p class="Body">
+If the combination of the event identifier and the event generator's object reference obtained from an event object is not one in which the mailbox client has registered an interest, an <code>UnknownEventException</code> should be propagated back to the event generator. This is accomplished by calling <code>addUnknownEvents</code> with a collection of unknown events. The effects of modifying the collection of unknown events during a call to <code>addUnknownEvents</code> are undefined.
+
+<p class="Body">
+The mailbox service will maintain a list of unknown events, on a per-registration basis, with the particular combinations of event identifier and source reference (obtained from the provided event objects). The mailbox should then propagate an <code>UnknownEventException</code> back to any event generator that attempts to deliver an event with an identifier-source combination held in a registration's unknown exception list. The valid iterator associated with the registration should also eventually skip the future delivery of any stored events that have an identifier-source combination held in this list.
+
+<p class="Body">
+A registration's unknown exception list is persistent across service restarts or crashes, until the associated registration's lease terminates or is cleared by subsequent calls to either <code>enableDelivery</code> or <code>getRemoteEvents</code>.
+
+<p class="Body">
+<code>RemoteEventIterator</code>'s next method returns either an event from the registration's set of events (event set) or <code>null</code> if the event set is empty. This method takes a single argument of type <code>long</code>, which is the maximum time, in milliseconds, to wait for an event to become available in the event set. This argument must be a non-negative number or an <code>IllegalArgumentException</code> will be thrown. An iterator will not redeliver an event once it has been successfully returned from that iterator.
+
+<p class="Body">
+In general, events may be transferred to the client during or after the <code>getRemoteEvents</code> call. If there are <code>InvocationConstraints</code> associated with the <code>getRemoteEvents</code> call, then all of the events returned by <code>next</code> will be transferred in a way that meets those constraints. In particular, any constraints associated with the <code>next</code> method are ignored. The <code>next</code> method may return events after the associated registration lease has expired.
+
+<p class="Body">
+The <code>next</code> method may throw an <code>InvalidIteratorException</code>. An <code>InvalidIteratorException</code> is thrown if <code>enableDelivery</code> was subsequently called for this registration, a new iterator was subsequently generated for this registration, or the iterator was closed. Subsequent invocations (with the same or different argument value) will also fail with the same exception once an iterator throws <code>InvalidIteratorException</code>.
+
+<p class="Body">
+Calling <code>close</code> ends all event processing being performed by the iterator and invalidates the iterator. Subsequent iterator method invocations will also throw <code>InvalidIteratorException</code>. Any additional termination semantics must be defined by the implementation class itself.
+
+<h3 class="Heading2">
+ <a name="2034"> </a>EM.8 History
+</h3>
+<p>
+<table align="center" border="1" bordercolorlight="#FFFFFF" bordercolordark="#000000" cellpadding="5" cellspacing="0" summary="history of this specification">
+ <caption><p class="Body">
+ <a name="01887"> </a>
+</p>
+</caption>
+ <tr bgcolor="#CCCCCC">
+ <th>Version</th>
+ <th>Description</th>
+ </tr>
+<tr>
+ <td>v1.0</td>
+ <td>Initial release of this specification.</td>
+</tr>
+<tr>
+ <td>v2.0</td>
+ <td>Added "pull" semantics to mailbox specification (sections EM.5 through EM.8)<br>
+ Changed titles for former "Core" specifications</td>
+</tr>
+</table>
+<h3 class="Heading2">
+ <a name="0188"> </a> License
+</h3>
+<p>
+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.
+</blockquote>
+
+<p><hr>
+<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><i>A Collection of Jini Technology Helper Utilities and Services Specifications</i></td>
+</tr></table>
+<a name="skip"></a></p>
+<p><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.</p>
+<p></body>
+</html></p>
+<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
+<!-- by Susan Snyder -->
+<!-- Last updated: 01/27/05 -->
+ </div>
+ </td>
+ <td valign="top">
+ <div class="navigation">
+ <div class="navigation_top">
+ <div class="navigation_bottom">
+<!-- sidenav -->
+<ul>
+<li><a href="index.html">Home</a></li>
+<li><a href="news.html">News</a></li>
+</ul>
+<h3 id="community">Community</h3>
+<ul>
+<li><a href="supported-platforms.html">Supported platforms</a></li>
+<li><a href="get-involved.html">Get Involved</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li>
+<li><a href="downloads.html">Downloads</a></li>
+<li>Documentation<ul>
+<li><a href="http://people.apache.org/~sijskes/doc/index.html">Original Jini Wiki</a></li>
+<li><a href="user-guide-glossary.html">Glossary</a></li>
+<li><a href="documentation.html">Cookbook</a></li>
+<li><a href="javadoc.html">Javadoc</a></li>
+</ul>
+</li>
+<li><a href="success-stories.html">Success Stories</a></li>
+<li><a href="mailing-lists.html">Mailing Lists</a></li>
+<li><a href="committers.html">Committers</a></li>
+<li><a href="found-a-bug.html">Found a Bug</a>?</li>
+</ul>
+<h3 id="development">Development</h3>
+<ul>
+<li><a href="javadoc.html">Javadoc</a></li>
+<li><a href="source-code.html">Source Code</a></li>
+<li><a href="building-river.html">Building River</a></li>
+<li><a href="roadmap.html">Roadmap</a></li>
+<li><a href="development-process.html">Development Process</a></li>
+<li><a href="https://issues.apache.org/jira/browse/RIVER">Issue Tracker</a></li>
+<li><a href="http://wiki.apache.org/river/">Wiki</a></li>
+</ul>
+<h3 id="search">Search</h3>
+<DIV>
+<FORM action="http://www.google.com/search" method="get" style="font-size: 10px;">
+<INPUT name="ie" type="hidden" value="UTF-8"></INPUT>
+<INPUT name="oe" type="hidden" value="UTF-8"></INPUT>
+ <INPUT maxlength="255" name="q" size="15" type="text" value></INPUT><BR></BR>
+ <INPUT name="btnG" type="submit" value="Search"></INPUT>
+ <INPUT name="domains" type="hidden" value="incubator.apache.org/river"></INPUT>
+ <INPUT name="sitesearch" type="hidden" value="incubator.apache.org/river"></INPUT>
+</FORM>
+</DIV>
+
+<ul>
+<li><a href="sitemap.html">Sitemap</a></li>
+</ul>
+<h3 id="the_foundation">The Foundation</h3>
+<ul>
+<li><a href="http://www.apache.org">Apache</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">Sponsors</a></li>
+<li><a href="http://www.apache.org/foundation/how-it-works.html">How it works</a></li>
+<li><a href="http://incubator.apache.org/">Incubator</a></li>
+</ul>
+<!-- sidenav -->
+ </div>
+ </div>
+ </div>
+ </td>
+ </tr>
+ </tbody>
+ </table>
+
+<!--
+ <div class="bottom_red_bar"></div>
+-->
+ </div>
+ </div>
+ </div>
+</div>
+<div class="black_box">
+<div class="footer">
+ <div class="footer_l">
+ <div class="footer_r">
+ <div>
+
+ </div>
+ </div>
+ </div>
+</div>
+</div>
+</div>
+<!--
+<div class="design_attribution">Page Template Design By Marc Prud'hommeaux based on <a href="http://activemq.apache.org/">ActiveMQ template</a></div>
+-->
+<div class="copyright_footer">
+<p>Copyright © 2010 The Apache Software Foundation, Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br>Apache and the Apache feather logo are trademarks of The Apache Software Foundation.</p>
+</div>
+<script src="skeleton_files/urchin.js" type="text/javascript">
+</script>
+<script type="text/javascript">
+_uacct = "UA-1940143-1";
+urchinTracker();
+</script>
+
+</body></html>
Added: websites/staging/river/trunk/content/river/docs/specs/schema-spec.html
==============================================================================
--- websites/staging/river/trunk/content/river/docs/specs/schema-spec.html (added)
+++ websites/staging/river/trunk/content/river/docs/specs/schema-spec.html Wed Dec 8 11:35:41 2010
@@ -0,0 +1,867 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<!--
+
+ 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.
+-->
+
+ <link href="/river/css/site.css" rel="stylesheet" type="text/css">
+ <link href="/river/css/type-settings.css" rel="stylesheet" type="text/css">
+
+ <title>Apache River - </title>
+
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+</head>
+<body>
+<div class="white_box">
+<div class="header">
+ <div class="header_l">
+ <div class="header_r">
+ </div>
+ </div>
+</div>
+<div class="content">
+ <div class="content_l">
+ <div class="content_r">
+ <div>
+
+<!-- Banner -->
+
+
+ <div id="header_background">
+ <div id="river_logo">
+ <a href="/river"><img src="/river/images/apache_river_v2b_small.png"/></a>
+<img src="/river/images/apache-incubator-logo.png"/>
+
+ </div>
+ </div>
+
+ <table border="0">
+ <tbody>
+ <tr>
+ <td style="overflow: hidden;" valign="top" width="100%">
+ <div class="wiki-content">
+<!--
+ ! 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.
+ !-->
+
+<html>
+
+<p><head>
+<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 Lookup Attribute Schema Specification </title>
+</head></p>
+<body bgcolor="#ffffff">
+
+<p><a href="#skip" title="Skip navigation bar"></a>
+<table width="100%">
+<tr>
+<td align=left><a href="../../spec-index.html">Spec Index</a></td>
+<td align=right><em>A Collection of Jini Technology Helper Utilities and Services Specifications</em></td>
+</tr>
+</table>
+<br clear="all"></p>
+<p><hr align="left">
+<table width="90%">
+<tr>
+<td align="right" font size="4"><b>Version 1.0</b></td>
+</tr>
+</table>
+<a name="skip"></a>
+<blockquote>
+<h2><a name="7185"></a>LS - Jini<font size="-1"><sup>TM</sup></font> Lookup Attribute Schema Specification</h2>
+<h3 class="Heading2">
+ <a name="7186"> </a>LS.1 Introduction <br />
+</h3>
+<p class="Body">
+ <a name="3780"> </a>The Jini<font size="-1"><sup>TM</sup></font> lookup service provides facilities for services to advertise their availability and for would-be clients to obtain references to those services based on the attributes they provide. The mechanism that it provides for registering and querying based on attributes is centered on the Java<font size="-1"><sup>TM</sup></font> platform type system, and is based on the notion of an <em class="Emphasis">entry.</em>
+</p>
+<p class="Body">
+ <a name="3751"> </a>An entry is a class that contains a number of public fields of object type. Services provide concrete values for each of these fields; each value acts as an attribute. Entries thus provide aggregation of attributes into sets; a service may provide several entries when registering itself in the lookup service, which means that attributes on each service are provided in a set of sets.
+</p>
+<p class="Body">
+ <a name="3758"> </a>The purpose of this document is to provide a framework in which services and their would-be clients can interoperate. This framework takes two parts:
+</p>
+<ul></p>
+<p><li class="SmartList1"><a name="3768"> </a>We describe a set of common predefined entries that span much of the basic functionality that is needed both by services registering themselves and by entities that are searching for services.<p>
+ <li class="SmartList1"><a name="3776"> </a>Since we cannot anticipate all of the future needs of clients of the lookup service, we provide a set of guidelines and design patterns for extending, using, and imitating this set in ways that are consistent and predictable. We also construct some examples that illustrate the use of these patterns.
+</ul></p>
+<h4 class="Heading3">
+ <a name="3779"> </a>LS.1.1 Terminology
+</h4>
+
+<p class="Body">
+ <a name="3781"> </a>Throughout this document, we will use the following terms in consistent ways:
+</p>
+
+<ul>
+
+<li class="SmartList1"><a name="3782"> </a><em class="Emphasis">Service</em>--a service that has registered, or will register, itself with the lookup service<p>
+ <li class="SmartList1"><a name="3787"> </a><em class="Emphasis">Client</em>--an entity that performs queries on the lookup service, in order to find particular services
+</ul>
+
+<h4 class="Heading3">
+ <a name="3811"> </a>LS.1.2 Design Issues
+</h4>
+
+<p class="Body">
+ <a name="3812"> </a>Several factors influence and constrain the design of the lookup service schema.
+</p>
+<div style="color: #000000; font-family: Times; font-size: 11pt; font-style: normal; font-weight: bold; margin-bottom: 8pt; margin-left: 36pt; margin-right: 0pt; margin-top: 13pt; text-align: left; text-decoration: none; text-indent: -36pt; text-transform: none; vertical-align: baseline">
+<a name="3817"> </a>Matching Cannot Always Be Automated<br>
+</div>
+<p class="Body">
+ <a name="3820"> </a>No matter how much information it has at its disposal, a client of the lookup service will not always be able to find a single unique match without assistance when it performs a lookup. In many instances we expect that more than one service will match a particular query. Accordingly, both the lookup service and the attribute schema are geared toward reducing the number of matches that are returned on a given lookup to a minimum, and not necessarily to just one.
+</p>
+<div style="color: #000000; font-family: Times; font-size: 11pt; font-style: normal; font-weight: bold; margin-bottom: 8pt; margin-left: 36pt; margin-right: 0pt; margin-top: 13pt; text-align: left; text-decoration: none; text-indent: -36pt; text-transform: none; vertical-align: baseline">
+<a name="3821"> </a>Attributes Are Mostly Static<br>
+</div>
+<p class="Body">
+ <a name="3824"> </a>We have designed the schema for the lookup service with the assumption that most attributes will not need to be changed frequently. For example, we do not expect attributes to change more often than once every minute or so. This decision is based on our expectation that clients that need to make a choice of service based on more frequently updated attributes will be able to talk to whatever small set of services the lookup service returns for a query, and on our belief that the benefit of updating attributes frequently at the lookup service is outweighed by the cost in network traffic and processing.
+</p>
+<div style="color: #000000; font-family: Times; font-size: 11pt; font-style: normal; font-weight: bold; margin-bottom: 8pt; margin-left: 36pt; margin-right: 0pt; margin-top: 13pt; text-align: left; text-decoration: none; text-indent: -36pt; text-transform: none; vertical-align: baseline">
+<a name="3834"> </a>Humans Need to Understand Most Attributes<br>
+</div>
+<p class="Body">
+ <a name="3835"> </a>A corollary of the idea that matching cannot always be automated is that humans--whether they be users or administrators of services--must be able to understand and interpret attributes. This has several implications:
+</p>
+
+<ul>
+
+<li class="SmartList1"><a name="3840"> </a>We must provide a mechanism to deal with localization of attributes<p>
+ <li class="SmartList1"><a name="3847"> </a>Multiple-valued attributes must provide a way for humans to see only one value (see <a href="schema-spec.html#7189">Section LS.2, "Human Access to Attributes"</a>)
+</ul>
+
+<p class="Body">
+ <a name="3848"> </a>We will cover human accessibility of attributes soon.
+</p>
+<div style="color: #000000; font-family: Times; font-size: 11pt; font-style: normal; font-weight: bold; margin-bottom: 8pt; margin-left: 36pt; margin-right: 0pt; margin-top: 13pt; text-align: left; text-decoration: none; text-indent: -36pt; text-transform: none; vertical-align: baseline">
+<a name="3857"> </a>Attributes Can Be Changed by Services or Humans, But Not Both<br>
+</div>
+<p class="Body">
+ <a name="3860"> </a>For any given attribute class we expect that attributes within that class will all be set or modified either by the service, or via human intervention, but not both. What do we mean by this? A service is unlikely to be able to determine that it has been moved from one room to another, for example, so we would not expect the fields of a "location" attribute class to be changed by the service itself. Similarly, we do not expect that a human operator will need to change the name of the vendor of a particular service. This idea has implications for our approach to ensuring that the values of attributes are valid.
+</p>
+<div style="color: #000000; font-family: Times; font-size: 11pt; font-style: normal; font-weight: bold; margin-bottom: 8pt; margin-left: 36pt; margin-right: 0pt; margin-top: 13pt; text-align: left; text-decoration: none; text-indent: -36pt; text-transform: none; vertical-align: baseline">
+<a name="3880"> </a>Attributes Must Interoperate with JavaBeans<font size="-1"><sup>TM</sup></font> Components<br>
+</div>
+<p class="Body">
+ <a name="3881"> </a>The JavaBeans<font size="-1"><sup>TM</sup></font> specification provides a number of facilities relating to the localized display and modification of properties, and has been widely adopted. It is to our advantage to provide a familiar set of mechanisms for manipulating attributes in these ways.
+</p>
+<h4 class="Heading3">
+ <a name="3937"> </a>LS.1.3 Dependencies
+</h4>
+<p class="Body">
+ <a name="3938"> </a>This document relies on the following other specifications:
+</p>
+
+<ul>
+
+<li class="SmartList1"><a name="3940"> </a><a href="entry-spec.html"><em class="Emphasis">Jini Entry Specification</em></a> <p>
+ <li class="SmartList1"><a name="3961"> </a><a href="http://www.jini.org/standards"><em class="Emphasis"><code>net.jini.entry</code> Specification</em></a> <p>
+ <li class="SmartList1"><a name="3942"> </a><em class="Emphasis">JavaBeans</em><font size="-1"><sup>TM</sup></font><em class="Emphasis"> Specification</em>
+</ul>
+
+<h3 class="Heading2">
+ <a name="7189"> </a>LS.2 Human Access to Attributes
+</h3>
+
+<h4 class="Heading3">
+ <a name="7190"> </a>LS.2.1 Providing a Single View of an Attribute's Value
+</h4>
+
+<p class="Body">
+ <a name="7191"> </a>Consider the following entry class:
+</p>
+
+<pre class="Preformatted">
+public class Foo implements net.jini.core.entry.Entry {
+ public Bar baz;
+}
+
+public class Bar {
+ int quux;
+ boolean zot;
+}
+</code></pre>
+<p class="Body">
+ <a name="10587"> </a>A visual search tool is going to have a difficult time rendering the value of an instance of class <code>Bar</code> in a manner that is comprehensible to humans. Accordingly, to avoid such situations, entry class implementors should use the following guidelines when designing a class that is to act as a value for an attribute:
+</p>
+<ul>
+
+<p><li class="SmartList1"><a name="7201"> </a>Provide a property editor class of the appropriate type, as described in Section 9.2 of the <em class="Emphasis">JavaBeans Specification</em>.<p>
+ <li class="SmartList1"><a name="31176"> </a>Extend the <code>java.awt.Component</code> class; this allows a value to be represented by a JavaBeans component or some other "active" object.<p>
+ <li class="SmartList1"><a name="31177"> </a>Provide either a non-default implementation of the <code>Object.toString</code> method or inherit directly or indirectly from a class that does so (since the default implementation of <code>Object.toString </code>is not useful).
+</ul></p>
+<p class="Body">
+ <a name="7204"> </a>One of the above guidelines should be followed for all attribute value classes. Authors of entry classes should assume that any attribute value that does not satisfy one of these guidelines will be ignored by some or all user interfaces.
+</p>
+<h3 class="Heading2">
+ <a name="7212"> </a>LS.3 JavaBeans Components and Design Patterns
+</h3>
+<h4 class="Heading3">
+ <a name="7214"> </a>LS.3.1 Allowing Display and Modification of Attributes
+</h4>
+<p class="Body">
+ <a name="7215"> </a>We use JavaBeans components to provide a layer of abstraction on top of the individual classes that implement the <code>net.jini.core.entry.Entry</code> interface. This provides us with several benefits:
+</p>
+
+<ul>
+
+<li class="SmartList1"><a name="7216"> </a>This approach uses an existing standard and thus reduces the amount of unfamiliar material for programmers.<p>
+ <li class="SmartList1"><a name="7217"> </a>JavaBeans components provide mechanisms for localized display of attribute values and descriptions.<p>
+ <li class="SmartList1"><a name="7218"> </a>Modification of attributes is also handled, via property editors.
+</ul>
+
+<h5 class="Heading4">
+ <a name="7219"> </a>LS.3.1.1 Using JavaBeans Components with Entry Classes
+</h5>
+
+<p class="Body">
+ <a name="7220"> </a>Many, if not most, entry classes should have a bean class associated with them. Our use of JavaBeans components provides a familiar mechanism for authors of browse/search tools to represent information about a service's attributes, such as its icons and appropriately localized descriptions of the meanings and values of its attributes. JavaBeans components also play a role in permitting administrators of a service to modify some of its attributes, as they can manipulate the values of its attributes using standard JavaBeans component mechanisms.
+</p>
+<p class="Body">
+ <a name="31182"> </a>For example, obtaining a <code>java.beans.BeanDescriptor</code> for a JavaBeans component that is linked to a "location" entry object for a particular service allows a programmer to obtain an icon that gives a visual indication of what that entry class is for, along with a short textual description of the class and the values of the individual attributes in the location object. It also permits an administrative tool to view and change certain fields in the location, such as the floor number.
+</p>
+<h4 class="Heading3">
+ <a name="7222"> </a>LS.3.2 Associating JavaBeans Components with Entry Classes
+</h4>
+<p class="Body">
+ <a name="7223"> </a>The pattern for establishing a link between an entry object and an instance of its JavaBeans component is simple enough, as this example illustrates:
+</p>
+
+<pre class="Preformatted">
+package org.example.foo;
+
+import java.io.Serializable;
+import net.jini.lookup.entry.EntryBean;
+import net.jini.entry.AbstractEntry;
+
+public class Size {
+ public int value;
+}
+
+public class Cavenewt extends AbstractEntry {
+ public Cavenewt() {
+ }
+ public Cavenewt(Size anvilSize) {
+ this.anvilSize = anvilSize;
+ }
+ public Size anvilSize;
+}
+
+public class CavenewtBean implements EntryBean, Serializable {
+ protected Cavenewt assoc;
+ public CavenewtBean() {
+ super();
+ assoc = new Cavenewt();
+ }
+ public void setAnvilSize(Size x) {
+ assoc.anvilSize = x;
+ }
+ public Size getAnvilSize() {
+ return assoc.anvilSize;
+ }
+ public void makeLink(Entry obj) {
+ assoc = (Cavenewt) obj;
+ }
+ public Entry followLink() {
+ return assoc;
+ }
+}
+</pre>
+<p class="Body">
+ <a name="30162"> </a>From the above, the pattern should be relatively clear:
+</p>
+<ul>
+
+<p><li class="SmartList1"><a name="7263"> </a>The name of a JavaBeans component is derived by taking the fully qualified entry class name and appending the string <code>Bean</code>; for example, the name of the JavaBeans component associated with the entry class <code>foo.bar.Baz</code> is <code>foo.bar.BazBean</code>. This implies that an entry class and its associated JavaBeans component must reside in the same package.<p>
+ <li class="SmartList1"><a name="7264"> </a>The class has both a public no-arg constructor and a public constructor that takes each public object field of the class and its superclasses as parameter. The former constructs an empty instance of the class, and the latter initializes each field of the new instance to the given parameter.<p>
+ <li class="SmartList1"><a name="7265"> </a>The class implements the <code>net.jini.core.entry.Entry</code> interface, preferably by extending the <code>net.jini.entry.AbstractEntry</code> class, and the JavaBeans component implements the <code>net.jini.lookup.entry.EntryBean</code> interface.<p>
+ <li class="SmartList1"><a name="7266"> </a>There is a one-to-one link between a JavaBeans component and a particular entry object. The <code>makeLink</code> method establishes this link and will throw an exception if the association is with an entry class of the wrong type. The <code>followLink</code> method returns the entry object associated with a particular JavaBeans component.<p>
+ <li class="SmartList1"><a name="7267"> </a>The no-arg public constructor for a JavaBeans component creates and makes a link to an empty entry object.<p>
+ <li class="SmartList1"><a name="7268"> </a>For each public object field <code class="CodeEmphasis">foo</code> in an entry class, there exist both a <code>set</code><code class="CodeEmphasis">Foo</code> and a <code>getFoo</code> method in the associated JavaBeans component. The <code>set</code><code class="CodeEmphasis">Foo</code> method takes a single argument of the same type as the <code class="CodeEmphasis">foo</code> field in the associated entry and sets the value of that field to its argument. The <code>get</code><code class="CodeEmphasis">Foo</code> method returns the value of that field.
+</ul></p>
+<h4 class="Heading3">
+ <a name="7269"> </a>LS.3.3 Supporting Interfaces and Classes
+</h4>
+
+<p class="Body">
+ <a name="7270"> </a>The following classes and interfaces provide facilities for handling entry classes and their associated JavaBeans components.
+</p>
+
+<pre class="Preformatted">
+package net.jini.lookup.entry;
+
+public class EntryBeans {
+ public static EntryBean createBean(Entry e)
+ throws ClassNotFoundException, java.io.IOException {...}
+
+public static Class getBeanClass(Class c)
+ throws ClassNotFoundException {...}
+}
+
+public interface EntryBean {
+ void makeLink(Entry e);
+ Entry followLink();
+}
+</pre>
+<p class="Body">
+ <a name="30550"> </a>The <code>EntryBeans</code> class cannot be instantiated. Its sole method, <code>createBean</code>, creates and initializes a new JavaBeans component and links it to the entry object it is passed. If a problem occurs creating the JavaBeans component, the method throws either <code>java.io.IOException</code> or <code>ClassNotFoundException</code>.
+</p>
+<p class="Body">
+ <a name="7286"> </a>The <code>createBean</code> method uses the same mechanism for instantiating a JavaBeans component as the <code>java.beans.Beans.instantiate</code> method. It will initially try to instantiate the JavaBeans component using the same class loader as the entry it is passed. If that fails, it will fall back to using the default class loader.
+</p>
+<p class="Body">
+ <a name="7287"> </a>The <code>getBeanClass</code> method returns the class of the JavaBeans component associated with the given attribute class. If the class passed in does not implement the <code>net.jini.core.entry.Entry</code> interface, an <code>IllegalArgumentException</code> is thrown. If the given attribute class cannot be found, a <code>ClassNotFoundException</code> is thrown.
+</p>
+<p class="Body">
+ <a name="7288"> </a>The <code>EntryBean</code> interface must be implemented by all JavaBeans components that are intended to be linked to entry objects. The <code>makeLink</code> method establishes a link between a JavaBeans component object and an entry object, and the <code>followLink</code> method returns the entry object linked to by a particular JavaBeans component. Note that objects that implement the <code>EntryBean</code> interface should not be assumed to perform any internal synchronization in their implementations of the <code>makeLink</code> or <code>followLink</code> methods, or in the <code>setFoo</code> or <code>getFoo</code> patterns.
+</p>
+<h3 class="Heading2">
+ <a name="7313"> </a>LS.4 Generic Attribute Classes
+</h3>
+<p class="Body">
+ <a name="7314"> </a>We will now describe some attribute classes that are generic to many or all services and the JavaBeans components that are associated with each. Unless otherwise stated, all classes defined here live in the <code>net.jini.lookup.entry </code>package. The definitions assume the following classes to have been imported:
+</p>
+<pre class="Preformatted">
+java.io.Serializable</code>
+<code>net.jini.entry.AbstractEntry</code>
+</pre>
+<h4 class="Heading3">
+ <a name="31204"> </a>LS.4.1 Indicating User Modifiability
+</h4>
+<p class="Body">
+ <a name="31205"> </a>To indicate that certain entry classes should only be modified by the service that registered itself with instances of these entry classes, we annotate them with the <code>ServiceControlled</code> interface.
+</p>
+<pre class="Preformatted">
+public interface ServiceControlled {
+}
+</pre>
+<p class="Body">
+ <a name="10489"> </a>Authors of administrative tools that modify fields of attribute objects at the lookup service should not permit users to either modify any fields or add any new instances of objects that implement this interface.
+</p>
+<h4 class="Heading3">
+ <a name="7322"> </a>LS.4.2 Basic Service Information
+</h4>
+<p class="Body">
+ <a name="7323"> </a>The <code>ServiceInfo</code> attribute class provides some basic information about a service.
+</p>
+<pre class="Preformatted">
+public class ServiceInfo extends AbstractEntry
+ implements ServiceControlled
+{
+ public ServiceInfo() {...}
+ public ServiceInfo(String name, String manufacturer,
+ String vendor, String version,
+ String model, String serialNumber) {...}
+
+<div class="codehilite"><pre><span class="n">public</span> <span class="n">String</span> <span class="n">name</span><span class="p">;</span>
+<span class="n">public</span> <span class="n">String</span> <span class="n">manufacturer</span><span class="p">;</span>
+<span class="n">public</span> <span class="n">String</span> <span class="n">vendor</span><span class="p">;</span>
+<span class="n">public</span> <span class="n">String</span> <span class="n">version</span><span class="p">;</span>
+<span class="n">public</span> <span class="n">String</span> <span class="n">model</span><span class="p">;</span>
+<span class="n">public</span> <span class="n">String</span> <span class="n">serialNumber</span><span class="p">;</span>
+</pre></div>
+
+
+<p>}</p>
+<p>public class ServiceInfoBean
+ implements EntryBean, Serializable
+{
+ public String getName() {...}
+ public void setName(String s) {...}
+ public String getManufacturer() {...}
+ public void setManufacturer(String s) {...}
+ public String getVendor() {...}
+ public void setVendor(String s) {...}
+ public String getVersion() {...}
+ public void setVersion(String s) {...}
+ public String getModel() {...}
+ public void setModel(String s) {...}
+ public String getSerialNumber() {...}
+ public void setSerialNumber(String s) {...}
+}
+</pre>
+<p class="Body">
+ <a name="10491"> </a>Each service should register itself with only one instance of this class. The fields of the <code>ServiceInfo</code> class have the following meanings:
+</p>
+<ul></p>
+<p><li class="SmartList1"><a name="7355"> </a>The <code>name</code> field contains a specific product name, such as <code>"Ultra</code> <code>30"</code> (for a particular workstation) or <code>"JavaSafe"</code> (for a specific configuration management service). This string should not include the name of the manufacturer or vendor.<p>
+ <li class="SmartList1"><a name="7356"> </a>The <code>manufacturer</code> field provides the name of the company that "built" this service. This might be a hardware manufacturer or a software authoring company.<p>
+ <li class="SmartList1"><a name="7357"> </a>The <code>vendor</code> field contains the name of the company that sells the software or hardware that provides this service. This may be the same name as is in the <code>manufacturer</code> field, or it could be the name of a reseller. This field exists so that in cases in which resellers relabel products built by other companies, users will be able to search based on either name.<p>
+ <li class="SmartList1"><a name="7358"> </a>The <code>version</code> field provides information about the version of this service. It is a free-form field, though we expect that service implementors will follow normal version-naming conventions in using it.<p>
+ <li class="SmartList1"><a name="7359"> </a>The <code>model</code> field contains the specific model name or number of the product, if any.<p>
+ <li class="SmartList1"><a name="7360"> </a>The <code>serialNumber</code> field provides the serial number of this instance of the service, if any.
+</ul></p>
+<h4 class="Heading3">
+ <a name="7361"> </a>LS.4.3 More Specific Information
+</h4>
+<p class="Body">
+ <a name="7362"> </a>The <code>ServiceType</code> class allows an author of a service to deliver information that is specific to a particular instance of a service, rather than to services in general.
+</p>
+<pre class="Preformatted">
+public class ServiceType extends AbstractEntry
+ implements ServiceControlled
+{
+ public ServiceType() {...}
+ public java.awt.Image getIcon(int iconKind) {...}
+ public String getDisplayName() {...}
+ public String getShortDescription() {...}
+}
+</pre>
+<p class="Body">
+ <a name="10493"> </a>Each service may register itself with multiple instances of this class, usually with one instance for each type of service interface it implements.
+</p>
+<p class="Body">
+ <a name="7372"> </a>This class has no public fields and, as a result, has no associated JavaBeans component.
+</p>
+<p class="Body">
+ <a name="7373"> </a>The <code>getIcon</code> method returns an icon of the appropriate kind for the service; it works in the same way as the <code>getIcon</code> method in the <code>java.beans.BeanInfo</code> interface, with the value of <code>iconKind</code> being taken from the possibilities defined in that interface. The <code>getDisplayName</code> and <code>getShortDescription</code> methods return a localized human-readable name and description for the service, in the same manner as their counterparts in the <code>java.beans.FeatureDescriptor</code> class. Each of these methods returns <code>null</code> if no information of the appropriate kind is defined.
+</p>
+<p class="Body">
+ <a name="7374"> </a>In case the distinction between the information this class provides and that provided by a JavaBeans component's meta-information is unclear, the class <code>ServiceType</code> is meant to be used in the lookup service as one of the entry classes with which a service registers itself, and so it can be customized on a per-service basis. By contrast, the <code>FeatureDescriptor</code> and <code>BeanInfo</code> objects for all <code>EntryBean</code> classes provide only generic information about those classes and none about specific instances of those classes.
+</p>
+<h4 class="Heading3">
+ <a name="7375"> </a>LS.4.4 Naming a Service
+</h4>
+
+<p class="Body">
+ <a name="7376"> </a>People like to associate names with particular services and may do so using the <code>Name</code> class.
+</p>
+
+<pre class="Preformatted">
+public class Name extends AbstractEntry {
+ public Name() {...}
+ public Name(String name) {...}
+
+public String name;
+}
+
+public class NameBean implements EntryBean, Serializable {
+ public String getName() {...}
+ public void setName(String s) {...}
+}
+</pre>
+<p class="Body">
+ <a name="10495"> </a>Services may register themselves with multiple instances of this class, and either services or administrators may add, modify, or remove instances of this class from the attribute set under which a service is registered.
+</p>
+<p class="Body">
+ <a name="7389"> </a>The <code>name</code> field provides a short name for a particular instance of a service (for example, "<code>Bob's</code> <code>toaster</code>").
+</p>
+<h4 class="Heading3">
+ <a name="7390"> </a>LS.4.5 Adding a Comment to a Service
+</h4>
+<p class="Body">
+ <a name="7391"> </a>In cases in which some kind of comment is appropriate for a service (for example, "<code>this toaster tends to burn bagels</code>"), the <code>Comment</code> class provides an appropriate facility.
+</p>
+<pre class="Preformatted">
+public class Comment extends AbstractEntry {
+ public Comment() {...}
+ public Comment(String comment) {...}
+
+<div class="codehilite"><pre><span class="n">public</span> <span class="n">String</span> <span class="n">comment</span><span class="p">;</span>
+</pre></div>
+
+
+<p>}</p>
+<p>public class CommentBean implements EntryBean, Serializable {
+ public String getComment() {...}
+ public void setComment(String s) {...}
+}
+</pre>
+<p class="Body">
+ <a name="10497"> </a>A service may have more than one comment associated with it, and comments may be added, removed, or edited by either a service itself, administrators, or users.
+</p>
+<h4 class="Heading3">
+ <a name="7404"> </a>LS.4.6 Physical Location
+</h4>
+<p class="Body">
+ <a name="7405"> </a>The <code>Location</code> and <code>Address</code> classes provide information about the physical location of a particular service.
+</p>
+<p class="Body">
+ <a name="7406"> </a>Since many services have no physical location, some have one, and a few may have more than one, it might make sense for a service to register itself with zero or more instances of either of these classes, depending on its nature.
+</p>
+<p class="Body">
+ <a name="7407"> </a>The <code>Location</code> class is intended to provide information about the physical location of a service in a single building or on a small, unified campus. The <code>Address</code> class provides more information and may be appropriate for use with the <code>Location</code> class in a larger, more geographically distributed organization.
+</p>
+<pre class="Preformatted">
+public class Location extends AbstractEntry {
+ public Location() {...}
+ public Location(String floor, String room,
+ String building) {...}</p>
+<div class="codehilite"><pre><span class="n">public</span> <span class="n">String</span> <span class="n">floor</span><span class="p">;</span>
+<span class="n">public</span> <span class="n">String</span> <span class="n">room</span><span class="p">;</span>
+<span class="n">public</span> <span class="n">String</span> <span class="n">building</span><span class="p">;</span>
+</pre></div>
+
+
+<p>}</p>
+<p>public class LocationBean implements EntryBean, Serializable {
+ public String getFloor() {...}
+ public void setFloor(String s) {...}
+ public String getRoom() {...}
+ public void setRoom(String s) {...}
+ public String getBuilding() {...}
+ public void setBuilding(String s) {...}
+}</p>
+<p>public class Address extends AbstractEntry {
+ public Address() {...}
+ public Address(String street, String organization,
+ String organizationalUnit, String locality,
+ String stateOrProvince, String postalCode,
+ String country) {...}</p>
+<div class="codehilite"><pre><span class="n">public</span> <span class="n">String</span> <span class="n">street</span><span class="p">;</span>
+<span class="n">public</span> <span class="n">String</span> <span class="n">organization</span><span class="p">;</span>
+<span class="n">public</span> <span class="n">String</span> <span class="n">organizationalUnit</span><span class="p">;</span>
+<span class="n">public</span> <span class="n">String</span> <span class="n">locality</span><span class="p">;</span>
+<span class="n">public</span> <span class="n">String</span> <span class="n">stateOrProvince</span><span class="p">;</span>
+<span class="n">public</span> <span class="n">String</span> <span class="n">postalCode</span><span class="p">;</span>
+<span class="n">public</span> <span class="n">String</span> <span class="n">country</span><span class="p">;</span>
+</pre></div>
+
+
+<p>}</p>
+<p>public class AddressBean implements EntryBean, Serializable {
+ public String getStreet() {...}
+ public void setStreet(String s) {...}
+ public String getOrganization() {...}
+ public void setOrganization(String s) {...}
+ public String getOrganizationalUnit() {...}
+ public void setOrganizationalUnit(String s) {...}
+ public String getLocality() {...}
+ public void setLocality(String s) {...}
+ public String getStateOrProvince() {...}
+ public void setStateOrProvince(String s) {...}
+ public String getPostalCode() {...}
+ public void setPostalCode(String s) {...}
+ public String getCountry() {...}
+ public void setCountry(String s) {...}
+}
+</pre>
+<p class="Body">
+ <a name="7459"> </a>We believe the fields of these classes to be self-explanatory, with the possible exception of the <code>locality</code> field of the <code>Address</code> class, which would typically hold the name of a city.
+</p>
+<h4 class="Heading3">
+ <a name="7460"> </a>LS.4.7 Status Information
+</h4>
+<p class="Body">
+ <a name="7461"> </a>Some attributes of a service may constitute long-lived status, such as an indication that a printer is out of paper. We provide a class, <code>Status</code>, that implementors can use as a base for providing status-related entry classes.
+</p>
+<pre class="Preformatted">
+public abstract class Status extends AbstractEntry {
+ protected Status() {...}
+ protected Status(StatusType severity) {...}</p>
+<div class="codehilite"><pre><span class="n">public</span> <span class="n">StatusType</span> <span class="n">severity</span><span class="p">;</span>
+</pre></div>
+
+
+<p>}</p>
+<p>public class StatusType implements Serializable {
+ private final int type;
+ private StatusType(int t) { type = t; }
+ public static final StatusType ERROR = new StatusType(1);
+ public static final StatusType WARNING =
+ new StatusType(2);
+ public static final StatusType NOTICE = new StatusType(3);
+ public static final StatusType NORMAL = new StatusType(4);
+}</p>
+<p>public abstract class StatusBean
+ implements EntryBean, Serializable
+{
+ public StatusType getSeverity() {...}
+ public void setSeverity(StatusType i) {...}
+}
+</pre>
+<p class="Body">
+ <a name="30481"> </a>We define a separate <code>StatusType</code> class to make it possible to write a property editor that will work with the <code>StatusBean</code> class (we do not currently provide a property editor implementation).
+</p>
+<h4 class="Heading3">
+ <a name="7485"> </a>LS.4.8 Serialized Forms
+<p><CENTER>
+<table border="1" bordercolorlight="#FFFFFF" bordercolordark="#000000"
+ cellpadding="5" cellspacing="0" summary="serialized forms of the following classes">
+ <caption></caption>
+ <tr bgcolor="#CCCCCC">
+ <th>Class<br></th>
+ <th>serialVersionUID<br></th>
+ <th>Serialized Fields<br></th>
+ </tr>
+ <tr>
+ <td><code>Address</code><br></td>
+ <td>2896136903322046578L<br></td>
+ <td><em>all public fields</em></td>
+ </tr>
+ <tr>
+ <td><code>AddressBean</code><br></td>
+ <td>4491500432084550577L<br></td>
+ <td><code>Address asoc</code><br></td>
+ </tr>
+ <tr>
+ <td><code>Comment</code><br></td>
+ <td>7138608904371928208L<br></td>
+ <td><em>all public fields</em></td>
+ </tr>
+ <tr>
+ <td><code>CommentBean</code><br></td>
+ <td>5272583409036504625L<br></td>
+ <td><code>Comment asoc</code><br></td>
+ </tr>
+ <tr>
+ <td><code>Location</code><br></td>
+ <td>-3275276677967431315L<br></td>
+ <td><em>all public fields</em></div></td>
+ </tr>
+ <tr>
+ <td><code>LocationBean</code><br></td>
+ <td>-4182591284470292829L<br></td>
+ <td> </a><code>Location asoc</code><br></td>
+ </tr>
+ <tr>
+ <td><code>Name</code><br></td>
+ <td>2743215148071307201L<br></td>
+ <td><em>all public fields</em></td>
+ </tr>
+ <tr>
+ <td><code>NameBean</code><br></td>
+ <td>-6026791845102735793L<br></td>
+ <td><code>Name asoc</code><br></td>
+ </tr>
+ <tr>
+ <td><code>ServiceInfo</code><br></td>
+ <td>-1116664185758541509L<br></td>
+ <td><em>all public fields</em></td>
+ </tr>
+ <tr>
+ <td><code>ServiceInfoBean</code><br></td>
+ <td>8352546663361067804L<br></td>
+ <td><code>ServiceInfo asoc</code><br></td>
+ </tr>
+ <tr>
+ <td><code>ServiceType</code><br></td>
+ <td>-6443809721367395836L<br></td>
+ <td><em>all public fields</em></td>
+ </tr>
+ <tr>
+ <td><code>Status</code><br></td>
+ <td>-5193075846115040838L<br></td>
+ <td><em>all public fields</em></td>
+ </tr>
+ <tr>
+ <td><code>StatusBean</code><br></td>
+ <td>-1975539395914887503L<br></td>
+ <td><code>Status asoc</code><br></td>
+ </tr>
+ <tr>
+ <td><code>StatusType</code><br></td>
+ <td>-8268735508512712203L<br></td>
+ <td><code>int type</code><br></td>
+ </tr>
+</table>
+</CENTER></p>
+<h3 class="Heading2">
+ <a name="43987"> </a>LS.5 History</h3>
+
+<p>
+<table align="center" border="1" bordercolorlight="#FFFFFF" bordercolordark="#000000" cellpadding="5" cellspacing="0" summary="history of this specification">
+ <caption><p class="Body">
+ <a name="01887"> </a>
+</p>
+
+<p></caption>
+ <tr bgcolor="#CCCCCC">
+ <th>Version</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td valign="top">v1.0
+ </td>
+ <td>Initial release of this specification.
+</td>
+ </tr>
+</table></p>
+<h3 class="Heading2">
+ <a name="0188"> </a> License
+</h3>
+
+<p>
+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.
+</blockquote>
+
+<hr>
+<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>A Collection of Jini Technology Helper Utilities and Services Specifications</em></td>
+</tr></table>
+<a name="skip"></a>
+
+<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>
+
+<!-- This HTML file was initially created with Quadralay WebWorks Publisher 3.5.0 -->
+<!-- by Susan Snyder -->
+<!-- Last updated: 01/27/05 -->
+ </div>
+ </td>
+ <td valign="top">
+ <div class="navigation">
+ <div class="navigation_top">
+ <div class="navigation_bottom">
+<!-- sidenav -->
+<ul>
+<li><a href="index.html">Home</a></li>
+<li><a href="news.html">News</a></li>
+</ul>
+<h3 id="community">Community</h3>
+<ul>
+<li><a href="supported-platforms.html">Supported platforms</a></li>
+<li><a href="get-involved.html">Get Involved</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li>
+<li><a href="downloads.html">Downloads</a></li>
+<li>Documentation<ul>
+<li><a href="http://people.apache.org/~sijskes/doc/index.html">Original Jini Wiki</a></li>
+<li><a href="user-guide-glossary.html">Glossary</a></li>
+<li><a href="documentation.html">Cookbook</a></li>
+<li><a href="javadoc.html">Javadoc</a></li>
+</ul>
+</li>
+<li><a href="success-stories.html">Success Stories</a></li>
+<li><a href="mailing-lists.html">Mailing Lists</a></li>
+<li><a href="committers.html">Committers</a></li>
+<li><a href="found-a-bug.html">Found a Bug</a>?</li>
+</ul>
+<h3 id="development">Development</h3>
+<ul>
+<li><a href="javadoc.html">Javadoc</a></li>
+<li><a href="source-code.html">Source Code</a></li>
+<li><a href="building-river.html">Building River</a></li>
+<li><a href="roadmap.html">Roadmap</a></li>
+<li><a href="development-process.html">Development Process</a></li>
+<li><a href="https://issues.apache.org/jira/browse/RIVER">Issue Tracker</a></li>
+<li><a href="http://wiki.apache.org/river/">Wiki</a></li>
+</ul>
+<h3 id="search">Search</h3>
+<DIV>
+<FORM action="http://www.google.com/search" method="get" style="font-size: 10px;">
+<INPUT name="ie" type="hidden" value="UTF-8"></INPUT>
+<INPUT name="oe" type="hidden" value="UTF-8"></INPUT>
+ <INPUT maxlength="255" name="q" size="15" type="text" value></INPUT><BR></BR>
+ <INPUT name="btnG" type="submit" value="Search"></INPUT>
+ <INPUT name="domains" type="hidden" value="incubator.apache.org/river"></INPUT>
+ <INPUT name="sitesearch" type="hidden" value="incubator.apache.org/river"></INPUT>
+</FORM>
+</DIV>
+
+<ul>
+<li><a href="sitemap.html">Sitemap</a></li>
+</ul>
+<h3 id="the_foundation">The Foundation</h3>
+<ul>
+<li><a href="http://www.apache.org">Apache</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">Sponsors</a></li>
+<li><a href="http://www.apache.org/foundation/how-it-works.html">How it works</a></li>
+<li><a href="http://incubator.apache.org/">Incubator</a></li>
+</ul>
+<!-- sidenav -->
+ </div>
+ </div>
+ </div>
+ </td>
+ </tr>
+ </tbody>
+ </table>
+
+<!--
+ <div class="bottom_red_bar"></div>
+-->
+ </div>
+ </div>
+ </div>
+</div>
+<div class="black_box">
+<div class="footer">
+ <div class="footer_l">
+ <div class="footer_r">
+ <div>
+
+ </div>
+ </div>
+ </div>
+</div>
+</div>
+</div>
+<!--
+<div class="design_attribution">Page Template Design By Marc Prud'hommeaux based on <a href="http://activemq.apache.org/">ActiveMQ template</a></div>
+-->
+<div class="copyright_footer">
+<p>Copyright © 2010 The Apache Software Foundation, Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br>Apache and the Apache feather logo are trademarks of The Apache Software Foundation.</p>
+</div>
+<script src="skeleton_files/urchin.js" type="text/javascript">
+</script>
+<script type="text/javascript">
+_uacct = "UA-1940143-1";
+urchinTracker();
+</script>
+
+</body></html>