river-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r780791 [4/17] - in /websites/staging/river/trunk/content/river/specs: ./ html/ html/images/
Date Thu, 16 Dec 2010 16:02:59 GMT
Added: websites/staging/river/trunk/content/river/specs/html/entry-spec.html
==============================================================================
--- websites/staging/river/trunk/content/river/specs/html/entry-spec.html (added)
+++ websites/staging/river/trunk/content/river/specs/html/entry-spec.html Thu Dec 16 16:02:58
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 -->



Mime
View raw message