You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@river.apache.org by th...@apache.org on 2010/12/08 12:34:39 UTC
svn commit: r1043362 [1/23] - in
/incubator/river/site/trunk/content/river/docs: ./ release-notes/ specs/
specs/images/
Author: thobbs
Date: Wed Dec 8 11:34:36 2010
New Revision: 1043362
URL: http://svn.apache.org/viewvc?rev=1043362&view=rev
Log:
Added all the original Jini spec documents. They in in raw HTML (although renamed to mdtext) and need to be reformatted.
Added:
incubator/river/site/trunk/content/river/docs/
incubator/river/site/trunk/content/river/docs/arch2_0.mdtext
incubator/river/site/trunk/content/river/docs/build.mdtext
incubator/river/site/trunk/content/river/docs/index.mdtext
incubator/river/site/trunk/content/river/docs/info-index.mdtext
incubator/river/site/trunk/content/river/docs/manpages-index.mdtext
incubator/river/site/trunk/content/river/docs/proxypreparation.pdf
incubator/river/site/trunk/content/river/docs/release-notes/
incubator/river/site/trunk/content/river/docs/release-notes/activate.mdtext
incubator/river/site/trunk/content/river/docs/release-notes/activation.mdtext
incubator/river/site/trunk/content/river/docs/release-notes/browser.mdtext
incubator/river/site/trunk/content/river/docs/release-notes/bugfixes.mdtext
incubator/river/site/trunk/content/river/docs/release-notes/classdep.mdtext
incubator/river/site/trunk/content/river/docs/release-notes/classserver.mdtext
incubator/river/site/trunk/content/river/docs/release-notes/comsunjinithread.mdtext
incubator/river/site/trunk/content/river/docs/release-notes/discovery.mdtext
incubator/river/site/trunk/content/river/docs/release-notes/evseqnums.mdtext
incubator/river/site/trunk/content/river/docs/release-notes/execpolicy.mdtext
incubator/river/site/trunk/content/river/docs/release-notes/fiddler.mdtext
incubator/river/site/trunk/content/river/docs/release-notes/index.mdtext
incubator/river/site/trunk/content/river/docs/release-notes/jeri.mdtext
incubator/river/site/trunk/content/river/docs/release-notes/join.mdtext
incubator/river/site/trunk/content/river/docs/release-notes/lease.mdtext
incubator/river/site/trunk/content/river/docs/release-notes/loader.mdtext
incubator/river/site/trunk/content/river/docs/release-notes/mahalo.mdtext
incubator/river/site/trunk/content/river/docs/release-notes/mercury.mdtext
incubator/river/site/trunk/content/river/docs/release-notes/netjinientry.mdtext
incubator/river/site/trunk/content/river/docs/release-notes/new.mdtext
incubator/river/site/trunk/content/river/docs/release-notes/norm.mdtext
incubator/river/site/trunk/content/river/docs/release-notes/outrigger.mdtext
incubator/river/site/trunk/content/river/docs/release-notes/reggie.mdtext
incubator/river/site/trunk/content/river/docs/release-notes/security.mdtext
incubator/river/site/trunk/content/river/docs/release-notes/servicediscovery.mdtext
incubator/river/site/trunk/content/river/docs/release-notes/servicestarter.mdtext
incubator/river/site/trunk/content/river/docs/simpleproxyverification.pdf (with props)
incubator/river/site/trunk/content/river/docs/smartproxyverification.pdf (with props)
incubator/river/site/trunk/content/river/docs/spec-index.mdtext
incubator/river/site/trunk/content/river/docs/specs/
incubator/river/site/trunk/content/river/docs/specs/devicearch-spec.mdtext
incubator/river/site/trunk/content/river/docs/specs/discovery-spec.mdtext
incubator/river/site/trunk/content/river/docs/specs/discoveryutil-spec.mdtext
incubator/river/site/trunk/content/river/docs/specs/entry-spec.mdtext
incubator/river/site/trunk/content/river/docs/specs/event-spec.mdtext
incubator/river/site/trunk/content/river/docs/specs/images/
incubator/river/site/trunk/content/river/docs/specs/images/devicearch-spec2.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/devicearch-spec3.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/devicearch-speca.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/discovery-spec2.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/discovery-spec3.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/discovery-spec4.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/discovery-speca.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/event-spec2.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/event-spec3.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/event-spec4.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/event-speca.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/jini-spec2.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/jini-spec3.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/jini-spec4.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/jini-speca.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/jinilogo.75w.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/js-speca.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/servicediscutil-spec10.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/servicediscutil-spec11.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/servicediscutil-spec12.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/servicediscutil-spec13.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/servicediscutil-spec14.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/servicediscutil-spec15.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/servicediscutil-spec16.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/servicediscutil-spec17.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/servicediscutil-spec18.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/servicediscutil-spec19.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/servicediscutil-spec2.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/servicediscutil-spec20.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/servicediscutil-spec21.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/servicediscutil-spec22.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/servicediscutil-spec23.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/servicediscutil-spec24.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/servicediscutil-spec25.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/servicediscutil-spec26.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/servicediscutil-spec27.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/servicediscutil-spec28.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/servicediscutil-spec29.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/servicediscutil-spec3.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/servicediscutil-spec4.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/servicediscutil-spec5.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/servicediscutil-spec6.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/servicediscutil-spec7.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/servicediscutil-spec8.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/servicediscutil-spec9.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/servicediscutil-speca.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/servnUI.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/servonly.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/txn-spec2.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/txn-spec3.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/txn-spec4.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/images/txn-speca.gif (with props)
incubator/river/site/trunk/content/river/docs/specs/jini-spec.mdtext
incubator/river/site/trunk/content/river/docs/specs/joinutil-spec.mdtext
incubator/river/site/trunk/content/river/docs/specs/js-spec.mdtext
incubator/river/site/trunk/content/river/docs/specs/jxpnote-spec.mdtext
incubator/river/site/trunk/content/river/docs/specs/lds-spec.mdtext
incubator/river/site/trunk/content/river/docs/specs/lease-spec.mdtext
incubator/river/site/trunk/content/river/docs/specs/leaseutil-spec.mdtext
incubator/river/site/trunk/content/river/docs/specs/lookup-spec.mdtext
incubator/river/site/trunk/content/river/docs/specs/lrs-spec.mdtext
incubator/river/site/trunk/content/river/docs/specs/mailbox-spec.mdtext
incubator/river/site/trunk/content/river/docs/specs/schema-spec.mdtext
incubator/river/site/trunk/content/river/docs/specs/servicediscutil-spec.mdtext
incubator/river/site/trunk/content/river/docs/specs/serviceui-spec.mdtext
incubator/river/site/trunk/content/river/docs/specs/standard.css
incubator/river/site/trunk/content/river/docs/specs/txn-spec.mdtext
Added: incubator/river/site/trunk/content/river/docs/arch2_0.mdtext
URL: http://svn.apache.org/viewvc/incubator/river/site/trunk/content/river/docs/arch2_0.mdtext?rev=1043362&view=auto
==============================================================================
--- incubator/river/site/trunk/content/river/docs/arch2_0.mdtext (added)
+++ incubator/river/site/trunk/content/river/docs/arch2_0.mdtext Wed Dec 8 11:34:36 2010
@@ -0,0 +1,1246 @@
+<!--
+ ! 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>
+<body text="#000000" bgcolor="#ffffff" link="#9b37cc"
+ vlink="#cc1877" alink="#ffffff">
+
+<title>Jini Architecture Specification Version 2.0 Overview - Apache River Release v2.1.2</title>
+<a name="TOP">
+<center><h1>Jini<font><sup>TM</sup></font> Architecture Specification Version 2.0 Extensions Overview<br>
+ Apache River Release v2.1.2</h1></center>
+
+<br>
+
+<p>This document provides an overview of the new components of
+the Jini<font size="-1"><sup>TM</sup></font> v2.0 Architecture included in Apache River and
+explains how the components fit together and fit within the
+existing Jini<font size="-1"><sup>TM</sup></font> technology infrastructure. Much of this
+information is available in the package, interface, and class
+documentation, but this document provides a higher-level overview
+and indicates where to find more information.
+
+
+<h2>1 Overview of Jini<font size="-1"><sup>TM</sup></font> Architecture</h2>
+
+<p>The Jini system architecture consists of three categories:
+<i>programming model</i>, <i>infrastructure</i>, and <i>services</i>.
+The original <a href="../doc/specs/html/jini-spec.html"><i>Jini
+Architecture Specification Version 1.0</i></a> defines these categories as follows:
+
+<blockquote>
+ The infrastructure is the set of components that enables
+ building a federated Jini system, while the services are the
+ entities within the federation. The programming model is a
+ set of interfaces that enables the construction of reliable
+ services, including those that are part of the infrastructure
+ and those that join into the federation.
+</blockquote>
+
+<p>Originally, the programming model defined models for leasing, event
+notification, and transactions. The basic infrastructure consisted of
+the discovery/join protocol and the lookup service. Previous versions
+delivered implementations of the following Jini
+technology-enabled services (Jini services):
+
+<ul>
+<li> Lookup Service (reggie)
+<li> Transaction Manager Service (mahalo)
+<li> Lease Renewal Service (norm)
+<li> Event Mailbox Service (mercury)
+<li> Lookup Discovery Service (fiddler)
+<li> JavaSpaces Service (outrigger)
+</ul>
+
+<p>Apache River releases following and including the Jini v2.0 release add
+components to the first two
+categories (programming model and infrastructure) of the Jini
+architecture, although some components span both of these categories.
+Additionally, this release provides updates to existing services to
+account for the additions to the infrastructure and the programming
+model. The component additions can be summarized as follows:
+
+<p><i>Additions to Programming Models</i>
+<ul>
+<li><a href="api/net/jini/config/Configuration.html">Configuration</a>
+<li><a href="api/net/jini/export/Exporter.html">Exporter</a>
+<li><a href="api/net/jini/security/ProxyPreparer.html">ProxyPreparer</a>
+</ul>
+
+<p><i>New Infrastructure</i>
+<ul>
+<li><a href="api/net/jini/security/package-summary.html">Security</a>
+<li><a href="api/net/jini/core/constraint/package-summary.html">Invocation Constraints</a>
+<li><a href="api/net/jini/jeri/package-summary.html">Jini extensible
+remote invocation (Jini ERI)</a>
+<li><a href="api/net/jini/security/policy/package-summary.html">Dynamic Policy</a>
+<li><a href="api/net/jini/loader/pref/package-summary.html">Preferred Class Loading</a>
+<li><a href="api/com/sun/jini/discovery/package-summary.html">Discovery Protocol v2</a>
+</ul>
+
+<p><i>Updates to Services</i>
+
+<p>Each service has been updated to support being
+configured using a <code>Configuration</code>. Most of the
+services were previously configured via system properties. These
+services can now be configured via entries in the configuration.
+New types of behavior that can be configured are remote service
+exporting and proxy preparation.
+
+
+<h3>1.1 Goals</h3>
+
+The main goals for the additions in the Jini architecture are to:
+
+<ul>
+<li> Add support for secure Jini technology-based programs (Security infrastructure)
+<li> Provide mechanisms to configure applications (<code>Configuration</code>)
+<li> Unify client-side and server-side programming models
+ (<code>ProxyPreparer</code> and <code>Exporter</code>)
+<li> Provide a Java(TM) Remote Method Invocation (Java RMI)
+ implementation that supports pluggable invocation layer behavior
+ and pluggable transport providers (Jini ERI)
+</ul>
+
+<p>The primary motivation for augmenting the Jini architecture
+is to provide the new programming models and infrastructure
+necessary to support and manage security in Jini technology-based
+distributed applications. The previous Jini architecture lacked
+direct support for a type of security many Jini / Apache River applications
+need, namely basic network security for remote calls to
+services. This goal is addressed by the new security
+infrastructure and constraint-based remote invocation model.
+
+<p>Another important goal for this release is to better unify the
+overall programming model for service developers, given the
+previous lack of uniformity in the APIs for implementing,
+exporting, and deploying services. Securing remote invocation
+requires additional client-side verification steps, so this
+release introduces a uniform client-side API to handle a
+"preparation" step before remote invocation. Additionally,
+application developers can ease deployment tasks by separating
+out deployment-time information from the application. The
+<code>Configuration</code> API introduced in the Jini 2.0 release
+provides a simple and uniform way to obtain deployment-specific
+information. The resulting programming model supports a uniform
+framework for pluggable security, exporter, transport, and other
+service providers.
+
+<p>A final goal is to provide an implementation of the Java RMI
+programming model that supports constraints on remote invocation
+(which is crucial to the security model), and supports pluggable
+invocation and dispatch behavior as well as pluggable transport
+providers on a per-object basis, features which are lacking in the
+JRMP implementation of Java 2 SDK, Standard Edition (J2SE(TM)) RMI.
+The Jini ERI API provides such a pluggable implementation of the Java
+RMI programming model.
+
+
+<h2>2 Programming Model</h2>
+
+<p>Before delving into the discussion of the security
+architecture, it is important to understand initially a few
+additional programming models, <code>Configuration</code>,
+<code>Exporter</code>, and <code>ProxyPreparer</code>, each of
+which simplifies application development in general and secure
+application development in particular.
+
+<h3>2.1 <code>Configuration</code> </h3>
+
+An application is much easier to test, deploy, and evolve
+when the application's source code is not tied directly to specific
+deployments, but instead uses a level of abstraction, such as
+service provider interfaces. Such applications may separate out
+deployment-specific information from the application source code,
+allowing this information to be configured at deployment time. The
+obvious benefit of this approach is that the application can be
+configured to use the implementations that the deployment requires
+without having to change the application source code. If
+deployment needs change, only the configuration must change; the
+application can remain intact.
+
+<p>The <code>net.jini.config.Configuration</code> API supports this
+approach by providing a simple, uniform way to obtain the objects
+needed to configure an application. An application can obtain an
+object from a <code>Configuration</code> instead of explicitly
+constructing an instance to avoid tying the application to
+deployment-specific implementations. Typical objects that should be
+obtained from a configuration are <code>Exporter</code> and
+<code>ProxyPreparer</code> instances (discussed below).
+
+<p>An application may not want to be tied to a specific implementation
+of <code>Configuration</code> either, so an application can use
+<code>net.jini.config.ConfigurationProvider</code> to obtain a
+<code>Configuration</code> implementation. Using the
+<code>ConfigurationProvider</code> in an application allows the
+application's deployer to specify the most suitable
+<code>Configuration</code> implementation at deployment time.
+A given <code>Configuration</code> implementation might
+read configuration information from a file, a database,
+or from some other source.
+
+<p>The standard, default <code>Configuration</code> implementation is
+<code>net.jini.config.ConfigurationFile</code>. This implementation
+reads configuration information, written in a subset of the syntax of
+the Java programming language, from files and URLs to produce objects
+from the configuration. See the <a href="api/net/jini/config/package-summary.html"><code>net.jini.config</code> package
+documentation</a> for an example of how an application can use a
+<code>Configuration</code> and how a deployer can use a
+<code>ConfigurationFile</code> source file to configure that
+application.
+
+<h3>2.2 <code>Exporter</code> and the Server-Side Implementation Model </h3>
+
+<p>In Jini technology-based applications, invoking a method on a
+Jini service proxy has a uniform client-side model: a client
+simply invokes a method on the service's proxy to initiate remote
+communication to the service object, an invocation that follows
+the same general semantics as the Java RMI model.
+
+<p>The server-side implementation model for Jini / Apache River applications,
+however, is not uniform. An application developer typically
+implements a service and exports that service in a way that ties
+the service directly to a specific implementation and model of
+remote communication. This implementation dependence requires
+that the application source code be modified if the service needs
+to be exported in a slightly different way. For example, an
+application deployment may need to export a service to use a
+different port or socket factory, or may need to export that
+service using a different implementation of remote communication
+entirely, such as a different implementation of the Java RMI
+programming model.
+
+<p>The <code>net.jini.export.Exporter</code> interface unifies the
+server-side implementation model by providing an abstraction for
+exporting and unexporting a remote object. The details of export and
+unexport behavior, including communication protocols used for remote
+invocation and additional invocation semantics, are defined by the
+particular implementation of the <code>Exporter</code> interface.
+
+<p>Several standard <code>Exporter</code> implementations, which are
+also implementations of the Java RMI programming model, are provided.
+The following table lists these
+implementations along with the class whose behavior the exporter is
+semantically equivalent to.
+
+<p>
+<blockquote>
+<table summary="Describes the standard Exporter implementations"
+ border=1 cellpadding=5>
+<th> <code>Exporter</code> <th>Equivalent Class
+<tr> <td> <code>net.jini.jrmp.JrmpExporter</code>
+ <td> <code>java.rmi.server.UnicastRemoteObject</code>
+<tr> <td> <code>net.jini.iiop.IiopExporter</code>
+ <td> <code>javax.rmi.PortableRemoteObject</code>
+<tr> <td> <code>net.jini.jeri.BasicJeriExporter</code>
+ <td> itself
+</table>
+</blockquote>
+
+<p>An application can use a <code>Configuration</code> together with
+the <code>Exporter</code> interface to export remote objects in a way
+that can be configured at deployment time. The following example
+(similar to those in the <a href="api/net/jini/config/package-summary.html"><code>net.jini.config.Configuration</code>
+package documentation</a>) illustrates configurable exporting:
+
+<pre>
+ import java.rmi.*;
+ import net.jini.config.*;
+ import net.jini.export.*;
+ public class Example implements Remote {
+ public static void main(String[] args) throws Exception {
+ Configuration config = ConfigurationProvider.getInstance(args);
+ Exporter exporter = (Exporter) config.getEntry(
+ "Example", "exporter", Exporter.class);
+ Remote proxy = exporter.export(new Example());
+ System.out.println(proxy);
+ exporter.unexport(true);
+ }
+ }
+</pre>
+
+<p>This application can be configured by specifying the following
+configuration file (that uses <code>ConfigurationFile</code>
+syntax) as a command line argument. The configuration file
+specifies the exporter to be a <code>JrmpExporter</code>, an
+exporter that produces proxies that participate in the JRMP
+protocol.
+
+<pre>
+ import net.jini.jrmp.*;
+ Example {
+ exporter = new JrmpExporter();
+ }
+</pre>
+
+<p>Alternatively, the application can be deployed to specify the
+exporter to be a <code>BasicJeriExporter</code> (an exporter for
+exporting a remote object to use Jini ERI) constructed to export the
+object on an anonymous TCP port.
+
+<pre>
+ import net.jini.jeri.*;
+ import net.jini.jeri.tcp.*;
+ Example {
+ exporter = new BasicJeriExporter(TcpServerEndpoint.getInstance(0));
+ }
+</pre>
+
+<h3>2.3 <code>ProxyPreparer</code> and the Client-Side Invocation Model </h3>
+
+<p>The new security model (discussed below) requires the application
+to perform some pre-invocation "preparation" of a service proxy before
+invoking its methods. This is because an application may receive the
+service proxy from an untrusted source. Therefore, before an
+application uses a proxy, that application might need to perform
+operations such as verifying trust in the proxy or granting
+permissions to the proxy once its trust has been verified.
+
+<p>These security requirements add an additional step to the
+client-side invocation model. The
+<code>net.jini.security.ProxyPreparer</code> interface abstracts the
+operation of "proxy preparation" into a single method,
+<code>prepareProxy</code>, so that the client-side invocation model
+can be uniform across applications using secure and non-secure
+proxies.
+
+<p>A <code>ProxyPreparer</code> can be used together with a
+<code>Configuration</code> to allow configurable proxy preparation.
+The following is a code snippet from the <a
+href="../source/src/com/sun/jini/example/hello/index.html"><i>hello</i>
+example</a> client, which is part of a comprehensive example included
+in the Apache River release:
+
+<p>
+<pre>
+ ProxyPreparer preparer = (ProxyPreparer) config.getEntry(
+ "com.sun.jini.example.hello.Client",
+ "preparer", ProxyPreparer.class, new BasicProxyPreparer());
+ server = (Hello) preparer.prepareProxy(server);
+ System.out.println("Server says: " + server.sayHello());
+</pre>
+
+<p>The call to <code>getEntry</code> supplies a default (<code>new
+BasicProxyPreparer()</code>) for the entry that will be returned if
+the configuration file does not have the specified entry. A
+<code>net.jini.security.BasicProxyPreparer</code> instance can be
+constructed with arguments specifying whether a proxy, passed to its
+<code>prepareProxy</code> method, needs to be verified or needs other
+security-related operations to be performed. A
+<code>BasicProxyPreparer</code> constructed with no arguments, which
+is the default above, specifies a "do nothing"
+<code>ProxyPreparer</code> that simply returns the proxy passed to the
+<code>prepareProxy</code> method.
+
+<p>If an application deployment has security requirements, the
+application can be deployed with a <code>BasicProxyPreparer</code>
+constructed with the appropriate arguments or can be
+deployed with an alternate <code>ProxyPreparer</code> implementation.
+
+
+<h2>3 Security</h2>
+
+<p>In a typical Jini technology-based application, a client obtains a
+service proxy from somewhere (for example, from a lookup service or as
+a result of communicating with another service) and then invokes
+methods on that proxy to communicate with the service. Many
+applications have a need to secure such remote communication,
+requiring one or more of the following:
+
+<ul>
+<li> Mutual authentication (client and server)
+<li> Authorization (access control)
+<li> Integrity (cryptographic checksums)
+<li> Confidentiality (encryption)
+</ul>
+
+<p>These requirements are typical for securing <i>data</i>
+communication; however, the Jini security model has an additional
+requirement: <i>code</i> integrity. In the Jini and Java RMI model,
+an object's data is sent in a remote invocation, but its code is
+downloaded out-of-band as a result of that remote invocation. An
+application needs to establish trust for the <i>objects</i> it
+receives, both in the integrity of an object's code as well as in its
+data.
+
+<p>This release provides a framework for trust verification as well as
+a constraint-based remote invocation model that enables an application
+to specify various requirements (such as security requirements) on
+remote invocations. The infrastructure also provides mechanisms that
+can be used to ensure code integrity.
+
+<h3>3.1 Constraints and Remote Invocation</h3>
+
+<p>The security requirements described above can be expressed as
+<i>constraints</i> on remote invocation. A constraint is a specific
+requirement, set by the client, on the behavior of remote invocations
+through a proxy to its associated service. A proxy can implement the
+interface <code>net.jini.core.constraint.RemoteMethodControl</code> to
+enable a client to set constraints on remote invocation through
+that proxy. The constraint-based remote invocation model is general,
+providing for security-related constraint types as well as other
+constraint types.
+
+<p>One example use of constraints is a client that needs to authenticate
+the identity of a service (such as a bank) before communicating with
+it through its proxy. In this example, the service proxy can
+implement the interface <code>RemoteMethodControl</code> to enable a
+client to set a constraint requiring server authentication on any
+remote invocation through that proxy. It is the proxy's
+responsibility to satisfy those constraints, but it is the client's
+responsibility to verify that it can trust the proxy to carry out its
+responsibility (discussed below).
+
+<p>Each constraint is represented as a
+<code>net.jini.core.constraint.InvocationConstraint</code> instance.
+An <code>InvocationConstraint</code> instance expresses "what" but not
+"how"; that is, a constraint expresses "what" the constraint
+represents, but not "how" the constraint should be satisfied. A proxy
+is responsible for using the appropriate transport and protocols to
+satisfy the constraints set by the client. Because constraints are
+expressed abstractly, the security implementations are pluggable and
+thus are capable of supporting a wide variety of protocols such as
+Secure Socket Layer (SSL) and Kerberos. See the
+<a href="api/net/jini/core/constraint/package-summary.html"><code>net.jini.core.constraint</code> package documentation</a> for
+general information on constraints including a number of pre-defined
+basic constraints.
+
+<p>Before a client sets constraints on a proxy, the client first needs
+to verify that it can trust the proxy to carry out the constraints to
+be set, because the proxy may have been received from an untrusted
+source. If the client does not verify that the proxy is trusted,
+there is a danger that the proxy could simply ignore the client's
+constraints and perform unencrypted data transfer, misrepresent the
+client's or server's identity, or worse. After the client verifies
+trust in the proxy, it can then set constraints on the proxy to
+specify any desired security requirements, such as server
+authentication.
+
+<p>Once a client trusts a proxy, it may also need to grant additional
+permissions to the proxy, over and above the minimal permissions
+typically configured in advance for untrusted code, so that future
+invocations through the proxy function properly. A proxy may require
+<code>net.jini.security.AuthenticationPermission</code> so that it can
+authenticate with the server, for example. A client must not grant
+permissions to the proxy before it trusts the proxy, so that the proxy
+cannot abuse the grants in a way that might cause harm.
+
+<p>To summarize, a client receiving a proxy from an untrusted source
+needs to "prepare" the proxy in the following manner before invoking
+that proxy's methods. The full requirements for each of these steps
+are described in the <a href="api/net/jini/security/package-summary.html"><code>net.jini.security</code> package documentation</a>:
+
+<ul>
+<li>Verify trust in the proxy
+<li>Grant permissions to the proxy
+<li>Set constraints on (a copy of) the proxy
+</ul>
+
+<p>The steps above can be encapsulated in a single operation known as
+<i>proxy preparation</i>, a term which means "preparing the proxy for
+remote invocation". The client-side interface
+<code>net.jini.security.ProxyPreparer</code> (discussed above)
+encapsulates such proxy preparation into a single method,
+<code>prepareProxy</code>.
+
+<p>The class <code>net.jini.security.BasicProxyPreparer</code>, a
+standard implementation of the <code>ProxyPreparer</code> interface,
+performs the three necessary steps above to prepare a proxy for secure
+remote calls. Most deployers can use a
+<code>BasicProxyPreparer</code> instance for proxy preparation and not
+worry about all the details behind trust verification (which are
+outlined in some detail below). Other applications may need to subclass
+<code>BasicProxyPreparer</code> if verifying trust, setting
+constraints, and/or granting permissions require some customization.
+
+
+<h3>3.2 Proxy Preparation Using <code>BasicProxyPreparer</code></h3>
+
+
+<p>The <code>BasicProxyPreparer</code> class encapsulates the three steps
+of verifying trust, setting constraints, and granting permissions to a
+proxy. A <code>BasicProxyPreparer</code> instance can be constructed
+in a variety of ways, supporting many common cases for proxy
+preparation including the following:
+
+<ul>
+
+<li> <i>Verify trust, grant permissions, and set new constraints</i>:
+to prepare a proxy received from an untrusted source.
+
+<li> <i>Set new constraints</i>: to prepare a trusted proxy received
+with integrity protection from a trusted source that is not known to
+supply the appropriate constraints.
+
+<li> <i>Grant permissions</i>: to prepare a trusted proxy received
+with integrity protection from a trusted source that supplies
+appropriate constraints, if the proxy needs permission grants.
+
+<li> <i>Do nothing</i>: to use as a default when retrieving an
+optional configuration entry, or to prepare a non-secure proxy.
+
+</ul>
+
+<p>Static methods <code>Security.verifyObjectTrust</code> and
+<code>Security.grant</code> of the
+<code>net.jini.security.Security</code> class implement the trust
+verification and permission granting mechanisms, respectively.
+Constraints can be set on the proxy implementing the
+<code>RemoteMethodControl</code> interface by calling its
+<code>setConstraints</code> method. A
+<code>BasicProxyPreparer</code> uses these three mechanisms to
+implement the specifics of proxy preparation.
+
+<p>The next three sections describe the mechanics of proxy preparation
+using a <code>BasicProxyPreparer</code> instance that performs all three
+steps. For the purposes of this discussion, let's assume that a
+<code>BasicProxyPreparer</code> is constructed as follows:
+
+<pre>
+ new BasicProxyPreparer(true, <i>constraints</i>, <i>permissions</i>)
+</pre>
+
+<p>where the argument <code>true</code> indicates that the proxy
+should be verified for trust, <i>constraints</i> is a
+<code>MethodConstraints</code> object (an object containing the
+per-method constraints to set on the proxy), and <i>permissions</i> is
+an array containing the <code>java.security.Permission</code>s to be
+granted to the proxy.
+
+<p>The UML sequence diagrams (PDF files) referred to in the
+next three sections illustrate the proxy preparation and trust
+verification processes. Together, these diagrams depict a full scenario
+of verifying trust, granting permissions, and setting constraints:
+
+<ul>
+
+<li><a href="proxypreparation.pdf">Proxy Preparation (Figure 1)</a>:
+illustrates verifying trust, granting permissions, and setting new
+constraints on a proxy.
+
+<li> <a href="simpleproxyverification.pdf">Non-Smart Proxy Trust
+Verification (Figure 2)</a>: shows verifying trust of a non-smart proxy
+(for example, a simple Jini ERI proxy) using a
+<code>ProxyTrustVerifier</code>.
+
+<li> <a href="smartproxyverification.pdf">Smart Proxy Trust
+Verification (Figure 3)</a>: shows verifying trust of a smart proxy using a
+<code>ProxyTrustVerifier</code>.
+
+</ul>
+
+<p>Note: See this tutorial for <a
+href="http://www.togethersoft.com/services/practical_guides/umlonlinecourse/index.html#sequence-diagrams">a
+description of the syntax of UML sequence diagrams</a>.
+
+<p>Note that the <code>BasicProxyPreparer</code> class is designed to be
+subclassable, therefore the implementation of the
+<code>prepareProxy</code> method invokes <code>protected</code>
+methods on the instance (<code>verify</code>, <code>grant</code>,
+<code>setConstraints</code>, etc.) to allow a potential subclass to
+customize the instance behavior.
+
+<h4>3.2.1 Verifying Trust</h4>
+
+
+<p>The basic model for verifying trust in an object received from an
+untrusted source is to consult one or more <i>trust verifiers</i> (of
+type <code>net.jini.security.TrustVerifier</code>) that are
+essentially part of the "trusted computing base" (a term which means
+the platform's hardware and software that is fully trusted to enforce
+the security mechanisms and policies in place) to see if at least one
+of those verifiers trusts the object in question. If one trust
+verifier is unable to verify trust, then another one is consulted.
+This trust verification process is carried out by the
+<code>static</code> method <code>Security.verifyObjectTrust</code>.
+
+<p>The <code>Security.verifyObjectTrust</code> method obtains trust
+verifiers from a resource,
+<code>META-INF/services/net.jini.security.TrustVerifier</code>, which,
+in this distribution, is part of the file
+<code>jsk-resources.jar</code>, which is referenced by
+<code>jsk-platform.jar</code>. These built-in trust verifiers are
+provided to verify instances of classes in the Apache River release. The
+following table lists these trust verifier implementations along with
+a description of the instances they verify:
+
+<blockquote>
+<table summary="Describes the standard TrustVerifier implementations"
+ border=1 cellpadding=5>
+<th> <code>TrustVerifier</code> <th> Verified Instances
+
+<tr> <td valign="top"> <code>net.jini.constraint.<br>ConstraintTrustVerifier</code>
+ <td valign="top"> constraint classes in <code>net.jini.core.constraint</code>
+<tr> <td valign="top"> <code>net.jini.jeri.<br>BasicJeriTrustVerifier</code>
+ <td valign="top"> proxy produced by <code>BasicJeriExporter.export</code>,
+if the proxy's invocation handler is a standard
+<code>BasicInvocationHandler</code> instance containing a
+<code>BasicObjectEndpoint</code> instance, the proxy's class
+loader is trusted, and the proxy's server constraints and
+<code>Endpoint</code> are trusted
+
+<tr> <td valign="top"> <code>net.jini.jeri.ssl.<br>SslTrustVerifier</code>
+ <td valign="top"> client-related classes in the <code>net.jini.jeri.ssl</code> package
+<tr> <td valign="top"> <code>net.jini.jeri.kerberos.<br>KerberosTrustVerifier</code>
+ <td valign="top"> client-related classes in the <code>net.jini.jeri.kerberos</code> package
+<tr> <td valign="top"> <code>net.jini.security.proxytrust.<br>ProxyTrustVerifier</code>
+ <td valign="top"> proxy that can be verified by obtaining a trust verifier from the proxy's server
+<tr> <td valign="top"> <code>net.jini.discovery.<br>ConstrainableLookupLocatorTrustVerifier</code>
+ <td valign="top"> <code>ConstraintableLookupLocator</code> instances
+<tr> <td valign="top"> <code>com.sun.jini.discovery.<br>DiscoveryConstraintTrustVerifier</code>
+ <td valign="top"> discovery constraints
+</table>
+</blockquote>
+
+<p>Most clients will use one or more of the trust verifiers above
+(indirectly) when verifying trust in a proxy. However, a service will
+need to implement a special trust verifier for a smart proxy, or for a
+proxy produced by <code>BasicJeriExporter</code>.
+
+<p>Proxy preparation is initiated by invoking the
+<code>prepareProxy</code> method on a <code>BasicProxyPreparer</code>
+instance (constructed as above, with <i>verify</i> set to
+<code>true</code>), passing it the <i>proxy</i> to be prepared (see <a
+href="proxypreparation.pdf">Figure 1</a>). The
+<code>BasicProxyPreparer</code> instance initiates trust verification
+by invoking the <code>Security.verifyObjectTrust</code> method,
+passing the <i>proxy</i>, the value <code>null</code> (<i>loader</i>) to
+specify the context class loader, and the <i>constraints</i> (obtained
+from the instance itself) to use on any remote communication by the
+trust verification mechanism.
+
+<p>The <code>Security.verifyObjectTrust</code> method obtains the
+trust verifiers from the resource in the specified <i>loader</i> (if
+the trust verifiers have not already been obtained) and creates a
+<code>net.jini.security.TrustVerifier.Context</code> (<i>context</i>)
+containing the ordered list of trust verifiers. Next, the
+<code>isTrustedObject</code> method of each trust verifier is invoked,
+passing it the proxy to be verified and the trust verifier context,
+until one trust verifier returns <code>true</code>. A given trust
+verifier will return <code>true</code> if it can verify trust in the
+object passed to it. A trust verifier may also use the context passed
+to verify other component objects recursively, before deciding
+whether it trusts the object.
+
+<p>The <code>Security.verifyObjectTrust</code> method returns
+<code>true</code> if there is at least one trust verifier in the
+context that trusts the proxy.
+
+<p>A <code>net.jini.security.proxytrust.ProxyTrustVerifier</code>
+can verify a service proxy for which a trusted verifier can be obtained
+from the service's remote object in a pre-defined manner,
+requiring cooperation with the proxy and the service's
+remote object. The two typical cases that
+<code>ProxyTrustVerifier</code> handles are: verifying non-smart
+proxies (for example, a simple proxy returned by
+<code>BasicJeriExporter</code>) and verifying smart proxies that
+wrap simple (non-smart) proxies. These cases are described in
+the following two sections.
+
+<p><code>ProxyTrustVerifier</code> implements a trust verification
+mechanism that uses a trusted <i>bootstrap proxy</i> (either
+derived or obtained from the original proxy) to obtain a
+trust verifier from the server to use to verify the
+original proxy.
+
+<p>The reasoning behind this trust verification approach is as
+follows: if you trust the service (like your bank), and you
+obtain the trust verifier by communicating with the service
+through a trusted bootstrap proxy with server authentication and
+integrity, then you can trust the verifier returned by the
+service to verify the service proxy. After all, it is the
+service that knows best how to verify its own proxies.
+
+<h4>Non-Smart Proxy Trust Verification</h4>
+
+<p>If a non-smart proxy that is a dynamic proxy would be directly
+trusted by a local trust verifier if only its proxy class were
+defined by a class loader trusted by such a verifier, then the
+non-smart proxy can implement
+<code>net.jini.security.proxytrust.ProxyTrust</code> so that it
+can be verified by a
+<code>net.jini.security.proxytrust.ProxyTrustVerifier</code>. In
+this case, the service's remote object must also cooperate
+in <code>ProxyTrustVerifier</code>'s verification scheme by
+providing a <code>TrustVerifier</code> for its proxies as
+described in the section "Implementation Requirements for Trust
+Verification".
+
+<p>The mechanism implemented by <code>ProxyTrustVerifier</code>
+verifies non-smart proxies by performing the following:
+
+<ul>
+<li> Creates a "derivative bootstrap proxy" from the proxy,
+<li> Verifies trust in this derivative bootstrap proxy using the
+ locally trusted verifiers, and then
+<li> Uses the derivative bootstrap proxy to obtain, from the
+ service, a trust verifier for the proxy itself.
+</ul>
+
+<p>The details of this mechanism are implemented by the
+<code>ProxyTrustVerifier.isTrustedObject</code> method (depicted in <a
+href="simpleproxyverification.pdf">Figure 2</a>).
+
+The proxy itself implements <code>ProxyTrust</code> and, as such,
+is considered a bootstrap proxy. However, this proxy is not
+typically trusted because, in most cases, the proxy's class is
+defined by an untrusted class loader when the proxy is received
+by a remote virtual machine. In this case if certain conditions
+are met, the <code>ProxyTrustVerifier</code> creates a
+"derivative bootstrap proxy" using a dynamic proxy class defined
+by the parent class loader (which is typically a trusted class
+loader) with the identical invocation handler as the bootstrap
+proxy. If the derivative bootstrap proxy is trusted by one of
+the locally trusted trust verifiers available in the context
+(determined by invoking <code>isTrustedObject</code> on the
+<code>TrustVerifier.Context</code>), then the derivative
+bootstrap proxy is the bootstrap proxy.
+
+<p>If the derivative bootstrap proxy is trusted, then the
+<code>ProxyTrustVerifier</code> can obtain the trust verifier
+from the service. The <code>ProxyTrustVerifier</code> first sets
+constraints (obtained from the context) on the derivative
+bootstrap proxy so that it will obtain the trust verifier from
+the server in a secure way. Next, the
+<code>ProxyTrustVerifier</code> invokes the
+<code>ProxyTrust.getProxyVerifier</code> method on the bootstrap
+proxy to obtain the trust verifier. This invocation is a remote
+call to a "bootstrap remote object" that implements the
+<code>ProxyTrust</code> interface. The
+<code>getProxyVerifier</code> implementation can then call the
+ <code>ServerProxyTrust.getProxyVerifier</code> method on the
+service (which is a local method call) to obtain the trust
+verifier and then return the result. Note that the bootstrap
+remote object and the service remote object could be the same object; that is,
+the service object can implement <code>ProxyTrust</code>.
+If the service's remote object is exported to use
+<code>BasicInvocationDispatcher</code>, a separate bootstrap
+remote object is not needed, nor does the remote object's class
+need to implement <code>ProxyTrust</code>, because
+<code>BasicInvocationDispatcher</code> takes care of these details.
+In this case, however, the service's remote object will still
+need to implement <code>ServerProxyTrust</code> as described in
+the section <a href="#serverProxyTrust">"Implementing
+<code>ServerProxyTrust</code>"</a>.
+
+<p>After the <code>ProxyTrustVerifier</code> obtains the trust
+verifier from the service, it can then invoke the trust verifier's
+<code>isTrustedObject</code> method, passing it the original service proxy and
+the context, to determine whether the proxy is really a proxy that the
+service trusts.
+
+<h4>Smart Proxy Trust Verification</h4>
+
+<p>Smart proxies or other proxies that do not implement
+<code>ProxyTrust</code> and that cannot be verified directly by the
+built-in trust verifiers can also be verified by
+<code>net.jini.security.proxytrust.ProxyTrustVerifier</code>. A
+<code>ProxyTrustVerifier</code>, in verifying smart proxies, uses
+some mechanisms in addition to those described above for
+non-smart proxies that implement <code>ProxyTrust</code>
+directly. As with non-smart proxies verified by
+<code>ProxyTrustVerifier</code>, a smart proxy and its corresponding
+remote object must cooperate in
+<code>ProxyTrustVerifier</code>'s verification mechanism. The
+implementation requirements for service proxies and their remote objects
+are described in the section "Implementation
+Requirements for Trust Verification".
+
+<p>The mechanism implemented by <code>ProxyTrustVerifier</code>
+verifies smart proxies by performing the following:
+
+<ul>
+<li> Obtains a "bootstrap proxy" from the proxy,
+<li> Verifies trust in the bootstrap proxy using the locally trusted
+ verifiers, and then
+<li> Uses the bootstrap proxy to obtain, from the service, a trust
+ verifier for the proxy itself.
+</ul>
+
+<p>The details of this mechanism are implemented by the
+<code>ProxyTrustVerifier.isTrustedObject</code> method (depicted in <a
+href="smartproxyverification.pdf">Figure 3</a>). The
+<code>ProxyTrustVerifier</code> uses a special iterator,
+<code>ProxyTrustIterator</code>, to obtain the bootstrap proxy. This
+special iterator and the bootstrap proxy (from the iterator) are
+obtained as follows.
+
+<p>The <code>ProxyTrustVerifier</code> reflectively invokes a
+(typically private) method, <code>getProxyTrustIterator</code>, on the
+supplied proxy or the supplied proxy's invocation handler to obtain a
+<code>ProxyTrustIterator</code>. This iterator is used to obtain the
+bootstrap proxy, an object that must implement the interface
+<code>ProxyTrust</code>, which is a remote interface for obtaining a
+proxy trust verifier from the service. If the object returned from
+the iterator is not a <code>ProxyTrust</code> instance, then a
+<code>ProxyTrustIterator</code> is obtained from the returned object
+recursively. Otherwise, if the returned object does not implement the
+interface <code>RemoteMethodControl</code>, the
+<code>ProxyTrustIterator</code> is used again to obtain another
+candidate bootstrap proxy.
+
+<p>When the iterator returns a bootstrap proxy implementing
+<code>ProxyTrust</code> and <code>RemoteMethodControl</code>,
+the <code>ProxyTrustVerifier</code>
+verifies trust in the bootstrap proxy by using the locally trusted
+trust verifiers available in the context. This trust verification
+process is the same as described for the method
+<code>Security.verifyObjectTrust</code>.
+
+<p>If the bootstrap proxy is not trusted by the locally trusted
+verifiers available in the context (that is, the method
+<code>isTrustedObject</code> on the
+<code>TrustVerifier.Context</code> returns <code>false</code>),
+then if certain conditions are met, the
+<code>ProxyTrustVerifier</code> creates a "derivative bootstrap
+proxy" using a dynamic proxy class defined by the parent class
+loader (which is typically a trusted class loader) with the
+identical invocation handler as the bootstrap proxy. If the
+derivative bootstrap proxy is trusted by one of the locally
+trusted verifiers (determined by invoking
+<code>isTrustedObject</code> on the
+<code>TrustVerifier.Context</code>), then the derivative
+bootstrap proxy can be used as the bootstrap proxy.
+
+<p>Once trust in the bootstrap proxy (or derivative) has been established, the
+<code>ProxyTrustVerifier</code> can obtain the trust verifier from the
+service. The <code>ProxyTrustVerifier</code> first sets constraints
+(obtained from the context) on the bootstrap proxy so that it will
+obtain the trust verifier from the server in a secure way. Next, the
+<code>ProxyTrustVerifier</code> invokes the
+<code>ProxyTrust.getProxyVerifier</code> method on the bootstrap proxy
+to obtain the trust verifier. This invocation is a remote call to a
+"bootstrap remote object" that implements the <code>ProxyTrust</code>
+interface. The <code>getProxyVerifier</code> implementation can then
+call the
+ <code>ServerProxyTrust.getProxyVerifier</code> method on the service
+(which is a local method call) to obtain the trust verifier and then
+return the result. Note that the bootstrap remote object and the
+service's remote object could be the same object; that is, the service object can
+implement <code>ProxyTrust</code>.
+
+<p>After the <code>ProxyTrustVerifier</code> obtains the trust
+verifier from the service, it can then invoke the trust verifier's
+<code>isTrustedObject</code> method, passing it the service proxy and
+the context, to determine whether the proxy is really a proxy that the
+service trusts.
+
+<h4>Implementation Requirements for Proxy Trust Verification</h4>
+
+<p>There are two main kinds of service proxies: a "simple" proxy,
+that is, a "non-smart" proxy returned from export (like a JRMP
+stub), and a smart proxy that wraps the proxy returned from
+export. This section describes the verifiers that can be used to
+verify different categories of proxies, based on their
+characteristics, and explains the implementation requirements
+for service proxies and their respective remote objects.
+
+<p>A <code>BasicJeriTrustVerifier</code> can be used as a trust
+verifier for a Jini ERI proxy (a proxy returned by
+<code>BasicJeriExporter</code>) if that proxy's class is defined by a
+trusted class loader and uses <code>BasicInvocationHandler</code>
+and <code>BasicObjectEndpoint</code> containing locally
+verifiable endpoint instances (such as
+<code>net.jini.jeri.ssl.HttpsEndpoint</code> and
+<code>net.jini.jeri.kerberos.KerberosEndpoint</code>). This is
+not a typical case, though, because in most cases, the class of a
+Jini ERI proxy received by a remote VM will be defined by an
+untrusted class loader.
+
+<p>If a Jini ERI proxy satisfies all of
+<code>BasicJeriTrustVerifier</code>'s conditions for trust, except
+the condition regarding its dynamic proxy class's loader, then
+(on the asumption that the parent of that loader will be locally
+trusted) the service proxy and its remote object can cooperate
+in the verification mechanism provided by
+<code>ProxyTrustVerifier</code>. In this case, the proxy itself
+serves as the bootstrap proxy and must implement
+<code>ProxyTrust</code>. To facilitate this, the service's
+remote object can be exported with a
+<code>net.jini.jeri.ProxyTrustILFactory</code> which ensures that
+the service proxy implements <code>ProxyTrust</code> (in addition
+to <code>RemoteMethodControl</code>). The service's remote object
+must also implement the
+<code>ServerProxyTrust.getProxyVerifier</code> method to return a
+verifier for the proxy (as described below in the section <a
+href="#serverProxyTrust">"Implementing
+<code>ServerProxyTrust</code>"</a>).
+
+<p>If a Jini ERI proxy that could be trusted by clients (perhaps
+by <code>ProxyTrustVerifier</code> as described above) is used
+inside a smart proxy that will not be trusted directly by
+clients, a <code>ProxyTrustILFactory</code> can be used to cause
+the inner Jini ERI proxy to also be an instance of
+<code>ProxyTrust</code> (in addition to
+<code>RemoteMethodControl</code>). To fit into the
+<code>ProxyTrustVerifier</code> mechanism, the outer proxy must
+implement the <code>getProxyTrustIterator</code> method to return
+a <code>ProxyTrustIterator</code> whose <code>next</code> method
+returns the inner proxy (referred to as the "bootstrap proxy"
+above). The
+<code>net.jini.security.proxytrust.SingletonProxyTrustIterator</code>
+is a simple implementation of <code>ProxyTrustIterator</code>
+whose <code>next</code> method returns the object the instance is
+constructed with. Additionally, the service's remote object must
+implement the <code>ServerProxyTrust</code> interface to return a
+trust verifier that verifies the proxy (as described below in the
+section <a href="#serverProxyTrust">"Implementing
+<code>ServerProxyTrust</code>"</a>).
+
+<p>For other smart proxies or Jini ERI proxies containing a custom
+invocation handler or custom endpoint that will not be trusted
+directly by clients, a
+<code>net.jini.security.proxytrust.ProxyTrustExporter</code> can be
+used to combine that proxy with a trustable bootstrap proxy, such that
+the client can use <code>ProxyTrustVerifier</code> to verify that the
+aggregate proxy can be trusted. The service's remote object would
+need to implement <code>ServerProxyTrust.getProxyVerifier</code>
+to return a verifier for the aggregate proxy.
+
+
+<h5><a name="serverProxyTrust"></a>Implementing <code>ServerProxyTrust</code></h5>
+
+<p>A service's remote object should implement
+the <code>ServerProxyTrust</code> interface
+to provide a trust verifier for its proxies that simply
+compares a known canonical service proxy with the yet-to-be-trusted proxy,
+testing that the proxies are <i>trust equivalent</i>. An object is
+considered trust equivalent to a known, trusted object if it is
+equivalent in trust, content, and function to that trusted object. The
+<code>net.jini.security.proxytrust.TrustEquivalence</code> interface
+can be implemented by trusted objects (say component objects in the
+proxy) that need to allow other objects to be checked for trust
+equivalence. The <code>TrustEquivalence</code> interface has a
+single method, <code>checkTrustEquivalence</code>, for checking trust
+equivalence.
+
+<p>An implementation of a basic proxy trust verifier, which could be
+returned by an implementation of the
+<code>ServerProxyTrust.getProxyVerifier</code> method, is the <a
+href="api/com/sun/jini/proxy/BasicProxyTrustVerifier.html"><code>com.sun.jini.proxy.BasicProxyTrustVerifier</code></a>
+(see the source code <a
+href="../source/src/com/sun/jini/proxy/BasicProxyTrustVerifier.java"><code>BasicProxyTrustVerifier.java</code></a>
+for implementation details).
+
+
+<h4>3.2.2 Granting Permissions</h4>
+
+<p>Once trust in a proxy has been verified, the client may wish to
+grant permissions to the proxy so that future invocations on the proxy
+will function correctly. This task can also be accomplished through a
+<code>BasicProxyPreparer</code>.
+
+<p>Permissions can only be granted to a proxy if dynamic
+permission grants are supported by the installed security policy
+implementation. This release provides a
+<code>java.security.Policy</code> implementation,
+<code>net.jini.security.policy.DynamicPolicyProvider</code>, that
+supports such dynamic granting of permissions at runtime. The
+<code>DynamicPolicyProvider</code> implements the interface
+<code>net.jini.security.policy.DynamicPolicy</code>, which defines
+methods for granting permissions on the granularity of a class loader.
+For an application to grant a specific permission, the calling context
+must have <code>net.jini.security.GrantPermission</code> for the
+permission being granted. Note that the <code>Security</code> class
+has a <code>static</code> method, <code>grantSupported</code>, that
+can be called to check whether dynamic permission grants are
+supported.
+
+<p>A <code>BasicProxyPreparer</code> grants permissions to the proxy
+on the granularity of the proxy's class loader. The preparer invokes
+its own <code>getPermissions</code> method, passing the
+proxy, to obtain the permissions to grant. If there are permissions
+to grant, the preparer invokes <code>Security.grant</code> with the
+proxy's class (<i>proxyClass</i>) and the <i>permissions</i> to grant
+(see Figure 1).
+
+<p>The <code>Security.grant</code> operation will delegate to the
+security policy implementation to grant the permissions if the policy
+supports dynamic permission grants via <code>DynamicPolicy</code>.
+This <code>Security.grant</code> method grants the specified
+permissions to all protection domains that are associated with the
+class loader of the given class (which, in this example, is the
+proxy's class) and passes at least the principals of the current
+subject (if any). If grants are not supported or the calling context
+does not have the requisite <code>GrantPermission</code> for each
+permission to grant, then a <code>SecurityException</code> is thrown.
+
+<h4>3.2.3 Setting Constraints</h4>
+
+<p>Once trust is verified and permissions (if any) have been granted
+to the proxy, constraints should be set on the proxy to ensure the
+desired level of security on future remote invocations through the
+proxy. A <code>BasicProxyPreparer</code>'s final task is to set
+constraints (if any) on the proxy, resulting in a new proxy (with the
+constraints set), and to return that proxy as the result of the
+<code>prepareProxy</code> operation (see Figure 1).
+
+<p>A proxy must implement the interface
+<code>net.jini.core.constraint.RemoteMethodControl</code> to enable
+the setting of constraints. Constraints are set by invoking the
+proxy's <code>setConstraints</code> method, passing a
+<code>MethodConstraints</code> object containing the constraints to
+set. A <code>BasicProxyPreparer</code> obtains the method constraints
+from itself by invoking its own <code>getMethodConstraints</code>
+method and then sets these constraints on the proxy. The
+copy of the proxy (<i>new proxy</i>) returned by the
+<code>setConstraints</code> method is returned as the result of
+preparing the proxy.
+
+<h3>3.3 Code Integrity</h3>
+
+The <code>net.jini.core.constraint.Integrity</code> constraint should
+be set on a proxy if remote calls through that proxy require integrity
+protection on both the in-band call data, transmitted as part of the
+remote call, and the code downloaded out-of-band as a result of the
+call. A communication mechanism enforcing an <code>Integrity</code>
+constraint can use the <code>Security.verifyCodebaseIntegrity</code>
+method to determine if all URLs in a codebase provide content
+integrity, based on whatever
+<code>net.jini.security.IntegrityVerifier</code> instances are
+configured.
+
+<p>The application does not have to worry about verifying codebase
+integrity itself; that task is carried out by the underlying
+communication mechanism enforcing the <code>Integrity</code>
+constraint. Such communication mechanisms should verify the
+codebase URLs for integrity when unmarshalling objects during a remote
+call.
+
+<p>The <code>Security.verifyCodebaseIntegrity</code> method obtains
+integrity verifiers from a resource,
+<code>META-INF/services/net.jini.security.IntegrityVerifier</code>,
+which, in this distribution (and similar to trust verifiers),
+is part of the file <code>jsk-resources.jar</code>. The following
+table lists the standard integrity verifier implementations along
+with the type of URLs they verify. <p>
+
+<blockquote>
+<table summary="Describes the standard IntegrityVerifier implementations"
+ border=1 cellpadding=5>
+<th> <code>IntegrityVerifier</code> <th> Verified URLs
+<tr> <td> <code>net.jini.url.httpmd.HttpmdIntegrityVerifier</code>
+ <td> HTTPMD
+<tr> <td> <code>net.jini.url.https.HttpsIntegrityVerifier</code>
+ <td> HTTPS
+<tr> <td> <code>net.jini.url.file.FileIntegrityVerifier</code>
+ <td> FILE
+</table>
+</blockquote>
+
+<p>The mechanism implemented by
+<code>Security.verifyCodebaseIntegrity</code> is pluggable (since it
+uses a resource), so that other <code>IntegrityVerifier</code>
+implementations can be configured if a deployment requires other URL
+types to have their integrity protection verified.
+
+<h4>HTTPMD URLs</h4>
+
+<p>A deployment requiring integrity protection for downloaded code may
+wish to make use of HTTPMD URLs, introduced in this release. An
+HTTPMD URL includes a message digest for the data retrieved from the
+URL. The URL input stream ensures that the data has the correct
+message digest when the end of file for the stream is reached.
+
+<p>The reasoning behind why HTTPMD URLs can be used to verify code
+integrity is as follows. An HTTPMD URL (configured in a codebase path
+for an application and subsequently used by the underlying
+communication mechanism as a class annotation) is transmitted in band
+as part of a remote call. Because the HTTPMD URL (both the URL and
+message digest component) is transmitted in band, the message digest
+can be trusted to the same extent as any other data transmitted in the
+call. If the HTTPMD URL is communicated with integrity, the value of
+the message digest must be correct. Therefore, the URL input stream
+can use the message digest to verify correctly the integrity of the
+stream contents.
+
+<p>The URL protocol handlers in J2SE can be configured with additional
+protocol handlers, over and above built-in handlers (such as for HTTP
+and FILE URLs). To configure the use of HTTPMD URLs for an
+application, the "java.protocol.handler.pkgs" system property should
+be set to "net.jini.url".
+
+<p>For convenience, the tool <a
+href="api/com/sun/jini/tool/ComputeHttpmdCodebase.html"><code>ComputeHttpmdCodebase</code></a>
+can be used to compute message digests for a codebase with HTTPMD
+URLs.
+
+
+<h2>4 Jini Extensible Remote Invocation </h2>
+
+<p>Jini ERI, defined in the <a href="api/net/jini/jeri/package-summary.html"><code>net.jini.jeri</code> package</a>, is a
+pluggable implementation of the Java RMI programming model that
+supports the remote object export model defined in the
+<a href="api/net/jini/export/package-summary.html"><code>net.jini.export</code> package</a> and supports the security model
+described above, including invocation constraints, remote method
+control, and the trust verification model. Jini ERI allows
+customization of client-side and server-side remote invocation
+behavior and also allows the use of a variety of communication
+transports.
+
+<p>See the <a
+href="api/net/jini/jeri/package-summary.html"><code>net.jini.jeri</code> package
+documentation</a> for more information.
+
+<h2>5 Service Providers</h2>
+
+<p>While this release provides a pluggable infrastructure with many
+avenues for customization, it also includes many provider
+implementations that are sufficient for most applications. These
+providers are summarized in this section.
+
+<p>Many applications will use the supplied providers, having one or
+more of them specified in deployment-time information in a
+resource or configuration. Other applications may implement one or more
+of their own providers if their application deployment requires a
+more specific feature that is not implemented by the built-in
+providers.
+
+<p>In general, an application developer or deployer does not need to
+understand all APIs used by providers. Such APIs only need to be
+well-understood if one is developing a new service provider or
+customizing some aspect of an existing one.
+
+<h3>5.1 Providers located by resources</h3>
+
+<p>The following is a list of provider interfaces and associated
+implementations that are located via resources (and specified in
+<code>jsk-resources.jar</code>). For the most part, these
+provider interfaces and implementations are used by other
+infrastructure implementations. Applications generally don't
+need to program to either the interfaces or the implementations
+of these kinds of providers with some minor exceptions: to
+implement <code>TrustVerifier</code> for a smart/custom proxy,
+and to reference a <code>Configuration</code>.
+
+<blockquote>
+<p> <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/rmi/server/RMIClassLoaderSpi.html"><code>java.rmi.server.RMIClassLoaderSpi</code></a> (defined in J2SE)
+<ul>
+<li> <code>net.jini.loader.pref.PreferredClassProvider</code>
+<li> <code>net.jini.loader.pref.RequireDlPermProvider</code>
+</ul>
+
+<p> <a href="api/net/jini/export/ServerContext.Spi.html"><code>net.jini.export.ServerContext.Spi</code></a>
+<ul>
+<li> <code>net.jini.jrmp.JrmpServerContext</code>
+</ul>
+
+<p> <a href="api/net/jini/security/TrustVerifier.html"><code>net.jini.security.TrustVerifier</code></a>
+<ul>
+<li> <code>net.jini.constraint.ConstraintTrustVerifier</code>
+<li> <code>net.jini.jeri.BasicJeriTrustVerifier</code>
+<li> <code>net.jini.jeri.ssl.SslTrustVerifier</code>
+<li> <code>net.jini.jeri.kerberos.KerberosTrustVerifier</code>
+<li> <code>net.jini.security.proxytrust.ProxyTrustVerifier</code>
+<li> <code>net.jini.discovery.ConstrainableLookupLocatorTrustVerifier</code>
+<li> <code>com.sun.jini.discovery.DiscoveryConstraintTrustVerifier</code>
+</ul>
+
+<p> <a href="api/net/jini/security/IntegrityVerifier.html"><code>net.jini.security.IntegrityVerifier</code></a>
+<ul>
+<li> <code>net.jini.url.httpmd.HttpmdIntegrityVerifier</code>
+<li> <code>net.jini.url.https.HttpsIntegrityVerifier</code>
+<li> <code>net.jini.url.file.FileIntegrityVerifier</code>
+</ul>
+
+<p> <a href="api/net/jini/config/Configuration.html"><code>net.jini.config.Configuration</code></a>
+<ul>
+<li> <code>net.jini.config.ConfigurationFile</code>
+</ul>
+
+<p> <a href="api/net/jini/security/policy/DynamicPolicy.html"><code>net.jini.security.policy.DynamicPolicy</code></a> and
+ <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/security/Policy.html"><code>java.security.Policy</code></a>
+<ul>
+<li> <code>net.jini.security.policy.DynamicPolicyProvider</code>
+</ul>
+</blockquote>
+
+<h3>5.2 Providers specified in configurations</h3>
+
+<p>The providers in this section are those that a deployer may specify
+explicitly in a configuration. Applications typically program to the
+interfaces of these providers, but not their implementations. Many
+applications can utilize the implementations available in the
+Apache River release, and therefore, don't need to worry about how to implement a
+specific interface, only how to use it.
+
+<blockquote>
+<p> <a href="api/net/jini/export/Exporter.html"><code>net.jini.export.Exporter</code></a>
+<ul>
+<li> <code>net.jini.jeri.BasicJeriExporter</code>
+<li> <code>net.jini.jrmp.JrmpExporter</code>
+<li> <code>net.jini.iiop.IiopExporter</code>
+<li> <code>net.jini.activation.ActivationExporter</code>
+<li> <code>net.jini.security.proxytruxt.ProxyTrustExporter</code>
+</ul>
+
+<p> <a href="api/net/jini/security/ProxyPreparer.html"><code>net.jini.security.ProxyPreparer</code></a>
+<ul>
+<li> <code>net.jini.security.BasicProxyPreparer</code>
+</ul>
+
+<p> <a href="api/net/jini/core/constraint/InvocationConstraint.html"><code>net.jini.core.constraint.InvocationConstraint</code></a>
+<ul>
+<li><code>net.jini.core.constraint.ClientAuthentication</code>
+<li><code>net.jini.core.constraint.ClientMaxPrincipal</code>
+<li><code>net.jini.core.constraint.ClientMaxPrincipalType</code>
+<li><code>net.jini.core.constraint.ClientMinPrincipal</code>
+<li><code>net.jini.core.constraint.ClientMinPrincipalType</code>
+<li><code>net.jini.core.constraint.Confidentiality</code>
+<li><code>net.jini.core.constraint.ConnectionAbsoluteTime</code>
+<li><code>net.jini.core.constraint.ConnectionRelativeTime</code>
+<li><code>net.jini.core.constraint.ConstraintAlternatives</code>
+<li><code>net.jini.core.constraint.Delegation</code>
+<li><code>net.jini.core.constraint.DelegationAbsoluteTime</code>
+<li><code>net.jini.core.constraint.DelegationRelativeTime</code>
+<li><code>net.jini.core.constraint.Integrity</code>
+<li><code>net.jini.core.constraint.RelativeTimeConstraint</code>
+<li><code>net.jini.core.constraint.ServerAuthentication</code>
+<li><code>net.jini.core.constraint.ServerMinPrincipal</code>
+</ul>
+
+<p> <a href="api/net/jini/jeri/ServerEndpoint.html"><code>net.jini.jeri.ServerEndpoint</code></a>
+<ul>
+<li> <code>net.jini.jeri.ssl.SslServerEndpoint</code>
+<li> <code>net.jini.jeri.ssl.HttpsServerEndpoint</code>
+<li> <code>net.jini.jeri.tcp.TcpServerEndpoint</code>
+<li> <code>net.jini.jeri.kerberos.KerberosServerEndpoint</code>
+<li> <code>net.jini.jeri.http.HttpServerEndpoint</code>
+</ul>
+</blockquote>
+
+<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>
+
+
Added: incubator/river/site/trunk/content/river/docs/build.mdtext
URL: http://svn.apache.org/viewvc/incubator/river/site/trunk/content/river/docs/build.mdtext?rev=1043362&view=auto
==============================================================================
--- incubator/river/site/trunk/content/river/docs/build.mdtext (added)
+++ incubator/river/site/trunk/content/river/docs/build.mdtext Wed Dec 8 11:34:36 2010
@@ -0,0 +1,225 @@
+<!--
+ ! 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>
+<body text="#000000" bgcolor="#ffffff" link="#9b37cc"
+ vlink="#cc1877" alink="#ffffff">
+
+<title>Building the Apache River Packages</title>
+<a name="TOP">
+<center><h1>Building the Apache River Packages</h1></center>
+
+<br>
+The Apache River distribution includes support for
+generating binary (JAR) files and documentation from the provided source code
+using the Apache Ant build tool (available from the Ant project site at
+Apache.org, <a href="http://ant.apache.org">
+ <code>http://ant.apache.org</code></a>).
+<p>
+This page describes how to use <code>ant</code> to build the distribution from
+the source code. This Ant build process was originally based on Geoff Arnold's
+Ant build script, located at <a href="http://user-garnold.jini.org">
+<code>http://user-garnold.jini.org</code> (link dead)</a>, and we thank him for his
+contribution.
+
+<p>
+It is not necessary to build the JAR files from source code to get started with
+Jini technology. The JAR files are provided for you as part of the starter kit,
+depending on your installation options. The location of the JAR files is
+documented in <a href="info-index.html#examine">info-index.html</a> . In the
+instructions below, <B><VAR>install_dir</VAR></B> is the directory into which
+you installed the Apache River distribution.
+
+<p>
+<b>NOTE</b>:<i> Please do not attempt to build the Apache River JAR files
+without first taking referencing the
+<a href="http://developer.java.sun.com/developer/products/jini/tested.html">
+platforms on which the starter kit has been tested (link dead)</a></i>.
+
+<p>
+<hr>
+<h2>Build instructions</h2>
+
+<p>
+The following prerequisites must be met before a build can be executed:
+<ul>
+ <li>
+ The <b><code>bin</code></b> directory of the Java(TM) 2 SDK, Standard
+ Edition, v 1.4 (or later) must be in your executable search path. You can
+ obtain the Java software at <a href="http://java.sun.com">
+ <code>http://java.sun.com</code></a> .
+ </li>
+ <p>
+ <li>
+ Apache Ant, version 1.6.2 or later, must be installed on your system. You
+ can obtain the Ant software from Ant's project site at
+ <a href="http://ant.apache.org"><code>http://ant.apache.org</code></a> .
+ </li>
+ <p>
+</ul>
+
+<p>
+The following build options are currently available:
+<ul>
+ <li>
+ The <b><code>debug</code></b> parameter can be used to override the
+ default debuglevel values. The possible values are "<code>none</code>",
+ "<code>lines</code>", "<code>source</code>", and "<code>vars</code>".
+ If two or more values are used together, they must be comma-separated
+ (eg, "<code>lines,source,vars</code>"). Refer to the javac documentation
+ or the javac task section of the Ant documentation for further details
+ regarding these debuglevel options.
+ <pre>
+ ant -Ddebug=lines,source,vars <<i>target</i>>
+ </pre
+ </li>
+</ul>
+
+<p>
+To build the starter kit JAR files, you must:
+
+<pre>
+ cd <B><VAR>install_dir</VAR></B>
+
+ ant <<i>target</i>>
+</pre>
+
+where the basic targets are:
+<blockquote>
+ <dl>
+ <dt>
+ <b>all.build</b><br>
+ This target is also the default target and can be invoked by simply running
+ <code>ant</code> without specifying any target. This target compiles the
+ class files for all of the distribution source code, generates Java Remote
+ Method Invocation (Java RMI) stub classes, and generates the configentry
+ files. The class files and configentry files will be placed in the following
+ directories, respectively:
+ <br><br>
+ <code><B><VAR>install_dir</VAR></B>/build/classes</code>
+ <br>
+ <code><B><VAR>install_dir</VAR></B>/build/configentry</code>
+ <br><br>
+ Additionally, this target will build all subprojects (currently 'qa' and 'examples/hello').
+ <p>
+ <dt>
+ <b>jars</b><br>
+ Creates the JAR files for the distribution, using the compiled class files.
+ The compiled class files must already have been created. The resulting JAR
+ files will be placed in the following directories:
+ <br><br>
+ <code><B><VAR>install_dir</VAR></B>/lib</code> <br>
+ <code><B><VAR>install_dir</VAR></B>/lib-dl</code> <br>
+ <code><B><VAR>install_dir</VAR></B>/lib-ext</code><br>
+ <br>
+ <b>NOTE</b>:
+ <br>
+ <i>
+ During the jars build, warning messages similar to the following are generated:
+ </i>
+ <br><br>
+ <code>[java] Nested class LogManager$Probe has different preferred state than outer class LogManager</code>
+ <br><br>
+ <i>
+ Messages of this sort are expected and pose no concern to the resulting build.
+ </i>
+
+ <p>
+ <dt>
+ <b>clean</b><br>
+ Removes the class files, configentry files, docs, JAR files, and all associated
+ directories generated during the build.
+
+ <p>
+ <dt>
+ <b>doc</b>
+ Generates API documentation for the starter kit, using the Javadoc(TM) tool.
+ The documentation will be placed in the following directory:
+ <br><br>
+ <code><B><VAR>install_dir</VAR></B>/doc/api</code>
+
+ <p>
+ <dt>
+ <b>spec-doc</b><br>
+ Generates the specification-only documentation for the starter kit, using the Javadoc(TM) tool.
+ The documentation will be placed in the following directory:
+ <br><br>
+ <code><B><VAR>install_dir</VAR></B>/doc/specs/api</code>
+
+ <p>
+ <dt>
+ <b>release</b><br>
+ This target will compile everything, generate the jar files, generate the javadoc,
+ and produce the distribution bundles (binary and source) in the top-level "dist"
+ directory.
+
+ <p>
+ <dt>
+ <b>install-policy</b> and <b>uninstall-policy</b><br>
+ This target will install/uninstall jsk-policy.jar into the JVM extensions directory.
+
+ </dl>
+</blockquote>
+
+<h2>Testing your Build</h2>
+<p>There are three test harnesses:
+<ul>
+ <li><b>Unit Tests:</b> The build target is <b>test</b>. JUnit testing is provided
+ because of the popularity of this Unit test framework, reducing the initial
+ learning curve for developers, enabling more developers
+ to participate.
+ </li>
+ <li><b>Regression Tests:</b> The build target is <b>jtreg</b> from the build.xml
+ file in the qa directory. Jtreg is the Regression Test framework
+ for Jini, also utilised by Sun's JRE, you'll need to download jtreg
+ separately from <a href="http://openjdk.java.net/jtreg/">openjdk.java.net/jtreg</a>
+ and ensure jtreg is available on your execution path.
+ </li>
+ <li><b>Integration and Compliance Tests:</b> The build target is <b>qa.run</b> from
+ the main build.xml file.
+ The Jini QA Test Harness, was developed by Sun, specifically to cater for testing
+ of the Jini Architecture, more information can be found in the qa directory.
+ </li>
+</ul>
+</p>
+
+
+<p>
+If you make any modifications and/or corrections to this build process and
+want those changes considered for use in our next release, please submit your
+modifications to <code>river-user@incubator.apache.org</code> for consideration.
+
+<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.
+
+</body>
+</html>
Added: incubator/river/site/trunk/content/river/docs/index.mdtext
URL: http://svn.apache.org/viewvc/incubator/river/site/trunk/content/river/docs/index.mdtext?rev=1043362&view=auto
==============================================================================
--- incubator/river/site/trunk/content/river/docs/index.mdtext (added)
+++ incubator/river/site/trunk/content/river/docs/index.mdtext Wed Dec 8 11:34:36 2010
@@ -0,0 +1,81 @@
+<!--
+ ! 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.
+ !-->
+<body text="#000000" bgcolor="#ffffff" link="#9b37cc"
+ vlink="#cc1877" alink="#ffffff">
+
+<title>Apache River Release Kit Index</title>
+
+<center><h1>Apache River Release<BR>v2.1.2</h1></center>
+<hr>
+<p>
+The Apache River release is based on the following two major contributions:
+the Jini Technology Starter Kit, and Service UI. In the documentation for this
+release, you may see historical references to those releases.
+
+<p>
+<UL>
+<LI><B><a href="info-index.html">Getting Started & More</a></B>
+<p>
+<LI><B>Informative reading</B>
+ <ul>
+ <li><i><a href="arch2_0.html">Jini<font size="-1"><sup>TM</sup></font> Architecture Specification Version 2.0 Extensions</a></i>
+ <li><i><a href="specs/html/jini-spec.html">Jini<font size="-1"><sup>TM</sup></font> Architecture Specification Version 1.0</a></i>
+
+</ul>
+<p>
+<LI><B><a href="release-notes/index.html">Release Notes</a></B>
+<p>
+<LI><B><a href="manpages-index.html">Manual Pages</a></B> for services, utilities, and tools
+<p>
+<LI><B><a href="spec-index.html">Specifications</a></B>
+<p>
+<LI><B>API documentation</B>
+ <UL>
+ <LI><a href="api/index.html"> Frames version</a>
+ <LI><a href="api/overview-summary.html"> No Frames version</a>
+ </UL>
+
+<p>
+
+</UL>
+<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.
+
+</body>
+
+
+
+
+
+