Added: incubator/river/site/trunk/content/river/docs/specs/entry-spec.mdtext URL: http://svn.apache.org/viewvc/incubator/river/site/trunk/content/river/docs/specs/entry-spec.mdtext?rev=1043362&view=auto ============================================================================== --- incubator/river/site/trunk/content/river/docs/specs/entry-spec.mdtext (added) +++ incubator/river/site/trunk/content/river/docs/specs/entry-spec.mdtext Wed Dec 8 11:34:36 2010 @@ -0,0 +1,259 @@ +<!-- + ! 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> + +<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 Entry Specification</title> +</head> + +<body bgcolor="#ffffff"> + +<p> </p> +<a href="#skip" title="Skip navigation bar"></a> +<table width="90%"><td align=left> +<tr> +<td align=left><a href="../../spec-index.html">Spec Index</a></td> +<td align=right><em>Jini Technology Core Platform Specifications</em></td> +</tr> +</table> +<br clear="all"> + + +<hr align="left"> +<table width="90%"> +<tr> +<td align="right" font size="4"><b>Version 1.0</b></td> +</tr> +</table> + +<blockquote> +<a name="skip"></a> +<h2 align="left">EN - Jini<font size="-1"><sup>TM</sup></font> Entry Specification +</h2> + +<h3 class="Heading2"> + <a name="30254"> </a>EN.1 Entries and Templates +</h3> +<p class="Body"> + Entries are designed to be used in distributed algorithms for which exact-match lookup semantics are useful. An entry is a typed set of objects, each of which may be tested for exact match with a template. +</p> +<h4 class="Heading3"> + <a name="6981"> </a>EN.1.1 Operations +</h4> +<p class="Body"> + <a name="29427"> </a>A service that uses entries will support methods that let you use entry objects. In this document we will use the term "operation" for such methods. There are three types of operations: +</p> +<ul> + <li class="SmartList1"><a name="29575"> </a><em class="Emphasis">Store operations</em>--operations that store one or more entries, usually for future matches. +<p> + <li class="SmartList1"><a name="29576"> </a><em class="Emphasis">Match operations</em>--operations that search for entries that match one or more templates. +<p> + <li class="SmartList1"><a name="29442"> </a><em class="Emphasis">Fetch operations</em>--operations that return one or more entries. +</ul> +<p class="Body"> + <a name="29443"> </a>It is possible for a single method to provide more than one of the operation types. For example, consider a method that returns an entry that matches a given template. Such a method can be logically split into two operation types (match and fetch), so any statements made in this specification about either operation type would apply to the appropriate part of the method's behavior. +</p> +<h4 class="Heading3"> + <a name="6962"> </a>EN.1.2 <code>Entry</code> +</h4> +<p class="Body"> + <a name="30282"> </a>An entry is a typed group of object references represented by a class that implements the marker interface <code>net.jini.core.entry.Entry</code>. Two different entries have the same type if and only if they are of the same class. +<pre class="Preformatted">package net.jini.core.entry; + +public interface Entry extends java.io.Serializable { } +</pre> +<p class="Body"> + <a name="29584"> </a>For the purpose of this specification, the term "field" when applied to an entry will mean fields that are public, non-static, non-transient, and non-final. Other fields of an entry are not affected by entry operations. In particular, when an entry object is created and filled in by a fetch operation, only the public non-static, non-transient, and non-final fields of the entry are set. Other fields are not affected, except as set by the class's no-arg constructor. +</p> +<p class="Body"> + <a name="7248"> </a>Each <code>Entry</code> class must provide a public no-arg constructor. Entries may not have fields of primitive type (<code>int</code>, <code>boolean</code>, etc.), although the objects they refer to may have primitive fields and non-public fields. For any type of operation, an attempt to use a malformed entry type that has primitive fields or does not have a no-arg constructor throws <code>IllegalArgumentException</code>. +</p> +<h4 class="Heading3"> + <a name="4383"> </a>EN.1.3 Serializing <code>Entry</code> Objects +</h4> +<p class="Body"> + <a name="4197"> </a><code>Entry</code> objects are typically not stored directly by an entry-using service (one that supports one or more entry operations). The client of the service will typically turn an <code>Entry</code> into an implementation-specific representation that includes a serialized form of the entry's class and each of the entry's fields. (This transformation is typically not explicit but is done by a client-side proxy object for the remote service.) It is these implementation-specific forms that are typically stored and retrieved from the service. These forms are not directly visible to the client, but their existence has important effects on the operational contract. The semantics of this section apply to all operation types, whether the above assumptions are true or not for a particular service. +</p> +<p class="Body"> + <a name="29606"> </a>Each entry has its fields serialized separately. In other words, if two fields of the entry refer to the same object (directly or indirectly), the serialized form that is compared for each field will have a separate copy of that object. This is true only of different fields of an entry; if an object graph of a particular field refers to the same object twice, the graph will be serialized and reconstituted with a single copy of that object. +</p> +<p class="Body"> + <a name="29607"> </a>A fetch operation returns an entry that has been created by using the entry type's no-arg constructor, and whose fields have been filled in from such a serialized form. Thus, if two fields, directly or indirectly, refer to the same underlying object, the fetched entry will have independent copies of the original underlying object. +</p> +<p class="Body"> + <a name="7348"> </a>This behavior, although not obvious, is both logically correct and practically advantageous. Logically, the fields can refer to object graphs, but the entry is not itself a graph of objects and so should not be reconstructed as one. An entry (relative to the service) is a set of separate fields, not a unit of its own. From a practical standpoint, viewing an entry as a single graph of objects requires a matching service to parse and understand the serialized form, because the ordering of objects in the written entry will be different from that in a template that can match it. +</p> +<p class="Body"> + <a name="4777"> </a>The serialized form for each field is a <code>java.rmi.MarshalledObject</code> object instance, which provides an <code>equals</code> method that conforms to the above matching semantics for a field. <code>MarshalledObject</code> also attaches a codebase to class descriptions in the serialized form, so classes written as part of an entry can be downloaded by a client when they are retrieved from the service. In a store operation, the class of the entry type itself is also written with a <code>MarshalledObject</code>, ensuring that it, too, may be downloaded from a codebase. +</p> +<h4 class="Heading3"> + <a name="4137"> </a>EN.1.4 <code>UnusableEntryException</code> +</h4> +<p class="Body"> + <a name="29509"> </a>A <code>net.jini.core.entry.UnusableEntryException</code> will be thrown if the serialized fields of an entry being fetched cannot be deserialized for any reason: +</p> +<pre class="Preformatted">package net.jini.core.entry; + +public class UnusableEntryException extends Exception { + public Entry partialEntry; + public String[] unusableFields; + public Throwable[] nestedExceptions; + public UnusableEntryException(Entry partial, + String[] badFields, Throwable[] exceptions) {...} + public UnusableEntryException(Throwable e) {...} +} +</pre> +<p class="Body"> + <a name="4082"> </a>The <code>partialEntry</code> field will refer to an entry of the type that would have been fetched, with all the usable fields filled in. Fields whose deserialization caused an exception will be <code>null</code> and have their names listed in the <code>unusableFields</code> string array. For each element in <code>unusableFields</code> the corresponding element of <code>nestedExceptions</code> will refer to the exception that caused the field to fail deserialization. +</p> +<p class="Body"> + <a name="7037"> </a>If the retrieved entry is corrupt in such a way as to prevent even an attempt at field deserialization (such as being unable to load the exact class for the entry), <code>partialEntry</code> and <code>unusableFields</code> will both be <code>null</code>, and <code>nestedExceptions</code> will be a single element array with the offending exception. +</p> +<p class="Body"> + <a name="4084"> </a>The kinds of exceptions that can show up in <code>nestedExceptions</code> are: +</p> +<ul> + <li class="SmartList1"><a name="4085"> </a><code>ClassNotFoundException</code>: The class of an object that was serialized cannot be found.<p> + <li class="SmartList1"><a name="4086"> </a><code>InstantiationException</code>: An object could not be created for a given type.<p> + <li class="SmartList1"><a name="4087"> </a><code>IllegalAccessException</code>: The field in the entry was either inaccessible or <code>final</code>.<p> + <li class="SmartList1"><a name="5170"> </a><code>java.io.ObjectStreamException</code>: The field could not be deserialized because of object stream problems.<p> + <li class="SmartList1"><a name="4088"> </a><code>java.rmi.RemoteException</code>: When a <code>RemoteException</code> is the nested exception of an <code>UnusableEntryException</code>, it means that a remote reference in the entry's state is no longer valid (more below). Remote errors associated with a method that is a fetch operation (such as being unable to contact a remote server) are not reflected by <code>UnusableEntryException</code> but in some other way defined by the method (typically by the method throwing <code>RemoteException</code> itself). +</ul> +<p class="Body"> + <a name="4222"> </a>Generally speaking, storing a remote reference to a non-persistent remote object in an entry is risky. Because entries are stored in serialized form, entries stored in an entry-based service will typically not participate in the garbage collection that keeps such references valid. However, if the reference is not persistent because the referenced server does not export persistent references, that garbage collection is the only way to ensure the ongoing validity of a remote reference. If a field contains a reference to a non-persistent remote object, either directly or indirectly, it is possible that the reference will no longer be valid when it is deserialized. In such a case the client code must decide whether to remove the entry from the entry-fetching service, to store the entry back into the service, or to leave the service as it is. +</p> +<p class="Body"> + <a name="4231"> </a>In the Java(TM) 2 Platform, activatable object references fit this need for persistent references. If you do not use a persistent type, you will have to handle the above problems with remote references. You may choose instead to have your entries store information sufficient to look up the current reference rather than putting actual references into the entry. +</p> +<h4 class="Heading3"> + <a name="3701"> </a>EN.1.5 Templates and Matching +</h4> +<p class="Body"> + <a name="29455"> </a>Match operations use entry objects of a given type, whose fields can either have <em class="Emphasis">values</em> (references to objects) or <em class="Emphasis">wildcards</em> (<code>null</code> references). When considering a template <em class="Emphasis">T</em> as a potential match against an entry <em class="Emphasis">E</em>, fields with values in <em class="Emphasis">T</em> must be matched exactly by the value in the same field of <em class="Emphasis">E</em>. Wildcards in <em class="Emphasis">T</em> match any value in the same field of <em class="Emphasis">E</em>. +</p> +<p class="Body"> + <a name="7327"> </a>The type of <em class="Emphasis">E</em> must be that of <em class="Emphasis">T</em> or be a subtype of the type of <em class="Emphasis">T</em>, in which case all fields added by the subtype are considered to be wildcards. This enables a template to match entries of any of its subtypes. If the matching is coupled with a fetch operation, the fetched entry must have the type of <em class="Emphasis">E</em>. +</p> +<p class="Body"> + <a name="29610"> </a>The values of two fields match if <code>MarshalledObject.equals</code> returns <code>true</code> for their <code>MarshalledObject</code> instances. This will happen if the bytes generated by their serialized form match, ignoring differences of serialization stream implementation (such as blocking factors for buffering). Class version differences that change the bytes generated by serialization will cause objects not to match. Neither entries nor their fields are matched using the <code>Object.equals</code> method or any other form of type-specific value matching. +</p> +<p class="Body"> + <a name="7182"> </a>You can store an entry that has a <code>null</code>-valued field, but you cannot match explicitly on a <code>null</code> value in that field, because <code>null</code> signals a wildcard field. If you have a field in an entry that may be variously <code>null</code> or not, you can set the field to <code>null</code> in your entry. If you need to write templates that distinguish between set and unset values for that field, you can (for example) add a <code>Boolean</code> field that indicates whether the field is set and use a <code>Boolean</code> value for that field in templates. +</p> +<p class="Body"> + <a name="3707"> </a>An entry that has no wildcards is a valid template. +</p> +<h4 class="Heading3"> + <a name="30385"> </a>EN.1.6 Serialized Form +</h4> +<CENTER> +<table border="1" bordercolorlight="#FFFFFF" bordercolordark="#000000" + cellpadding="5" cellspacing="0" Summary="serialized form of <code>UnusableEntryException</code>"> + <caption></caption> + <tr bgcolor="#CCCCCC"> + <th>Class<br></th> + <th>serialVersionUID<br></th> + <th>Serialized Fields<br></th> + </tr> + <tr> + <td><code>UnusableEntryException</code><br></td> + <td>-2199083666668626172L<br></td> + <td><em>all public fields</em></td> +</tr> +</table> +</CENTER> + + + + +<h3 class="Heading2"> + <a name="43987"> </a>EN.2 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 valign="top">v1.0</td> + <td>Initial release of this specification.</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> + +<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> +<td align=right><i>Jini Technology Core Platform Specifications</i></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 created with Quadralay WebWorks Publisher 3.5.0 --> +<!-- by Susan Snyder --> +<!-- Last updated: 01/25/05 -->
