Modified: river/jtsk/skunk/qa_refactor/trunk/src/com/sun/jini/outrigger/package.html URL: http://svn.apache.org/viewvc/river/jtsk/skunk/qa_refactor/trunk/src/com/sun/jini/outrigger/package.html?rev=1634322&r1=1634321&r2=1634322&view=diff ============================================================================== --- river/jtsk/skunk/qa_refactor/trunk/src/com/sun/jini/outrigger/package.html (original) +++ river/jtsk/skunk/qa_refactor/trunk/src/com/sun/jini/outrigger/package.html Sun Oct 26 13:17:28 2014 @@ -1,2110 +1,2124 @@ -<!-- - ! 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 BGCOLOR="white"> - -This is an implementation of a JavaSpaces technology-enabled service. -In addition to implementing the basic {@link net.jini.space.JavaSpace} -interface, it all implements the {@link net.jini.space.JavaSpace05} -extension. <p> - -There are two ways to run Outrigger — as a transient space that loses -its state between executions, or as a persistent space that maintains state -between executions. The first is implemented by -<CODE>com.sun.jini.outrigger.TransientOutriggerImpl</CODE>; the second by -<CODE>com.sun.jini.outrigger.PersistentOutriggerImpl</CODE>. <CODE>TransientOutriggerImpl</CODE> -can only be run as a non-activatable server, while -<CODE>PersistentOutriggerImpl</CODE> can be run as an activatable or -non-activatable server.<p> - -<code>PersistentOutriggerImpl</code> relies on a pluggable persistence -layer, {@link com.sun.jini.outrigger.Store}. Which implementation of the -<code>Store</code> interface to use is controlled by the <a -href="#store"><code>store</code></a> configuration entry. Unlike some -previous releases there is no default <code>Store</code> implementation. -<p> - -This release includes one implementation of the <code>Store</code> -interface. {@link com.sun.jini.outrigger.snaplogstore.LogStore -com.sun.jini.outrigger.snaplogstore.LogStore}, also called -<em>Snaplogstore</em>. Snaplogstore was introduced in the 2.1beta2 -release. The original implementation of the <code>Store</code> interface, -<code>com.sun.jini.outrigger.logstore.LogStore</code>, or <em>Logstore</em> -for short, is no longer available. Snaplogstore and Logstore have different -scalability characteristics, so if you were using Logstore in the past you -many want to evaluate how your application works with Snaplogstore. - -Because there is no default <code>Store</code> implementation if you are -using <code>PersistentOutriggerImpl</code> you will need to provide a value -for the <a href="#store"><code>store</code></a> configuration entry (as -well as the <a -href="#persistenceDirectory"><code>persistenceDirectory</code></a> -configuration entry). -<p> - -The storage formats used by Snaplogstore and Logstore are mutually -incompatible.<p> - -The JAR file <code>outrigger.jar</code>, included in the <code>lib</code> -subdirectory of the Apache River release -installation, contains the classes for <code>TransientOutriggerImpl</code>. -  <code>outrigger.jar</code> also includes, via a JAR file manifest -classpath directive, a reference to -<code>jsk-lib.jar</code>. <code>jsk-lib.jar</code> must be in the same -directory as <code>outrigger.jar</code> for Outrigger to operate -properly.<p> - -<code>outrigger.jar</code> also includes, via a JAR file manifest classpath -directive, a reference to <code>outrigger-snaplogstore.jar</code>. -<code>outrigger-snaplogstore.jar</code> adds the classes necessary to run -<code>PersistentOutriggerImpl</code> with the Snaplogstore implementation of -<code>Store</code>, and must be in the same directory as -<code>outrigger.jar</code> for <code>PersistentOutriggerImpl</code> to -operate properly with snaplogstore.<p> - -The JAR files <code>outrigger-dl.jar</code> and <code>jsk-dl.jar</code> in -the <code>lib-dl</code> directory contain the classes needed to -instantiate Outrigger's proxy objects in a client. Outrigger's codebase -should include both of these files.<p> - -None of the JAR files discussed in the previous paragraphs include classes -from <code>jsk-platform.jar</code>. On the server side service starter, the -service launcher utility, ensures that -<code>jsk-platform.jar</code> is available to Outrigger. On the client it -is the responsibility of the client to make <code>jsk-platform.jar</code> -available. Typically this is done by including -<code>jsk-platform.jar</code> in the client's classpath.<p> - -Outrigger's top level proxy implements {@link net.jini.admin.Administrable} -in addition to <code>JavaSpace</code> and -<code>JavaSpace05</code>. Outrigger's <em>admin proxy</em> can be obtained -by calling {@link net.jini.admin.Administrable#getAdmin -Administrable.getAdmin}. The admin proxy implements {@link -net.jini.admin.JoinAdmin} and {@link com.sun.jini.admin.DestroyAdmin}. The -admin proxy will also implement {@link -com.sun.jini.outrigger.ConstrainableJavaSpaceAdmin} if the server has been -set up with a Java(TM) remote method invocation (Java RMI) implementation -that supports constraints, or {@link com.sun.jini.outrigger.JavaSpaceAdmin} -if constraints are not supported. However, -<code>ConstrainableJavaSpaceAdmin</code> and <code>JavaSpaceAdmin</code> -have been depreciated and should not be used. -<p> - -This document provides the following information about Outrigger: <ul> - -<li> <a href="#configuration">Configuring Outrigger</a> -<li> <a href="#Blocking Queries">Blocking Queries</a> -<li> <a href="#access_control">Access Control Permission Targets</a> -<li> <a href="#logging">Logging</a> -<li> <a href="#examples">Examples for Running Outrigger</a> - -</ul> <p> - - -<a name="configuration"> -<H2>Configuration Entries Consulted By Outrigger</H2> -</a> - -The Outrigger service implementation consults a number of configuration -entries. Most deployments will find it useful to provide values for one or -more of the following configuration entries: - -<ul> -<li><a href="#persistenceDirectory"><code>persistenceDirectory</code></a> - (required if using <CODE>PersistentOutriggerImpl</CODE>) -<li><a href="#store"><code>store</code></a> - (required if using <CODE>PersistentOutriggerImpl</CODE>) -<li><a href="#initialLookupGroups"><code>initialLookupGroups</code></a> -<li><a href="#initialLookupLocators"><code>initialLookupLocators</code></a> -<li><a href="#initialLookupAttributes"><code>initialLookupAttributes</code></a> -</ul> - -Each of these, except for <code>persistenceDirectory</code> and -<code>store</code>, has reasonable defaults.<p> - -Deployments that want to use a Java RMI implementation other than Jini -extensible remote invocation (Jini ERI) over TCP/IP on a random port will -need to provide a value for the <a href="#serverExporter"> -<code>serverExporter</code></a> configuration entry. Deployments that use -multicast discovery and have special requirements may need to provide -values for the various {@link net.jini.discovery.LookupDiscovery} -configuration entries.<p> - -Secure deployments will need to provide values for most if not -all of these configuration entries: - -<ul> -<li><a href="#serverExporter"><code>serverExporter</code></a> -<li><a href="#loginContext"><code>loginContext</code></a> -<li><a href="#listenerPreparer"><code>listenerPreparer</code></a> -<li><a href="#recoveredListenerPreparer"> - <code>recoveredListenerPreparer</code></a> - (if using <CODE>PersistentOutriggerImpl</CODE>) -<li><a href="#transactionManagerPreparer"> - <code>transactionManagerPreparer</code></a> -<li><a href="#recoveredTransactionManagerPreparer"> - <code>recoveredTransactionManagerPreparer</code></a> - (if using <CODE>PersistentOutriggerImpl</CODE>) -<li><a href="#activationIdPreparer"><code>activationIdPreparer</code></a> - (if using activation) -<li><a href="#activationSystemPreparer"> - <code>activationSystemPreparer</code></a> - (if using activation) -<li><a href="#lookupLocatorPreparer"><code>lookupLocatorPreparer</code></a> -<li><a href="#recoveredLookupLocatorPreparer"> - <code>recoveredLookupLocatorPreparer</code></a> - (if using <CODE>PersistentOutriggerImpl</CODE>) -</ul> - -plus the following configuration entries from -{@link net.jini.discovery.LookupDiscovery} : - -<ul> -<li><code>registrarPreparer</code> -<li><code>discoveryConstraints</code> -</ul> - -{@link net.jini.discovery.LookupLocatorDiscovery} : - -<ul> -<li><code>registrarPreparer</code> -</ul> - -and {@link net.jini.lookup.JoinManager} : -<ul> -<li><code>registrarPreparer</code> -<li><code>registrationPreparer</code> -<li><code>serviceLeasePreparer</code> -</ul> - - -in addition to providing appropriate security policy files, key stores, -login configuration files, etc.<p> - -The Outrigger service implementation obtains its configuration by calling -{@link net.jini.config.ConfigurationProvider#getInstance(String[], ClassLoader) -ConfigurationProvider.getInstance} with the specified -<i>configOptions</i> and the class loader for the implementation -class. <p> - -The implementation supports the following configuration entries, with -component <code>com.sun.jini.outrigger</code>: <p> - -<a name="activationIdPreparer"></a> -<table summary="Describes the activationIdPreparer configuration entry" - border="0" cellpadding="2"> - <tr valign="top"> - <th scope="col" summary="layout"> <font size="+1">•</font> - <th scope="col" align="left" colspan="2"> <font size="+1"> - <code>activationIdPreparer</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> {@link net.jini.security.ProxyPreparer} - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> An instance of - {@link net.jini.security.BasicProxyPreparer} that - does nothing - <tr valign="top"> <td>   <th scope="row" align="right"> - - Description: <td> Proxy preparer to use for the {@link - java.rmi.activation.ActivationID} passed to the activation - constructor. Only obtained if being run as an activatable - service. The preparer should expect Outrigger to call the {@link - java.rmi.activation.ActivationID#activate activate } method of the - proxy being prepared. Obtained at activatable service start and - restart. - </table> - -<a name="activationSystemPreparer"></a> -<table summary="Describes the activationSystemPreparer configuration entry" - border="0" cellpadding="2"> - <tr valign="top"> - <th scope="col" summary="layout"> <font size="+1">•</font> - <th scope="col" align="left" colspan="2"> <font size="+1"> - <code>activationSystemPreparer</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> {@link net.jini.security.ProxyPreparer} - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> An instance of - {@link net.jini.security.BasicProxyPreparer} that - does nothing - <tr valign="top"> <td>   <th scope="row" align="right"> - - Description: <td> Proxy preparer to use for the {@link - java.rmi.activation.ActivationSystem} proxy. Only obtained if being - run as an activatable service. The preparer should expect Outrigger - to call the {@link - java.rmi.activation.ActivationSystem#unregisterGroup unregisterGroup} - method of the proxy being prepared. Obtained at activatable - service start and restart. - - </table> - -<a name="contentsLeasePeriodPolicy"></a> -<table summary="Describes the contentsLeasePeriodPolicy configuration entry" - border="0" cellpadding="2"> - <tr valign="top"> - <th scope="col" summary="layout"> <font size="+1">•</font> - <th scope="col" align="left" colspan="2"> <font size="+1"> - <code>contentsLeasePeriodPolicy</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> {@link com.sun.jini.landlord.LeasePeriodPolicy} - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> A <code>new </code>{@link - com.sun.jini.landlord.FixedLeasePeriodPolicy} that allows leases up - to one hour, and grants one hour leases for duration requests of - {@link net.jini.core.lease.Lease#ANY Lease.ANY} - - <tr valign="top"> <td>   <th scope="row" align="right"> - - Description: <td> Policy used to determine the length of initial - grants and renewals of the leases on {@link net.jini.space.MatchSet} - instances. Obtained at service start and restart. - </table> - -<a name="discoveryManager"></a> -<table summary="Describes the discoveryManager configuration entry" - border="0" cellpadding="2"> - <tr valign="top"> - <th scope="col" summary="layout"> <font size="+1">•</font> - <th scope="col" align="left" colspan="2"> <font size="+1"> - <code>discoveryManager</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> {@link net.jini.discovery.DiscoveryManagement} - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> -<pre> -new {@link net.jini.discovery.LookupDiscoveryManager}( - {@link net.jini.discovery.DiscoveryGroupManagement#NO_GROUPS}, - null, // locators - null, // listener - this) // config -</pre> - <tr valign="top"> <td>   <th scope="row" align="right"> - - Description: <td> The object Outrigger should use to find lookups to - register with. In addition to <code>DiscoveryManagement</code> it - must also implement {@link - net.jini.discovery.DiscoveryGroupManagement} and {@link - net.jini.discovery.DiscoveryLocatorManagement}. The {@link - net.jini.discovery.DiscoveryManagement#terminate terminate} method of - this object will be called when the service is destroyed. This - object must be configured with an empty set of multicast groups and - locators (Outrigger will set the groups and locators based on the - values of the <a - href="#initialLookupGroups"><code>initialLookupGroups</code></a> and - <a - href="#initialLookupLocators"><code>initialLookupLocators</code></a> - configurations entries, or based on persisted state set via its - implementation of the {@link net.jini.admin.JoinAdmin} - interface). Note, if you use the default you should also consult the - {@linkplain net.jini.discovery.LookupDiscoveryManager - <code>LookupDiscoveryManager</code> documentation} to see what - configuration entries it reads. Obtained at service start and - restart. - </table> - -<a name="entryLeasePeriodPolicy"></a> -<table summary="Describes the entryLeasePeriodPolicy configuration entry" - border="0" cellpadding="2"> - <tr valign="top"> - <th scope="col" summary="layout"> <font size="+1">•</font> - <th scope="col" align="left" colspan="2"> <font size="+1"> - <code>entryLeasePeriodPolicy</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> {@link com.sun.jini.landlord.LeasePeriodPolicy} - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> A <code>new </code>{@link - com.sun.jini.landlord.FixedLeasePeriodPolicy} that allows - leases up to {@link java.lang.Long#MAX_VALUE Long.MAX_VALUE}, and - grants one day leases for duration requests of {@link - net.jini.core.lease.Lease#ANY Lease.ANY} - <tr valign="top"> <td>   <th scope="row" align="right"> - - Description: <td> Policy used to determine the length of initial - grants and renewals of the leases on entries. Obtained at service - start and restart. - </table> - -<a name="eventLeasePolicy"></a> -<table summary="Describes the eventLeasePolicy configuration entry" - border="0" cellpadding="2"> - <tr valign="top"> - <th scope="col" summary="layout"> <font size="+1">•</font> - <th scope="col" align="left" colspan="2"> <font size="+1"> - <code>eventLeasePolicy</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> {@link com.sun.jini.landlord.LeasePeriodPolicy} - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> A <code>new </code> - {@link com.sun.jini.landlord.FixedLeasePeriodPolicy} that - allows leases up to one hour, and grants one hour leases - for duration requests of {@link net.jini.core.lease.Lease#ANY Lease.ANY} - <tr valign="top"> <td>   <th scope="row" align="right"> - - Description: <td> Policy used to determine the length of initial - grants and renewals of the leases on event registrations. Obtained at - service start and restart. - </table> - -<a name="initialLookupAttributes"></a> -<table summary="Describes the initialLookupAttributes configuration entry" - border="0" cellpadding="2"> - <tr valign="top"> - <th scope="col" summary="layout"> <font size="+1">•</font> - <th scope="col" align="left" colspan="2"> <font size="+1"> - <code>initialLookupAttributes</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> {@link net.jini.core.entry.Entry Entry[]} - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> <code>new Entry[0]</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - - Description: <td> This configuration entry will be read the <em>first - time</em> a given Outrigger instance is started and combined with a - default set of attributes. The combined set will be used as the - initial set of attributes that Outrigger will use to register with - lookup services. Any changes to the set of attributes should be done - via Outrigger's admin proxy using the {@link - net.jini.admin.JoinAdmin} interface. - </table> - -<a name="initialLookupGroups"></a> -<table summary="Describes the initialLookupGroups configuration entry" - border="0" cellpadding="2"> - <tr valign="top"> - <th scope="col" summary="layout"> <font size="+1">•</font> - <th scope="col" align="left" colspan="2"> <font size="+1"> - <code>initialLookupGroups</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> {@link java.lang.String String[]} - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> <code>new String[]{""}</code> (aka the "public" group) - <tr valign="top"> <td>   <th scope="row" align="right"> - - Description: <td> This entry will be read the <em>first time</em> a - given Outrigger instance is started to determine the initial set of - multicast discovery groups Outrigger should participate in. Any - future changes to the set of discovery groups should be made via - Outrigger's admin proxy using the {@link net.jini.admin.JoinAdmin} - interface. - </table> - -<a name="initialLookupLocators"></a> -<table summary="Describes the initialLookupLocators configuration entry" - border="0" cellpadding="2"> - <tr valign="top"> - <th scope="col" summary="layout"> <font size="+1">•</font> - <th scope="col" align="left" colspan="2"> <font size="+1"> - <code>initialLookupLocators</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> {@link net.jini.core.discovery.LookupLocator - LookupLocator[]} - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> <code>new LookupLocator[0]</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - - Description: <td> This entry will be read the <em>first time</em> a - given Outrigger instance is started to determine the inital set of - specific lookup services Outrigger should register with. Any future - changes to this set should be made via Outrigger's admin proxy using - the {@link net.jini.admin.JoinAdmin} interface. - </table> - -<a name="iteratorBatchSize"></a> -<table summary="Describes the iteratorBatchSize configuration entry" - border="0" cellpadding="2"> - <tr valign="top"> - <th scope="col" summary="layout"> <font size="+1">•</font> - <th scope="col" align="left" colspan="2"> <font size="+1"> - <code>iteratorBatchSize</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> <code>int</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> <code>100</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - - Description: <td> Fetch ahead limit for {@link - net.jini.space.JavaSpace05#contents JavaSpace05.contents} and {@link - net.jini.space.MatchSet#next MatchSet.next} calls. A given - <code>contents</code> or <code>next</code> invocation will never - fetch more than this many entries. Must be a positive - <code>int</code> value. Obtained at service start and restart. - </table> - -<a name="listenerPreparer"></a> -<table summary="Describes the listenerPreparer configuration entry" - border="0" cellpadding="2"> - <tr valign="top"> - <th scope="col" summary="layout"> <font size="+1">•</font> - <th scope="col" align="left" colspan="2"> <font size="+1"> - <code>listenerPreparer</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> {@link net.jini.security.ProxyPreparer} - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> An instance of - {@link net.jini.security.BasicProxyPreparer} that - does nothing - <tr valign="top"> <td>   <th scope="row" align="right"> - - Description: <td> Proxy preparer for {@link - net.jini.core.event.RemoteEventListener} proxies passed to {@link - net.jini.space.JavaSpace#notify JavaSpace.notify}. The preparer - should expect Outrigger to call the {@link - net.jini.core.event.RemoteEventListener#notify notify} method on the - returned proxy. The preparer may be asked to prepare proxies for the - same remote listener multiple times, though at most once per - registration the listener is associated with. <p> - - Only listener proxies that have been returned by this preparer will - be persisted. If a listener proxy is recovered it will be re-prepared - by the <a href="#recoveredListenerPreparer"><code> - recoveredListenerPreparer</code></a>. <p> - - Obtained at service start and restart. - - </table> - -<a name="loginContext"></a> -<table summary="Describes the loginContext configuration entry" - border="0" cellpadding="2"> - <tr valign="top"> - <th scope="col" summary="layout"> <font size="+1">•</font> - <th scope="col" align="left" colspan="2"> <font size="+1"> - <code>loginContext</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> {@link javax.security.auth.login.LoginContext} - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> <code>null</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - - Description: <td> If non-<code>null</code>, JAAS login context for - performing a JAAS login, after which the service is run as the - resulting subject. If <code>null</code>, no JAAS login is - performed. Obtained at service start and restart. - - </table> - -<a name="lookupLocatorPreparer"></a> -<table summary="Describes the lookupLocatorPreparer configuration entry" - border="0" cellpadding="2"> - <tr valign="top"> - <th scope="col" summary="layout"> <font size="+1">•</font> - <th scope="col" align="left" colspan="2"> <font size="+1"> - <code>lookupLocatorPreparer</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> {@link net.jini.security.ProxyPreparer} - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> An instance of - {@link net.jini.security.BasicProxyPreparer} that - does nothing - <tr valign="top"> <td>   <th scope="row" align="right"> - - Description: <td> Proxy preparer to use for instances of {@link - net.jini.core.discovery.LookupLocator} that are passed to various - {@link net.jini.admin.JoinAdmin} methods. The preparer should expect - Outrigger to call the {@link - net.jini.core.discovery.LookupLocator#getRegistrar}, - <code>equals</code>, and <code>hashCode</code> methods of the proxy - being prepared. The object returned by this preparer must be equal - (in the sense of the <code>equals</code> method) to the object passed - in. If a <code>LookupLocator</code> instance passed in via the - methods of <code>JoinAdmin</code> is persisted, the version returned - by this preparer will be the one that is persisted.<p> - - The <code>LookupLocator</code> instances obtained from - <a href="#initialLookupLocators"><code>initialLookupLocators</code> - </a> will not be prepared by this preparer.<p> - - Obtained at service start and restart. - </table> - -<a name="maxOps"></a> -<table summary="Describes the maxOps configuration entry" - border="0" cellpadding="2"> - <tr valign="top"> - <th scope="col" summary="layout"> <font size="+1">•</font> - <th scope="col" align="left" colspan="2"> <font size="+1"> - <code>maxOps</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> <code>int</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> <code>1000</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - - Description: <td> Maximum number of persistent store directives that - can be written to a log. Only consulted if {@link - com.sun.jini.outrigger.snaplogstore.LogStore - com.sun.jini.outrigger.snaplogstore.LogStore} is being used for the <a - href="#store">store</a> configuration entry. Outrigger writes - directives for the persistent store into logs that are consumed by a - consumer thread. This configuration entry represents the maximum - number of directives that can be written before a new log is - created. Must be a positive <code>int</code> value. - Obtained at service start and restart. - </table> - -<a name="maxServerQueryTimeout"></a> -<table summary="Describes the maxServerQueryTimeout configuration entry" - border="0" cellpadding="2"> - <tr valign="top"> - <th scope="col" summary="layout"> <font size="+1">•</font> - <th scope="col" align="left" colspan="2"> <font size="+1"> - <code>maxServerQueryTimeout</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> <code>long</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> {@link java.lang.Long#MAX_VALUE Long.MAX_VALUE} - <tr valign="top"> <td>   <th scope="row" align="right"> - - Description: <td> Controls the default value of the <em>maximum - server query timeout</em> for proxies created by this server. Must be - a positive long value. See <a href="#Blocking Queries"><i>Blocking - Queries</i></a> for details on the maximum server query - timeout. Note, proxies created by previous incarnations of this - server are unaffected by this entry. Obtained at service start and - restart. - </table> - -<a name="maxUnexportDelay"></a> -<table summary="Describes the maxUnexportDelay configuration entry" - border="0" cellpadding="2"> - <tr valign="top"> - <th scope="col" summary="layout"> <font size="+1">•</font> - <th scope="col" align="left" colspan="2"> <font size="+1"> - <code>maxUnexportDelay</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> <code>long</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> <code>120000</code> (2 minutes) - <tr valign="top"> <td>   <th scope="row" align="right"> - - Description: <td> How long to retry “nice” unexport attempts before - forcing the unexport. Part of destroying an Outrigger server includes - calling {@link net.jini.export.Exporter#unexport - Exporter.unexport(boolean force)} on the <code>Exporter</code> used - to export the server (see - <a href="#serverExporter"><code>serverExporter</code></a>). The initial - <code>unexport</code> call passes <code>false</code> for the value of - the <code>force</code> parameter. This is done in order to allow the - destroy call to return cleanly to the client. If the initial - <code>unexport</code> call fails, Outrigger will retry calling - <code>unexport(false)</code> for up to <code>maxUnexportDelay</code> - milliseconds before giving up and calling - <code>unexport(true)</code>. <code>maxUnexportDelay</code> must be a - non-negative long value. If <code>maxUnexportDelay</code> is zero - then the very first call to <code>unexport</code> passes - <code>true</code> for the value of the <code>force</code> parameter, - no nice unexport attempt is made. Obtained at service start and - restart. Note, the delay between attempted <code>unexport</code> - calls is controlled by the <a - href="#unexportRetryDelay"><code>unexportRetryDelay</code></a> - configuration entry. - - </table> - - -<a name="notificationsTaskManager"></a> -<table summary="Describes the notificationsTaskManager configuration entry" - border="0" cellpadding="2"> - <tr valign="top"> - <th scope="col" summary="layout"> <font size="+1">•</font> - <th scope="col" align="left" colspan="2"> <font size="+1"> - <code>notificationsTaskManager</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> {@link com.sun.jini.thread.TaskManager} - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> <code>new </code>{@link - com.sun.jini.thread.TaskManager#TaskManager() TaskManager()} - <tr valign="top"> <td>   <th scope="row" align="right"> - - Description: <td> The pool of threads used to make event delivery - attempts. - The {@link com.sun.jini.thread.TaskManager#terminate terminate} - method of this object will be called when the service is - destroyed. Obtained at service start and restart. - </table> - - -<a name="persistenceDirectory"></a> -<table summary="Describes the persistenceDirectory configuration entry" - border="0" cellpadding="2"> - <tr valign="top"> - <th scope="col" summary="layout"> <font size="+1">•</font> - <th scope="col" align="left" colspan="2"> <font size="+1"> - <code>persistenceDirectory</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> {@link java.lang.String} - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> none - <tr valign="top"> <td>   <th scope="row" align="right"> - - Description: <td> If the {@link - com.sun.jini.outrigger.snaplogstore.LogStore - com.sun.jini.outrigger.snaplogstore.LogStore} implementations of {@link - com.sun.jini.outrigger.Store} is being used, the value of this entry - is the name of the directory that should be used to persist - Outrigger's state. Obtained at persistent service start and restart. - </table> - -<a name="reapingInterval"></a> -<table summary="Describes the reapingInterval configuration entry" - border="0" cellpadding="2"> - <tr valign="top"> - <th scope="col" summary="layout"> <font size="+1">•</font> - <th scope="col" align="left" colspan="2"> <font size="+1"> - <code>reapingInterval</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> <code>long</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> <code>60000</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - - Description: <td> How often, in milliseconds, should Outrigger go - through its internal tables and remove unused entries, templates, - contents queries, etc. Must be a positive <code>long</code> - value. See also the <a - href="#reapingPriority"><code>reapingPriority</code></a> - configuration entry. Obtained at service start and restart. - </table> - - -<a name="reapingPriority"></a> -<table summary="Describes the reapingPriority configuration entry" - border="0" cellpadding="2"> - <tr valign="top"> - <th scope="col" summary="layout"> <font size="+1">•</font> - <th scope="col" align="left" colspan="2"> <font size="+1"> - <code>reapingPriority</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> <code>int</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> {@link java.lang.Thread#NORM_PRIORITY Thread.NORM_PRIORITY} - <tr valign="top"> <td>   <th scope="row" align="right"> - - Description: <td> The priority of the threads that periodically wake - up and remove entries, templates, contents queries, etc. from - Outrigger's internal tables. Must be a value between {@link - java.lang.Thread#MIN_PRIORITY Thread.MIN_PRIORITY} and {@link - java.lang.Thread#MAX_PRIORITY Thread.MAX_PRIORITY} inclusive. See - also the <a href="#reapingInterval"><code>reapingInterval</code></a> - configuration entry. Obtained at service start and restart. - </table> - -<a name="recoveredListenerPreparer"></a> -<table summary="Describes the recoveredListenerPreparer configuration entry" - border="0" cellpadding="2"> - <tr valign="top"> - <th scope="col" summary="layout"> <font size="+1">•</font> - <th scope="col" align="left" colspan="2"> <font size="+1"> - <code>recoveredListenerPreparer</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> {@link net.jini.security.ProxyPreparer} - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> An instance of - {@link net.jini.security.BasicProxyPreparer} that - does nothing - <tr valign="top"> <td>   <th scope="row" align="right"> - - Description: <td> Proxy preparer for {@link - net.jini.core.event.RemoteEventListener} proxies that have been - persisted and recovered. The preparer should expect Outrigger to call - the {@link net.jini.core.event.RemoteEventListener#notify notify} - method on the returned proxy. In a given virtual - machine for the Java platform (VM) the preparer may be asked - to prepare proxies for the same listener multiple times, though at - most one successful prepare call will be made per registration the - listener is associated with. Only read if Outrigger is being run as a - persistent service. See also the <a - href="#listenerPreparer"><code>listenerPreparer</code></a> - configuration entry. Obtained at persistent service start and - restart.<p> - - This preparer needs to perform only those operations whose results - are not retained in the serializable state of the listener proxy - itself, but need to be performed in the environment in which the - proxy is unmarshalled, typically just granting permissions. <p> - </table> - -<a name="recoveredLookupLocatorPreparer"></a> -<table summary="Describes the recoveredLookupLocatorPreparer configuration entry" - border="0" cellpadding="2"> - <tr valign="top"> - <th scope="col" summary="layout"> <font size="+1">•</font> - <th scope="col" align="left" colspan="2"> <font size="+1"> - <code>recoveredLookupLocatorPreparer</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> {@link net.jini.security.ProxyPreparer} - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> An instance of - {@link net.jini.security.BasicProxyPreparer} that - does nothing - <tr valign="top"> <td>   <th scope="row" align="right"> - - Description: <td> Proxy preparer to use for instances of {@link - net.jini.core.discovery.LookupLocator} that have been persisted and - recovered. This will include <code>LookupLocator</code>s passed into - various {@link net.jini.admin.JoinAdmin} methods as well as the - initial set of locators obtained from the <a - href="#initialLookupLocators"> <code>initialLookupLocators</code></a> - configuration entry. The preparer should expect Outrigger to call the - {@link net.jini.core.discovery.LookupLocator#getRegistrar - LookupLocator.getRegistrar}, <code>equals</code>, and - <code>hashCode</code> methods of the proxy being prepared, and that - the returned proxy will be persisted. The object returned by this - preparer must be equal (in the sense of the <code>equals</code> - method) to the object passed in. Only read if Outrigger is being run - as a persistent service. See also the <a - href="#lookupLocatorPreparer"><code>lookupLocatorPreparer</code></a> - configuration entry. Obtained at persistent service start and - restart. - <p> - This preparer needs to perform only those operations whose results - are not retained in the serializable state of the lookup locator - itself, but need to be performed in the environment in which the - lookup locator is unmarshalled. Typically no operations are - needed. <p> - - </table> - -<a name="recoveredTransactionManagerPreparer"></a> -<table summary="Describes the recoveredTransactionManagerPreparer - configuration entry" - border="0" cellpadding="2"> - <tr valign="top"> - <th scope="col" summary="layout"> <font size="+1">•</font> - <th scope="col" align="left" colspan="2"> <font size="+1"> - <code>recoveredTransactionManagerPreparer</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> {@link net.jini.security.ProxyPreparer} - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> An instance of - {@link net.jini.security.BasicProxyPreparer} that - does nothing - <tr valign="top"> <td>   <th scope="row" align="right"> - - Description: <td> Proxy preparer for {@link - net.jini.core.transaction.server.TransactionManager} proxies that - have been persisted and recovered. The preparer should expect - Outrigger to call the {@link - net.jini.core.transaction.server.TransactionManager#getState - getState}, <code>equals</code>, and <code>hashCode</code> methods on the - returned proxy. In a given VM, the preparer may be asked to prepare - proxies for the same <code>TransactionManager</code> multiple times, - though at most one successful prepare call will be made per given - transaction the manager is involved in. Only read if Outrigger is - being run as a persistent service. The object returned by this - preparer must be equal (in the sense of the <code>equals</code> - method) to the object passed in. See also the <a - href="#transactionManagerPreparer"> - <code>transactionManagerPreparer</code></a> configuration - entry. Obtained at persistent service start and restart. - <p> - - This preparer needs to perform only those operations whose results - are not retained in the serializable state of the transaction manager - proxy itself, but need to be performed in the environment in which - the proxy is unmarshalled, typically just granting permissions. <p> - </table> - - -<a name="serverExporter"></a> -<table summary="Describes the serverExporter configuration entry" - border="0" cellpadding="2"> - <tr valign="top"> - <th scope="col" summary="layout"> <font size="+1">•</font> - <th scope="col" align="left" colspan="2"> <font size="+1"> - <code>serverExporter</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> {@link net.jini.export.Exporter} - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> A new - {@link net.jini.jeri.BasicJeriExporter} - with <ul> - <li> a {@link - net.jini.jeri.tcp.TcpServerEndpoint} - created on a random port, - <li> a {@link net.jini.jeri.BasicILFactory}, - <li> distributed garbage collection turned off, - <li> keep alive on. - </ul> - If activatable, the same default will be used - but wrapped in an - {@link net.jini.activation.ActivationExporter} - and created with the service's {@link - java.rmi.activation.ActivationID} - <tr valign="top"> <td>   <th scope="row" align="right"> - - Description: <td> The exporter used to export the server. The - resulting proxy is used as the <em>inner proxy</em> for all of - Outrigger's proxies. If the server is activatable, the service's - <code>ActivationID</code> will be passed as the <code>data</code> - argument, otherwise the <code>data</code> argument will be - <code>null</code>. A new exporter is obtained every time Outrigger - needs to export itself, currently at service start and restart. - - </table> - -<a name="store"></a> -<table summary="Describes the store configuration entry" - border="0" cellpadding="2"> - <tr valign="top"> - <th scope="col" summary="layout"> <font size="+1">•</font> - <th scope="col" align="left" colspan="2"> <font size="+1"> - <code>store</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> {@link com.sun.jini.outrigger.Store} - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> none - <tr valign="top"> <td>   <th scope="row" align="right"> - - Description: <td> The object used to implement Outrigger's persistent - store. Only consulted if a persistent version of Outrigger is being - started. Obtained at persistent service start and restart.<p> - - A {@link com.sun.jini.outrigger.snaplogstore.LogStore - com.sun.jini.outrigger.snaplogstore.LogStore} instance can - be created like this: - <p> - - <code>new </code>{@link - com.sun.jini.outrigger.snaplogstore.LogStore#LogStore - com.sun.jini.outrigger.snaplogstore.LogStore(this)} - <code> // `this' == the configuration object</code> - <p> - </table> - -<a name="takeMultipleLimit"></a> -<table summary="Describes the takeMultipleLimit configuration entry" - border="0" cellpadding="2"> - <tr valign="top"> - <th scope="col" summary="layout"> <font size="+1">•</font> - <th scope="col" align="left" colspan="2"> <font size="+1"> - <code>takeMultipleLimit</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> <code>int</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> <code>100</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - - Description: <td> Maximum number of entries a {@link - net.jini.space.JavaSpace05#take JavaSpace05.take} call may - return. Must be a positive <code>int</code> value. Obtained at - service start and restart. - </table> - - -<a name="transactionManagerPreparer"></a> -<table summary="Describes the transactionManagerPreparer configuration entry" - border="0" cellpadding="2"> - <tr valign="top"> - <th scope="col" summary="layout"> <font size="+1">•</font> - <th scope="col" align="left" colspan="2"> <font size="+1"> - <code>transactionManagerPreparer</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> {@link net.jini.security.ProxyPreparer} - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> An instance of - {@link net.jini.security.BasicProxyPreparer} that - does nothing - <tr valign="top"> <td>   <th scope="row" align="right"> - - Description: <td> Proxy preparer for {@link - net.jini.core.transaction.server.TransactionManager} proxies - managing transactions Outrigger is participating in. The preparer - should expect Outrigger to call the {@link - net.jini.core.transaction.server.TransactionManager#join join}, - {@link net.jini.core.transaction.server.TransactionManager#getState - getState}, <code>equals</code>, and <code>hashCode</code> methods on the - returned proxy. The preparer may be asked to prepare proxies for the - same <code>TransactionManager</code> multiple times. Outrigger - attempts to minimize the number of times the - <code>TransactionManager</code> associated with a given transaction - is prepared; that is, if a given transaction is passed to multiple - operations on the space, in most cases the proxy for the associated - <code>TransactionManager</code> will only be prepared once. However, - it will be prepared again if it is used in a different - transaction. The object returned by this preparer must be equal (in - the sense of the <code>equals</code> method) to the object passed - in.<p> - - Only <code>TransactionManager</code> proxies that have been returned - by this preparer will be persisted. If a - <code>TransactionManager</code> proxy is recovered it will be - re-prepared by the <a - href="#recoveredTransactionManagerPreparer"><code> - recoveredTransactionManagerPreparer</code></a>.<p> - - Obtained at service start and restart. - </table> - -<a name="txnMonitorTaskManager"></a> -<table summary="Describes the txnMonitorTaskManager configuration entry" - border="0" cellpadding="2"> - <tr valign="top"> - <th scope="col" summary="layout"> <font size="+1">•</font> - <th scope="col" align="left" colspan="2"> <font size="+1"> - <code>txnMonitorTaskManager</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> {@link com.sun.jini.thread.TaskManager} - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> <code>new </code>{@link - com.sun.jini.thread.TaskManager#TaskManager() TaskManager()} - <tr valign="top"> <td>   <th scope="row" align="right"> - - Description: <td> The pool of threads used to check the status - of transactions that have been prepared or have locked contended - resources. - The {@link com.sun.jini.thread.TaskManager#terminate terminate} - method of this object will be called when the service is - destroyed. Obtained at service start and restart. - </table> - -<a name="unexportRetryDelay"></a> -<table summary="Describes the unexportRetryDelay configuration entry" - border="0" cellpadding="2"> - <tr valign="top"> - <th scope="col" summary="layout"> <font size="+1">•</font> - <th scope="col" align="left" colspan="2"> <font size="+1"> - <code>unexportRetryDelay</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> <code>long</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> <code>1000</code> (1 second) - <tr valign="top"> <td>   <th scope="row" align="right"> - - Description: <td> When destroying an Outrigger server how long to - wait between unexport attempts. <code>unexportRetryDelay</code> must - be a positive long value. When destroying itself Outrigger will sleep - for <code>unexportRetryDelay</code> milliseconds between {@link - net.jini.export.Exporter#unexport Exporter.unexport} calls. Obtained - at service start and restart. See <a - href="#maxUnexportDelay"><code>maxUnexportDelay</code></a> for - additional details. - </table> - -<!-- -<a name=""></a> -<table summary="Describes the firstEntryName configuration entry" - border="0" cellpadding="2"> - <tr valign="top"> - <th scope="col" summary="layout"> <font size="+1">•</font> - <th scope="col" align="left" colspan="2"> <font size="+1"> - <code>firstEntryName</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> <code><i>firstTypeName</i></code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> <code><i>firstDefaultValue</i></code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Description: <td> <i>This is the first description.</i> - </table> ---> - -<H3>Other Configuration Entries</H3> - -Outrigger uses {@link net.jini.lookup.JoinManager} to manage its lookup -service registrations, passing in the configuration, the {@link -net.jini.discovery.DiscoveryManagement} object obtained from the <a -href="#discoveryManager"><code>discoveryManager</code></a> configuration -entry, and <code>null</code> for the {@link -net.jini.lease.LeaseRenewalManager}. The {@linkplain net.jini.lookup.JoinManager -<code>JoinManager</code> documentation} should be consulted to see what -configuration entries <code>JoinManager</code> reads. - -<a name="Blocking Queries"> -<H2>Blocking Queries</H2> -</a> - -Outrigger implements blocking queries ({@link net.jini.space.JavaSpace#read -read}, {@link net.jini.space.JavaSpace#take take}, {@link -net.jini.space.JavaSpace05#take take}, {@link -net.jini.space.JavaSpace#readIfExists readIfExists}, and {@link -net.jini.space.JavaSpace#takeIfExists takeIfExists} calls with non-zero -timeouts that cannot be immediately resolved) by having the remote call -block in the server until the query can be resolved or the timeout -expires. This means the remote call could run up to the timeout provided by -the client. While this works well in many cases, some transports only -support relatively short remote call durations. In such cases, calls that -block in the server for a long time may fail with a remote exception. -Outrigger's <em>maximum server query timeout</em> facility can be used to -limit the duration of any one remote call while still allowing for the -client to submit blocking queries with very long timeouts. This allows an -Outrigger deployment to accommodate clients that want to use long timeouts -with blocking queries while using transports that cannot support remote -calls that block for an unbounded period of time.<p> - -When Outrigger's proxy handles a query with a non-zero <em>client -timeout</em>, it passes a non-zero <em>server timeout</em> to the -server. If the server timeout elapses, the server returns even if the query -has not been resolved. Normally the proxy just passes the client timeout as -the server timeout. However, each proxy has a <em>maximum server query -timeout</em> value that is used to bound the server timeout. If the maximum -server query timeout is less than the client timeout, the maximum server -query timeout will be passed for the server timeout. If a call to the -server returns without resolving the query, the proxy will re-submit the -query using the smaller of the maximum server query timeout and the -remainder of the client timeout as the server timeout. By setting the -maximum server query timeout to be shorter than the longest remote call the -transport will support, the client can use very long client -timeouts while avoiding remote exceptions that result from the transport's -inability to support long remote calls.<p> - -When Outrigger creates a proxy it provides a default value for the maximum -server query timeout. This default is controlled by the <a -href="#maxServerQueryTimeout"><code>maxServerQueryTimeout</code></a> -configuration entry. This value can be overridden in the client by setting -the <code>com.sun.jini.outrigger.maxServerQueryTimeout</code> property to a -positive <code>long</code> value.<p> - -Note, the maximum server query timeout only controls how long the server -will wait for resolution of a blocking query before returning to the proxy, -it does not affect how long the proxy will wait if there is a problem with -the network. If the Java RMI implementation being used allows one to limit -the total time a remote call is allowed to block, the maximum server -query timeout provides a way to make sure that the proxy will avoid making -calls that will last longer than that limit.<p> - -<a name="access_control"> -<H2>Access Control Permission Targets</H2> -</a> - -The following table lists the remote methods on Outrigger's proxy objects and -the associated target names for enforcing access control using {@link -com.sun.jini.outrigger.OutriggerPermission}: <p> - -<table border="1" cellpadding="5" - summary="The proxy methods and associated target names for - OutriggerPermission."> - -<tr> <th> Proxy Method <th> Target Name - -<!-- JavaSpace --> - -<tr> <td> {@link net.jini.space.JavaSpace#write JavaSpace.write} - <td> <code>write</code> - -<tr> <td> {@link net.jini.space.JavaSpace#take JavaSpace.take} - <td> <code>take</code> - -<tr> <td> {@link net.jini.space.JavaSpace#read JavaSpace.read} - <td> <code>read</code> - -<tr> <td> {@link net.jini.space.JavaSpace#takeIfExists JavaSpace.takeIfExists} - <td> <code>takeIfExists</code> - -<tr> <td> {@link net.jini.space.JavaSpace#readIfExists JavaSpace.readIfExists} - <td> <code>readIfExists</code> - -<tr> <td> {@link net.jini.space.JavaSpace#notify JavaSpace.notify} - <td> <code>notify</code> - -<!-- JavaSpace05 --> - -<tr> <td> {@link net.jini.space.JavaSpace05#write JavaSpace05.write} - <td> <code>write</code> - -<tr> <td> {@link net.jini.space.JavaSpace05#take JavaSpace05.take} - <td> <code>take</code> - -<tr> <td> {@link net.jini.space.JavaSpace05#contents JavaSpace05.contents} - <td> <code>contents</code> - -<tr> <td> {@link net.jini.space.JavaSpace05#registerForAvailabilityEvent - JavaSpace05.registerForAvailabilityEvent} - <td> <code>registerForAvailabilityEvent</code> - -<!-- MatchSet --> - -<tr> <td> {@link net.jini.space.MatchSet#next MatchSet.next} - <td> <code>nextBatch</code> - - -<!-- TransactionParticipant --> - -<tr> <td> {@link net.jini.core.transaction.server.TransactionParticipant#prepare - TransactionParticipant.prepare} - <td> <code>prepare</code> - -<tr> <td> {@link net.jini.core.transaction.server.TransactionParticipant#commit - TransactionParticipant.commit} - <td> <code>commit</code> - -<tr> <td> {@link net.jini.core.transaction.server.TransactionParticipant#abort - TransactionParticipant.abort} - <td> <code>abort</code> - -<tr> <td> {@link net.jini.core.transaction.server.TransactionParticipant#prepareAndCommit - TransactionParticipant.prepareAndCommit} - <td> <code>prepareAndCommit</code> - -<!-- Lease and LeaseMap --> - -<tr> <td> {@link net.jini.core.lease.Lease#renew Lease.renew} - <td> <code>renew</code> - -<tr> <td> {@link net.jini.core.lease.Lease#cancel Lease.cancel} - <td> <code>cancel</code> - -<tr> <td> {@link net.jini.core.lease.LeaseMap#renewAll LeaseMap.renewAll} - <td> <code>renewAll</code> - -<tr> <td> {@link net.jini.core.lease.LeaseMap#cancelAll LeaseMap.cancelAll} - <td> <code>cancelAll</code> - -<!-- Administrable --> - -<tr> <td> {@link net.jini.admin.Administrable#getAdmin Administrable.getAdmin} - <td> <code>getAdmin</code> - -<!-- JoinAdmin --> - -<tr> <td> {@link net.jini.admin.JoinAdmin#getLookupAttributes - JoinAdmin.getLookupAttributes} - <td> <code>getLookupAttributes</code> - -<tr> <td> {@link net.jini.admin.JoinAdmin#addLookupAttributes - JoinAdmin.addLookupAttributes} - <td> <code>addLookupAttributes</code> - -<tr> <td> {@link net.jini.admin.JoinAdmin#modifyLookupAttributes - JoinAdmin.modifyLookupAttributes} - <td> <code>modifyLookupAttributes</code> - -<tr> <td> {@link net.jini.admin.JoinAdmin#getLookupGroups - JoinAdmin.getLookupGroups} - <td> <code>getLookupGroups</code> - -<tr> <td> {@link net.jini.admin.JoinAdmin#addLookupGroups - JoinAdmin.addLookupGroups} - <td> <code>addLookupGroups</code> - -<tr> <td> {@link net.jini.admin.JoinAdmin#removeLookupGroups - JoinAdmin.removeLookupGroups} - <td> <code>removeLookupGroups</code> - -<tr> <td> {@link net.jini.admin.JoinAdmin#setLookupGroups - JoinAdmin.setLookupGroups} - <td> <code>setLookupGroups</code> - -<tr> <td> {@link net.jini.admin.JoinAdmin#getLookupLocators - JoinAdmin.getLookupLocators} - <td> <code>getLookupLocators</code> - -<tr> <td> {@link net.jini.admin.JoinAdmin#addLookupLocators - JoinAdmin.addLookupLocators} - <td> <code>addLookupLocators</code> - -<tr> <td> {@link net.jini.admin.JoinAdmin#removeLookupLocators - JoinAdmin.removeLookupLocators} - <td> <code>removeLookupLocators</code> - -<tr> <td> {@link net.jini.admin.JoinAdmin#setLookupLocators - JoinAdmin.setLookupLocators} - <td> <code>setLookupLocators</code> - -<!-- DestroyAdmin --> - -<tr> <td> {@link com.sun.jini.admin.DestroyAdmin#destroy DestroyAdmin.destroy} - <td> <code>destroy</code> - -<!-- ProxyTrust --> - -<tr> <td> {@link net.jini.security.proxytrust.ProxyTrust#getProxyVerifier - ProxyTrust.getProxyVerifier} - <td> <code>getProxyVerifier</code> - -<!-- ServiceProxyAccessor --> - -<tr> <td> {@link com.sun.jini.start.ServiceProxyAccessor#getServiceProxy - ServiceProxyAccessor.getServiceProxy} - <td> <code>getServiceProxy</code> - -<!-- (Constrainable)JavaSpaceAdmin --> - -<tr> <td> {@link com.sun.jini.outrigger.JavaSpaceAdmin#space - JavaSpaceAdmin.space} - <td> <code>space</code> - -<tr> <td> {@link - com.sun.jini.outrigger.JavaSpaceAdmin#contents( - net.jini.core.entry.Entry, - net.jini.core.transaction.Transaction) - JavaSpaceAdmin.contents(Entry, Transaction)},<br> - {@link com.sun.jini.outrigger.JavaSpaceAdmin#contents( - net.jini.core.entry.Entry, - net.jini.core.transaction.Transaction, - int) - JavaSpaceAdmin.contents(Entry, Transaction, int)},<br> - {@link - com.sun.jini.outrigger.ConstrainableJavaSpaceAdmin#contents( - net.jini.core.entry.Entry, - net.jini.core.transaction.Transaction, - int, - net.jini.core.constraint.MethodConstraints) - ConstrainableJavaSpaceAdmin.contents(Entry, Transaction, int, - MethodConstraints)} - - <td> <code>contents</code> - -<!-- AdminIterator --> - -<tr> <td> {@link com.sun.jini.outrigger.AdminIterator#next AdminIterator.next} - <td> <code>next</code> - -<tr> <td> {@link com.sun.jini.outrigger.AdminIterator#delete - AdminIterator.delete} - <td> <code>delete</code> - -<tr> <td> {@link com.sun.jini.outrigger.AdminIterator#close AdminIterator.close} - <td> <code>close</code> - -</table> - -<a name="logging"> -<h2>Logging</h2> -</a> - -The Outrigger service implementation uses a number of different {@link -java.util.logging.Logger} objects: <p> - - <table border="1" cellpadding="5" - summary="Describes the various logger names Outrigger uses"> - - <tr> <td> <b>Logger Name</b> <td> <b>Description</b> - - <tr> <td> <code>com.sun.jini.outrigger.lifecycle</code> - <td> Starting/restarting/destroying the service - - <tr> <td> <code>com.sun.jini.outrigger.operations</code> - <td> Top level space operations - - <tr> <td> <code>com.sun.jini.outrigger.transactions</code> - <td> Transactions - - <tr> <td> <code>com.sun.jini.outrigger.leases</code> - <td> Leases and leasing - - <tr> <td> <code>com.sun.jini.outrigger.iterator</code> - <td> Iterators - - <tr> <td> <code>com.sun.jini.outrigger.join</code> - <td> Outrigger's join state - - <tr> <td> <code>com.sun.jini.outrigger.entryMatching</code> - <td> Entry matching - - <tr> <td> <code>com.sun.jini.outrigger.event</code> - <td> Events and event delivery - - <tr> <td> <code>com.sun.jini.outrigger.store</code> - <td> Persistence - - <tr> <td> <code>com.sun.jini.outrigger.proxy</code> - <td> The operation of Outrigger's proxies - </table><p> - -Each of these loggers logs information at the following logging levels: <p> - - <table border="1" cellpadding="5" - summary="Describes logging performed by Outrigger at different - logging levels"> - - <tr> <th> Level <th> Description - - <tr> <td> SEVERE - <td> Problems which prevent startup or cause shutdown of Outrigger, - or which generally prevent Outrigger from continuing with its - processing - - <tr> <td> WARNING - <td> Problems that allow Outrigger to continue with its processing, - but in a "crippled" state that might be serious enough to affect - other operations in the system - - <tr> <td> INFO <td> - Serious, unexpected "problems" that occur during processing that the - user/deployer/administrator needs to know about, but which does not - necessarily indicate problems with other operations in the system. - Also top level life-cycle messages - - <tr> <td> CONFIG <td> - Trace information related to the configuration and administration - of Outrigger - - <tr> <td> FAILED <td> - Serious, unexpected "problems" encountered by Outrigger that - the user/deployer/administrator needs to know about, which - Outrigger propagates to its caller, and which may ultimately be - logged by some other component at a higher level (such as INFO). - Also error conditions in independent threads that are probably - transient in nature - - <tr> <td> FINE <td> - Information related to tracing Outrigger at a high level, - which might provide a logical view of the operations being - performed. - - <tr> <td> FINER <td> - Information related to tracing Outrigger at a lower level, - with more detail than that provided at the FINE level; for - example, tracing method entry and exit. - - <tr> <td> FINEST <td> - Information related to Outrigger's internal state that - might be useful in debugging or testing - </table> <p> - -<p> - -<a name="examples"> -<H2>Examples for Running Outrigger</H2> -</a> - -This section provides examples of running Outrigger in various configurations. - -<ul> -<li> <a href="#assumptions">Assumptions for running the examples</a> -<li> JRMP configurations - <ul> - <li> <a href="#transient_jrmp">Transient</a> - <li> <a href="#activatable_jrmp">Activatable</a> - </ul> -<li> Jini ERI configurations - <ul> - <li> <a href="#transient">Transient</a> - <li> <a href="#persistent">Persistent</a> - <li> <a href="#activatable">Activatable</a> - </ul> -<li> <a href="#stop_activatable">Stopping activatable configurations</a> -</ul> <p> - -No example is included for a non-activatable, persistent JRMP configuration -because this is <a href="#persistent_jrmp">unlikely to have the expected -result</a>. - -<a name="assumptions"> -<h3>Assumptions for Running the Examples</h3> -</a> - -The examples below make the following assumptions: <p> - -<ul> -<li> The Java(TM) 2 Platform, Standard Edition, (J2SE(TM)) has been - installed, and its commands are available in the current path -<li> The Apache River release has been installed in the - <var><b>install_dir</b></var> directory -<li> The example configuration and policy files described below are - available in the <var><b>config_dir</b></var> directory -<li> The local lookup group name is <var><b>your.group</b></var> -<li> The HTTP server for download JAR files is running on - the local host and is available on port - <var><b>http_port</b></var>. This HTTP server is serving files located - in the <var><b>install_dir</b></var>/lib-dl directory. You can use the - {@link com.sun.jini.tool.ClassServer} class for this purpose. -<li> The examples are being run on UNIX platforms -<li> The examples are being run on a secure network where access control - and authentication are not needed. See the <a - href="../../../../../../source/src/com/sun/jini/example/hello/index.html">hello example</a> for some - client and service configurations that enforce security. -<li> For activatable services, an activation system is running on - your machine. You can use the {@link - com.sun.jini.phoenix} implementation for this purpose. -</ul> <p> - -Throughout the examples, items in <var><b>bold</b></var> need to be -customized for your local environment. - -<a name="transient_jrmp"> -<h3>Starting Transient Outrigger using JRMP</h3> -</a> - -This configuration starts a transient Outrigger server that will use JRMP -(the basic Java RMI implementation included with the JDK) to communicate -between proxies and the server. Only a single VM will be involved (which -will be started by the command shown below). The Outrigger server will -reside in this VM. When this VM exits, the server, the space it is hosting, -and all entries in the space will be gone. This (or a similar <a -href="#transient">configuration that uses Jini ERI</a>) is a good choice when -you are just starting with spaces or when doing development since it has -low overhead, is simpler to get running, and is simpler to stop. It may or -may not be a good choice for a production deployment depending on the -application's requirements.<p> - -<blockquote> -<pre> -java -Djava.security.policy=<a href="#outrigger_all_policy"><var><b>config_dir</b></var>/outrigger-all.policy</a> \ - -jar <var><b>install_dir</b></var>/lib/start.jar \ - <a href="#start_transient_jrmp_config"><var><b>config_dir</b></var>/start-transient-jrmp-outrigger.config</a> -</pre> -</blockquote> <p> - -This configuration uses the following files. - -<a name="outrigger_all_policy"> -<h4>File <var><b>config_dir</b></var>/outrigger-all.policy</h4> -</a> - -For simplicity the examples all use this security policy file for starting -and running all Outrigger configurations. It would be possible to create -more targeted files in some cases. A policy file like this should prevent -Outrigger from being used to compromise the host it is being run on or -other hosts on the network while requiring minimal tweaking. It will not -prevent unauthorized access to the space, nor will it prevent denial of -service attacks against the space. Controlling access to the space and/or -preventing denial of service attacks will require a secure configuration. -See the <a -href="../../../../../../source/src/com/sun/jini/example/hello/index.html">hello -example</a> for some client and service configurations that enforce -security.<p> - -<blockquote> -<pre> -grant codebase "file:<var><b>install_dir</b></var>/lib/jsk-platform.jar" { - permission java.security.AllPermission; -}; - -grant codebase "file:<var><b>install_dir</b></var>/lib/jsk-lib.jar" { - permission java.security.AllPermission; -}; - -grant codebase "file:<var><b>install_dir</b></var>/lib/start.jar" { - permission java.security.AllPermission; -}; - -grant codebase "file:<var><b>install_dir</b></var>/lib/destroy.jar" { - permission java.security.AllPermission; -}; - -grant codebase "file:<var><b>install_dir</b></var>/lib/sharedvm.jar" { - permission java.security.AllPermission; -}; - -grant codebase "file:<var><b>install_dir</b></var>/lib/group.jar" { - permission java.security.AllPermission; -}; - -grant codebase "file:<var><b>install_dir</b></var>/lib/outrigger.jar" { - permission java.security.AllPermission; -}; - -grant codebase "file:<var><b>install_dir</b></var>/lib/outrigger-snaplogstore.jar" { - permission java.security.AllPermission; -}; - -grant codebase "file:<var><b>install_dir</b></var>/lib/phoenix-group.jar" { - permission java.security.AllPermission; -}; - -grant codebase "file:<var><b>install_dir</b></var>/lib/phoenix-init.jar" { - permission java.security.AllPermission; -}; -</pre> -</blockquote> - -<a name="start_transient_jrmp_config"> -<h4>File <var><b>config_dir</b></var>/start-transient-jrmp-outrigger.config</h4> -</a> - -Use this configuration source file to start transient Outrigger using -JRMP. <p> - -<blockquote> -<pre> -import com.sun.jini.start.NonActivatableServiceDescriptor; -import com.sun.jini.start.ServiceDescriptor; -import com.sun.jini.config.ConfigUtil; - -com.sun.jini.start { - private static basecodebase = "http://"; + ConfigUtil.getHostName() + - ":<var><b>http_port</b></var>/"; - private static codebase = basecodebase + "outrigger-dl.jar " + - basecodebase + "jsk-dl.jar"; - - private static policy = "<a href="#outrigger_all_policy"><var><b>config_dir</b></var>/outrigger-all.policy</a>"; - private static classpath = "<var><b>install_dir</b></var>/lib/outrigger.jar"; - private static config = "<a href="#transient_jrmp_config"><var><b>config_dir</b></var>/transient-jrmp-outrigger.config</a>"; - - static serviceDescriptors = new ServiceDescriptor[] { - new NonActivatableServiceDescriptor( - codebase, policy, classpath, - "com.sun.jini.outrigger.TransientOutriggerImpl", - new String[] { config }) - }; -} -</pre> -</blockquote> - - - -<a name="transient_jrmp_config"> -<h4>File <var><b>config_dir</b></var>/transient-jrmp-outrigger.config</h4> -</a> - -Use this configuration source file to run transient Outrigger using JRMP. <p> - -<blockquote> -<pre> -import net.jini.jrmp.JrmpExporter; - -com.sun.jini.outrigger { - initialLookupGroups = new String[] { "<var><b>your.group</b></var>" }; - serverExporter = new JrmpExporter(); -} -</pre> -</blockquote> - - - - - -<a name="activatable_jrmp"> -<h3>Starting Activatable Outrigger using JRMP</h3> -</a> - -This configuration starts an activatable (and persistent) Outrigger server -that will use JRMP to communicate between proxies and the server. In this -configuration the space is persistent and the activation system is used to -restart the server when necessary (e.g. after a crash). -<p> - -If you are not familiar with Java RMI activation you should read this <a -href="../../../../../release-notes/activation.html">note on activation</a> -first. For day to day development, or if you are just starting with Jini -technology you may be better served with either the <a -href="#transient_jrmp">transient JRMP</a> or <a href="#transient">transient -Jini ERI</a> configurations. If you require persistence you may also want to -try the <a href="#persistent">persistent Jini ERI</a> configuration. -<p> - -<blockquote> -<pre> -java -Djava.security.policy=<a href="#outrigger_all_policy"><var><b>config_dir</b></var>/outrigger-all.policy</a> \ - -jar <var><b>install_dir</b></var>/lib/start.jar \ - <a href="#start_activatable_jrmp_config"><var><b>config_dir</b></var>/start-activatable-jrmp-outrigger.config</a> -</pre> -</blockquote> <p> - - -This command will create a <em>new</em> activation group and create a -<em>new</em> Outrigger service instance that will be placed in that -group. If you execute the command twice you will end up with an error -message from the attempt to create the activation group and two Outrigger -services in the same activation group trying to share the same persistence -directory. -<p> - -If the goal of executing the command twice is to have two spaces, then -before the second invocation you should change the value of the -<code>persistenceDirectory</code> configuration entry in <code><a -href="#activatable_jrmp_config">activatable-jrmp-outrigger.config</a></code> -and either : -<ul> -<li> Change the value of the <code>groupPersistenceDirectory</code> - configuration entry in <a - href=#start_activatable_jrmp_config>start-activatable-jrmp-outrigger.config</a>, - which will give you two spaces in <em>two activation groups</em>. -<li> Remove the <code>SharedActivationGroupDescriptor</code> instance - from the <code>serviceDescriptors</code> configuration entry in - <a - href=#start_activatable_jrmp_config>start-activatable-jrmp-outrigger.config</a>, - which will give you two spaces in <em>one activation group</em>. -</ul> -<p> - -If you want to replace the first space with a new and empty space that has -a new identity, you should first destroy the original space using -Outrigger's administrable interface. You may also want to <a -href="#stop_activatable">destroy the original activation group</a>. If you -destroy the entire activation group you can skip using Outrigger's -administrable interface to destroy the Outrigger service instance, and -instead remove <var><b>config_dir</b></var>/outrigger.log after destroying -the activation group. -<p> - -This configuration uses the following additional files. - -<a name="start_activatable_jrmp_config"> -<h4>File -<var><b>config_dir</b></var>/start-activatable-jrmp-outrigger.config</h4> -</a> - -Use this configuration source file to start activatable Outrigger using -JRMP. <p> - -<blockquote> -<pre> -import com.sun.jini.start.ServiceDescriptor; -import com.sun.jini.start.SharedActivatableServiceDescriptor; -import com.sun.jini.start.SharedActivationGroupDescriptor; -import com.sun.jini.config.ConfigUtil; - -com.sun.jini.start { - private static basecodebase = "http://"; + ConfigUtil.getHostName() + - ":<var><b>http_port</b></var>/"; - private static outriggerCodebase = basecodebase + "outrigger-dl.jar " + - basecodebase + "jsk-dl.jar"; - - - private static outriggerPolicy = "<a href="#outrigger_all_policy"><var><b>config_dir</b></var>/outrigger-all.policy</a>"; - private static outriggerClasspath = "<var><b>install_dir</b></var>/lib/outrigger.jar"; - private static outriggerConfig = "<a href="#activatable_jrmp_config"><var><b>config_dir</b></var>/activatable-jrmp-outrigger.config</a>"; - - private static groupPolicy = "<a href="#outrigger_all_policy"><var><b>config_dir</b></var>/outrigger-all.policy</a>"; - private static groupClasspath = "<var><b>install_dir</b></var>/lib/sharedvm.jar"; - private static groupPersistenceDirectory = "<var><b>config_dir</b></var>/group.log"; - - static serviceDescriptors = new ServiceDescriptor[] { - new SharedActivationGroupDescriptor( - groupPolicy, groupClasspath, groupPersistenceDirectory, - null /* serverCommand */, - null /* serverOptions */, - null /* serverProperties */), - new SharedActivatableServiceDescriptor( - outriggerCodebase, outriggerPolicy, outriggerClasspath, - "com.sun.jini.outrigger.PersistentOutriggerImpl", - groupPersistenceDirectory, - new String[] { outriggerConfig }, - true /* restart */) - }; -} -</pre> -</blockquote> - -<a name="activatable_jrmp_config"> -<h4>File <var><b>config_dir</b></var>/activatable-jrmp-outrigger.config</h4> -</a> - -Use this configuration source file to run activatable Outrigger using JRMP -and the Snaplogstore implementation of <code>Store</code>. <p> - -<blockquote> -<pre> -import com.sun.jini.outrigger.snaplogstore.LogStore; -import java.rmi.activation.ActivationID; -import net.jini.jrmp.JrmpExporter; - -com.sun.jini.outrigger { - initialLookupGroups = new String[] { "<var><b>your.group</b></var>" }; - persistenceDirectory = "<var><b>config_dir</b></var>/outrigger.log"; - store = new LogStore(this); - serverExporter = new JrmpExporter((ActivationID) $data, 0); -} -</pre> -</blockquote> - - -<a name="stop_activatable"> -<h3>Stopping Activatable Outrigger</h3> -</a> - -To destroy the activation group running an activatable Outrigger, running -under either JRMP or Jini ERI, run the following command. <p> - -<blockquote> -<pre> -java -Djava.security.policy=<a href="#outrigger_all_policy"><var><b>config_dir</b></var>/outrigger-all.policy</a> \ - -jar <var><b>install_dir</b></var>/lib/destroy.jar \ - <a href="#stop_activatable_config"><var><b>config_dir</b></var>/stop-activatable-outrigger.config</a> -</pre> -</blockquote> <p> - -Running this command will remove the -<var><b>config_dir</b></var>/group.log directory. <p> - -Note that this command does not actually destroy the service itself, but -just destroys the activation group the service is running in. You may -want to first destroy the service using Outrigger's administrable interface, -or to remove the <var><b>config_dir</b></var>/outrigger.log directory after -destroying the activation group. <p> - -This command uses the following additional file. - -<a name="stop_activatable_config"> -<h4>File <var><b>config_dir</b></var>/stop-activatable-outrigger.config</h4> -</a> - -Use this configuration source file to destroy the activation group for -an activatable Outrigger. <p> - -<blockquote> -<pre> -import com.sun.jini.start.ServiceDescriptor; -import com.sun.jini.start.SharedActivatableServiceDescriptor; -import com.sun.jini.config.ConfigUtil; - -com.sun.jini.start { - private static codebase = "http://"; + ConfigUtil.getHostName() + - ":<var><b>http_port</b></var>/group-dl.jar"; - private static policy = "<a href="#outrigger_all_policy"><var><b>config_dir</b></var>/outrigger-all.policy</a>"; - private static classpath = "<var><b>install_dir</b></var>/lib/group.jar"; - private static persistenceDirectory = "<var><b>config_dir</b></var>/group.log"; - - static serviceDestructors = new ServiceDescriptor[] { - new SharedActivatableServiceDescriptor( - codebase, policy, classpath, - "com.sun.jini.start.SharedGroupImpl", - persistenceDirectory, - null /* config */, - false /* restart */) - }; -} -</pre> -</blockquote> - - -<a name="transient"> -<h3>Starting Transient Outrigger using Jini ERI</h3> -</a> - -This configuration starts a transient Outrigger server that will use Jini -ERI (the configurable Java RMI implementation included with the Apache River -release) to communicate between proxies and the server. Only a single VM will -be involved (which will be started by the command shown below). The -Outrigger server will reside in this VM. When this VM exits, the server, the -space it is hosting, and all entries in the space will be gone. This (or a -similar <a href="#transient_jrmp">configuration that uses JRMP</a>) is good -choice when you are just starting with spaces or when doing development -since it has low overhead, is simpler to get running, and is simpler to -stop. It may or may not be a good choice for a production deployment -depending on the application's requirements.<p> - -<blockquote> -<pre> -java -Djava.security.policy=<a href="#outrigger_all_policy"><var><b>config_dir</b></var>/outrigger-all.policy</a> \ - -jar <var><b>install_dir</b></var>/lib/start.jar \ - <a href="#start_transient_config"><var><b>config_dir</b></var>/start-transient-outrigger.config</a> -</pre> -</blockquote> <p> - -This configuration uses the following additional files. - -<a name="start_transient_config"> -<h4>File <var><b>config_dir</b></var>/start-transient-outrigger.config</h4> -</a> - -Use this configuration source file to start transient Outrigger using -Jini ERI. <p> - -<blockquote> -<pre> -import com.sun.jini.start.NonActivatableServiceDescriptor; -import com.sun.jini.start.ServiceDescriptor; -import com.sun.jini.config.ConfigUtil; - -com.sun.jini.start { - private static basecodebase = "http://"; + ConfigUtil.getHostName() + - ":<var><b>http_port</b></var>/"; - private static codebase = basecodebase + "outrigger-dl.jar " + - basecodebase + "jsk-dl.jar"; - - private static policy = "<a href="#outrigger_all_policy"><var><b>config_dir</b></var>/outrigger-all.policy</a>"; - private static classpath = "<var><b>install_dir</b></var>/lib/outrigger.jar"; - private static config = "<a href="#transient_config"><var><b>config_dir</b></var>/transient-outrigger.config</a>"; - - static serviceDescriptors = new ServiceDescriptor[] { - new NonActivatableServiceDescriptor( - codebase, policy, classpath, - "com.sun.jini.outrigger.TransientOutriggerImpl", - new String[] { config }) - }; -} -</pre> -</blockquote> - -<a name="transient_config"> -<h4>File <var><b>config_dir</b></var>/transient-outrigger.config</h4> -</a> - -Use this configuration source file to run transient Outrigger using Jini -ERI. <p> - -<blockquote> -<pre> -com.sun.jini.outrigger { - initialLookupGroups = new String[] { "<var><b>your.group</b></var>" }; -} -</pre> -</blockquote> - - -<a name="persistent"> -<h3>Starting Persistent Outrigger using Jini ERI</h3> -</a> - -This configuration starts a persistent, but non-activatable Outrigger -server that will use Jini ERI to communicate between proxies and the -server. Like the <a href="#transient">transient Jini ERI</a> and <a -href="#transient_jrmp">transient JRMP</a> configurations, only one VM will -be involved. Unlike the transient configurations, the space's state will be -persisted so the space can be reconstituted if the original VM hosting the -Outrigger server dies. Unlike the <a href="#activatable">activatable -Jini ERI</a> and <a href="#activatable_jrmp">activatable JRMP</a> -configurations, the restarting of the space will not occur automatically, -but must done by re-issuing a command similar to the one that started the -Outrigger server originally. Such a configuration is useful if you need a -persistent space but need more control over the how the space gets -restarted than the activation daemon will provide.<p> - -<blockquote> -<pre> -java -Djava.security.policy=<a href="#outrigger_all_policy"><var><b>config_dir</b></var>/outrigger-all.policy</a> \ - -jar <var><b>install_dir</b></var>/lib/start.jar \ - <a href="#start_persistent_config"><var><b>config_dir</b></var>/start-persistent-outrigger.config</a> -</pre> -</blockquote> <p> - -This configuration uses the following additional files. - -<a name="start_persistent_config"> -<h4>File <var><b>config_dir</b></var>/start-persistent-outrigger.config</h4> -</a> - -Use this configuration source file to start persistent Outrigger using Jini -ERI. <p> - -<blockquote> -<pre> -import com.sun.jini.start.NonActivatableServiceDescriptor; -import com.sun.jini.start.ServiceDescriptor; -import com.sun.jini.config.ConfigUtil; - -com.sun.jini.start { - private static basecodebase = "http://"; + ConfigUtil.getHostName() + - ":<var><b>http_port</b></var>/"; - private static codebase = basecodebase + "outrigger-dl.jar " + - basecodebase + "jsk-dl.jar"; - - private static policy = "<a href="#outrigger_all_policy"><var><b>config_dir</b></var>/outrigger-all.policy</a>"; - private static classpath = "<var><b>install_dir</b></var>/lib/outrigger.jar"; - private static config = "<a href="#persistent_config"><var><b>config_dir</b></var>/persistent-outrigger.config</a>"; - - static serviceDescriptors = new ServiceDescriptor[] { - new NonActivatableServiceDescriptor( - codebase, policy, classpath, - "com.sun.jini.outrigger.PersistentOutriggerImpl", - new String[] { config }) - }; -} -</pre> -</blockquote> - -<a name="persistent_config"> -<h4>File <var><b>config_dir</b></var>/persistent-outrigger.config</h4> -</a> - -Use this configuration source file to run persistent Outrigger using Jini -ERI and the Snaplogstore implementation of <code>Store</code>. <p> - -<blockquote> -<pre> -import com.sun.jini.outrigger.snaplogstore.LogStore; -import net.jini.id.UuidFactory; -import net.jini.jeri.BasicILFactory; -import net.jini.jeri.BasicJeriExporter; -import net.jini.jeri.tcp.TcpServerEndpoint; - -com.sun.jini.outrigger { - initialLookupGroups = new String[] { "<var><b>your.group</b></var>" }; - persistenceDirectory = "<var><b>config_dir</b></var>/outrigger.log"; - store = new LogStore(this); - serverExporter = new BasicJeriExporter( - TcpServerEndpoint.getInstance(<var><b>obj_port</b></var>), - new BasicILFactory(), - false, - true, - UuidFactory.create("<var><b>obj_UUID_string</b></var>")); -} -</pre> -</blockquote> - -The <var><b>obj_port</b></var> is the fixed TCP port that the server will -use to listen for incoming remote calls. The -<var><b>obj_UUID_string</b></var> is the fixed {@linkplain net.jini.id.Uuid -universally unique ID} for the server's inner proxy (the inner proxy is -used by Outrigger's proxies to access the server). These IDs have the form -<code>"01234567-89ab-cdef-0123-456789abcdef"</code>. By keeping the UUID -and port constant you will ensure that old references to the space will -still function after a re-start.<p> - -Remember to remove the <var><b>config_dir</b></var>/outrigger.log directory -before restarting persistent Outrigger if you want to start a new (empty) -space with a new identity. If you want to keep the old space and start a -new one, change the value of the <code>persistenceDirectory</code> -configuration entry. - -<a name="persistent_jrmp"> -<h4>Persistent Outrigger using JRMP</h4> -</a> - -Unlike the transient and activatable examples where either JRMP or Jini ERI -can be used as the transport, there is no supported way to use JRMP with a -persistent, non-activatable Outrigger. This is because when Outrigger has -been configured to use JRMP without activation and is restarted, clients of -the service that hold old proxies to the service (ones that were created on -a previous run) will not be able to interact with the service through those -old proxies; effectively making the restarted service useless to those -clients. A proxy that was created in a previous run cannot be used to -communicate with the restarted service because such a proxy is associated -with an old object ID, produced when the service was previously exported; -whereas the restarted service will be associated with a <b><i>new</i></b>, -different object ID, produced when the service is re-exported during the -restart. Note that this will be true even if the service is re-exported on -the same port. While this could be worked around for the top level proxy -by having clients get a new proxy from the lookup service, there is no way -to get a new proxy for an existing Outrigger lease. Such an arrangement can -also cause problems for any transaction managers managing transactions that -the Outrigger server was participating in.<p> - - -<a name="activatable"> -<h3>Starting Activatable Outrigger using Jini ERI</h3> -</a> - -This configuration starts an activatable (and persistent) Outrigger server -that will use Jini ERI to communicate between proxies and the server. In -this configuration the space is persistent and the activation system is -used to restart the server when necessary (e.g. after a crash). -<p> - -If you are not familiar with Java RMI activation you should read this <a -href="../../../../../release-notes/activation.html">note on activation</a> -first. For day to day development, or if you are just starting with Jini -technology you may be better served with either the <a -href="#transient_jrmp">transient JRMP</a> or <a href="#transient">transient -Jini ERI</a> configurations. If you require persistence you may also want to -try the <a href="#persistent">persistent Jini ERI</a> configuration. -<p> - -<blockquote> -<pre> -java -Djava.security.policy=<a href="#outrigger_all_policy"><var><b>config_dir</b></var>/outrigger-all.policy</a> \ - -jar <var><b>install_dir</b></var>/lib/start.jar \ - <a href="#start_activatable_config"><var><b>config_dir</b></var>/start-activatable-outrigger.config</a> -</pre> -</blockquote> <p> - -This command will create a <em>new</em> activation group and create a -<em>new</em> Outrigger service instance that will be placed in that -group. If you execute the command twice you will end up with an error -message from the attempt to create the activation group and two Outrigger -services in the same activation group trying to share the same persistence -directory. -<p> - -If the goal of executing the command twice is to have two spaces, then -before the second invocation you should change the value of the -<code>persistenceDirectory</code> configuration entry in <code><a -href="#activatable_config">activatable-outrigger.config</a></code> and -either : -<ul> -<li> Change the value of the <code>groupPersistenceDirectory</code> - configuration entry in <a - href=#start_activatable_config>start-activatable-outrigger.config</a>, - which will give you two spaces in <em>two activation groups</em>. -<li> Remove the <code>SharedActivationGroupDescriptor</code> instance - from the <code>serviceDescriptors</code> configuration entry in
[... 2215 lines stripped ...]
