Modified: river/jtsk/skunk/qa_refactor/trunk/src/com/sun/jini/reggie/package.html URL: http://svn.apache.org/viewvc/river/jtsk/skunk/qa_refactor/trunk/src/com/sun/jini/reggie/package.html?rev=1634322&r1=1634321&r2=1634322&view=diff ============================================================================== --- river/jtsk/skunk/qa_refactor/trunk/src/com/sun/jini/reggie/package.html (original) +++ river/jtsk/skunk/qa_refactor/trunk/src/com/sun/jini/reggie/package.html Sun Oct 26 13:17:28 2014 @@ -1,1771 +1,1801 @@ -<!-- - ! 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. - !--> - -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<html> -<head> - - -</head> -<body bgcolor="white"> - -Provides implementations of {@link net.jini.core.lookup.ServiceRegistrar}. -Two implementations are available for use with the {@link com.sun.jini.start} -package: - -<ul> - -<li> <code>com.sun.jini.reggie.PersistentRegistrarImpl</code> - a persistent - implementation which can be run either as activatable or non-activatable, - suitable for use with - {@link com.sun.jini.start.SharedActivatableServiceDescriptor} or - {@link com.sun.jini.start.NonActivatableServiceDescriptor} - -<li> <code>com.sun.jini.reggie.TransientRegistrarImpl</code> - a - non-activatable transient implementation, suitable for use with - {@link com.sun.jini.start.NonActivatableServiceDescriptor} - -</ul> <p> - -The name "Reggie" loosely refers to either implementation. The JAR file -<code>reggie.jar</code>, included in the <code>lib</code> subdirectory of the -Apache River release installation, contains the -classes for both Reggie service implementations. The <code>reggie-dl.jar</code> -and <code>jsk-dl.jar</code> files in the <code>lib-dl</code> subdirectory -contain the classes needed in the codebase for its downloaded proxies. -None of the JAR files include classes from <code>jsk-platform.jar</code>, -which are included by the service starter's <code>start.jar</code> JAR file, -and need to be included in the codebase of clients. <p> - -The main proxy of an instance of either of the implementations above implements -the <code>ServiceRegistrar</code>, {@link net.jini.admin.Administrable} and -{@link net.jini.id.ReferentUuid} interfaces. The admin proxy, obtainable by -calling the {@link net.jini.admin.Administrable#getAdmin getAdmin} method of -the main proxy, implements the {@link net.jini.lookup.DiscoveryAdmin}, {@link -net.jini.admin.JoinAdmin}, {@link com.sun.jini.admin.DestroyAdmin} and -<code>ReferentUuid</code> interfaces. <p> - -This document provides the following information about Reggie: -<ul> -<li> <a href="#configuration">Configuring Reggie</a> -<li> <a href="#access_control">Access Control Permission Targets</a> -<li> <a href="#logging">Loggers and Logging Levels</a> -<li> <a href="#system_properties">System Properties</a> -<li> <a href="#examples">Examples for Running Reggie</a> -</ul> <p> - -<a name="configuration"> -<h2>Configuring Reggie</h2> -</a> - -Both <code>TransientRegistrarImpl</code> and -<code>PersistentRegistrarImpl</code> service implementations obtain their -configurations 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 configuration entries supported by the two implementations are listed -below. <code>PersistentRegistrarImpl</code> supports all of the listed -entries. <code>TransientRegistrarImpl</code> supports all listed entries -except for the following persistence/activation-specific entries: -<ul> -<li> <a href="#activationIdPreparer"> - <code>activationIdPreparer</code></a> -<li> <a href="#activationSystemPreparer"> - <code>activationSystemPreparer</code></a> -<li> <a href="#persistenceDirectory"> - <code>persistenceDirectory</code></a> -<li> <a href="#persistenceSnapshotThreshold"> - <code>persistenceSnapshotThreshold</code></a> -<li> <a href="#persistenceSnapshotWeight"> - <code>persistenceSnapshotWeight</code></a> -<li> <a href="#recoveredListenerPreparer"> - <code>recoveredListenerPreparer</code></a> -<li> <a href="#recoveredLocatorPreparer"> - <code>recoveredLocatorPreparer</code></a> -</ul> <p> - -All configuration entries listed below have <code>com.sun.jini.reggie</code> as -their component. <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> - <code>new {@link net.jini.security.BasicProxyPreparer}()</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Description: <td> Specifies the proxy preparer to use for the {@link - java.rmi.activation.ActivationID} for this service, if this service is run - as activatable. This service does not invoke any methods on the prepared - <code>ActivationID</code> directly; however, it passes it to clients which - may call its {@link java.rmi.activation.ActivationID#activate activate} - method if they need to reactivate this service. This entry is obtained at - service start and restart if the service is running as activatable, and is - only supported by <code>PersistentRegistrarImpl</code>. -</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> - <code>new {@link net.jini.security.BasicProxyPreparer}()</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Description: <td> Specifies the proxy preparer to use for the {@link - java.rmi.activation.ActivationSystem} proxy. During shutdown, this service - calls the {@link java.rmi.activation.ActivationSystem#unregisterObject - unregisterObject} method on the <code>ActivationSystem</code> instance - returned from this preparer. This entry is obtained at service start and - restart if the service is running as activatable, and is only supported by - <code>PersistentRegistrarImpl</code>. -</table> - -<table summary="Describes the discoveryConstraints 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> - discoveryConstraints</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> {@link net.jini.core.constraint.MethodConstraints} - <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> Specifies constraints to apply to the multicast request, - multicast announcement and unicast discovery protocols. Multicast request - constraints are derived by calling {@link - net.jini.core.constraint.MethodConstraints#getConstraints getConstraints} - on the obtained <code>MethodConstraints</code> instance with a - <code>Method</code> object for the {@link - com.sun.jini.discovery.DiscoveryConstraints#multicastRequest} method; - multicast announcement and unicast discovery constraints are similarly - obtained by passing <code>Method</code> objects for the {@link - com.sun.jini.discovery.DiscoveryConstraints#multicastAnnouncement} and - {@link com.sun.jini.discovery.DiscoveryConstraints#unicastDiscovery} - methods, respectively. A <code>null</code> value is interpreted as mapping - all methods to empty constraints. - <p> - Reggie supports use of the following constraint types to control - discovery behavior: - <ul> - <li> {@link com.sun.jini.discovery.DiscoveryProtocolVersion}: this - constraint can be used to control which version(s) of the multicast - request, multicast announcement, and unicast discovery protocols are - used. Reggie defaults to using version one of the discovery - protocols if this constraint is not specified and no other - constraints, besides the ones listed here, are specified. - <li> {@link com.sun.jini.discovery.MulticastMaxPacketSize}: this - constraint can be used to control the maximum size of multicast - announcement packets to send; it can also be used to specify the - size of the buffer used to receive incoming multicast request - packets. Reggie defaults to <code>512</code> bytes as the maximum - size for announcements sent if this constraint is not specified for - the {@link - com.sun.jini.discovery.DiscoveryConstraints#multicastAnnouncement} - method. Reggie defaults to <code>512</code> bytes as the size of - the buffer used to receive incoming multicast request packets if - this constraint is not specified for the {@link - com.sun.jini.discovery.DiscoveryConstraints#multicastRequest} - method. - <li> {@link com.sun.jini.discovery.MulticastTimeToLive}: this constraint - can be used to control the time to live (TTL) value set on outgoing - multicast request packets. Reggie defaults to sending multicast - announcements with a TTL of <code>15</code> if this constraint is - not specified for the {@link - com.sun.jini.discovery.DiscoveryConstraints#multicastAnnouncement} - method. - <li> {@link com.sun.jini.discovery.UnicastSocketTimeout}: this constraint - can be used to control the read timeout set on sockets over which - unicast discovery is performed. In other words, it controls the - amount of time Reggie waits to read data from a connected client - attempting to discover Reggie. Reggie defaults to one minute as - the read timeout on sockets over which unicast discovery is - performed if this constraint is not specified for the {@link - com.sun.jini.discovery.DiscoveryConstraints#unicastDiscovery} - method. - <li> {@link net.jini.core.constraint.ConnectionRelativeTime}: - this constraint can be used to control the connection timeout set on - sockets over which unicast discovery is performed. In other words, - it controls the amount of time Reggie waits to connect to a client - attempting to discover Reggie. If this constraint is not specified - for the {@link - com.sun.jini.discovery.DiscoveryConstraints#unicastDiscovery} - method, the connection attempt will block until the connection - is established or an error occurs. - <li> {@link net.jini.core.constraint.ConnectionAbsoluteTime}: - This constraint can be used to set a time after which reggie will - cease to respond to discovery requests. By default, Reggie has no - limitation on how long to continue responding to discovery requests. - </ul> - Constraints other than those listed above are passed on to the underlying - implementations of versions 1 and 2 of the discovery protocols. This entry - is 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> Specifies <code>DiscoveryManagement</code> instance to - use to discover other lookup services with which this service should - register. The object returned must also implement {@link - net.jini.discovery.DiscoveryGroupManagement} and {@link - net.jini.discovery.DiscoveryLocatorManagement}, and should be configured - initially to discover no groups or specific lookup services. This entry is - obtained at service start and restart. -</table> - -<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> <code>{@link net.jini.core.entry.Entry}[]</code> - <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> Specifies initial attributes to use when registering with - lookup services (including self). The <code>null</code> value is - equivalent to an empty <code>Entry</code> array. This service - implementation provides two additional hardcoded attributes--a {@link - net.jini.lookup.entry.ServiceInfo} instance with <code>name</code> field - set to the string <code>"Lookup"</code>, and a {@link - com.sun.jini.lookup.entry.BasicServiceType} instance with <code>type</code> - field also set to <code>"Lookup"</code>--which are combined with the - entry-specified attributes to obtain the total set of initial attributes - with which to register. This entry is obtained once at service start; the - current set of attributes (modifiable via the {@link - net.jini.admin.JoinAdmin} methods of Reggie's admin object) is persisted - across restarts. -</table> - -<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> <code>String[]</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> {@link net.jini.discovery.DiscoveryGroupManagement#NO_GROUPS} - <tr valign="top"> <td>   <th scope="row" align="right"> - Description: <td> Specifies initial groups for determining the set of - lookup services with which to register. This entry is obtained once at - service start; the current set of lookup groups (modifiable via the {@link - net.jini.admin.JoinAdmin} methods of Reggie's admin object) is persisted - across restarts. -</table> - -<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> <code>{@link net.jini.core.discovery.LookupLocator}[]</code> - <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> Specifies initial list of locators indicating other - lookup services with which to register. This entry is obtained once at - service start; the current set of lookup locators (modifiable via the - {@link net.jini.admin.JoinAdmin} methods of Reggie's admin object) is - persisted across restarts. -</table> - -<table summary="Describes the initialMemberGroups 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> - initialMemberGroups</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> <code>String[]</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> <code>new String[]{ "" }</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Description: <td> Specifies initial groups for this lookup service to be a - member of. The value should not be <code>null</code> (which is equal to - {@link net.jini.discovery.DiscoveryGroupManagement#ALL_GROUPS}). This - entry is obtained once at service start; the current set of member groups - (modifiable via the {@link net.jini.lookup.DiscoveryAdmin} methods of - Reggie's admin object) is persisted across restarts. -</table> - -<table summary="Describes the initialUnicastDiscoveryPort 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> - initialUnicastDiscoveryPort</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>0</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Description: <td> Specifies the initial number of the port on which to - listen for unicast discovery queries. If the port number is - <code>0</code>, then an arbitrary port is selected (with preference given - to {@link net.jini.discovery.Constants#discoveryPort}, if available). This - entry is obtained once at service start; the current value (modifiable via - the {@link net.jini.lookup.DiscoveryAdmin} methods of Reggie's admin - object) is persisted across restarts. -</table> - -<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> - <code>new {@link net.jini.security.BasicProxyPreparer}()</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Description: <td> Specifies the proxy preparer to use for {@link - net.jini.core.event.RemoteEventListener}s registered with this service in - calls to {@link net.jini.core.lookup.ServiceRegistrar#notify}. During - event notification, this service calls the {@link - net.jini.core.event.RemoteEventListener#notify notify} method on - <code>RemoteEventListener</code> instances returned from this preparer. - This entry is obtained at service start and restart. -</table> - -<table summary="Describes the locatorPreparer 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> - locatorPreparer</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> - <code>new {@link net.jini.security.BasicProxyPreparer}()</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Description: <td> Specifies the proxy preparer to use for {@link - net.jini.core.discovery.LookupLocator}s passed to this service in calls to - the {@link net.jini.admin.JoinAdmin#addLookupLocators addLookupLocators}, - {@link net.jini.admin.JoinAdmin#setLookupLocators setLookupLocators} and - {@link net.jini.admin.JoinAdmin#removeLookupLocators removeLookupLocators} - methods of its admin object. When registering with other lookup services, - this service may call or use the constraints assigned to the - <code>getRegistrar</code> methods of <code>LookupLocator</code> instances - returned from this preparer. This entry is obtained at service start and - restart. -</table> - -<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> Do not perform JAAS login - <tr valign="top"> <td>   <th scope="row" align="right"> - Description: <td> Specifies the JAAS login context to use for performing a - JAAS login and supplying the {@link javax.security.auth.Subject} to use - when running the service. If this entry is not specified or if it is - specified with a value of <code>null</code>, no JAAS login is - performed. This entry is obtained at service start and restart. -</table> - -<table summary="Describes the minMaxEventLease 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> - minMaxEventLease</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 * 60 * 30L</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Description: <td> Specifies the lower bound for the maximum value allowed - for event leases, in milliseconds. The maximum event lease granted is - never less than the specified value, but may be greater than it if the - expected average time between lease renewals (based on the current number - of service and event registrations) would be less than the value of the - <code>minRenewalInterval</code> configuration entry. This entry replaces - in function the <code>setMinMaxEventLease</code> method of the - <code>RegistrarAdmin</code> interface supported by previous implementations - of Reggie, and is obtained at service start and restart. -</table> - -<table summary="Describes the minMaxServiceLease 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> - minMaxServiceLease</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 * 60 * 5L</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Description: <td> Specifies the lower bound for the maximum value allowed - for service leases, in milliseconds. The maximum service lease granted is - never less than the specified value, but may be greater than it if the - expected average time between lease renewals (based on the current number - of service and event registrations) would be less than the value of the - <code>minRenewalInterval</code> configuration entry. This entry replaces - in function the <code>setMinMaxServiceLease</code> method of the - <code>RegistrarAdmin</code> interface supported by previous implementations - of Reggie, and is obtained at service start and restart. -</table> - -<table summary="Describes the minRenewalInterval 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> - minRenewalInterval</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>100L</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Description: <td> Specifies the minimum average time to maintain between - lease renewals, in milliseconds. This entry replaces in function the - <code>setMinRenewalInterval</code> method of the - <code>RegistrarAdmin</code> interface supported by previous implementations - of Reggie, and is obtained at service start and restart. -</table> - -<a name="multicastAnnouncementInterval"></a> -<table summary="Describes the multicastAnnouncementInterval - 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> - multicastAnnouncementInterval</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 * 60 * 2L</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Description: <td> Specifies the number of milliseconds to wait in between - sending multicast announcement packets. This entry is consulted instead of - the <code>net.jini.discovery.announce</code> system property used by - previous implementations of Reggie. This entry is obtained at service - start and restart. -</table> - -<table summary="Describes the multicastInterfaceRetryInterval - 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> - multicastInterfaceRetryInterval</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 * 60 * 5</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Description: <td> Specifies the number of milliseconds to wait in between - retrying multicast interfaces for which initial attempts at enablement - failed. Failed interfaces are retried at the given interval until they are - successfully enabled; the overall set of multicast interfaces to use is - configurable via the <code>multicastInterfaces</code> configuration entry. - This entry is obtained at service start and restart. -</table> - -<a name="multicastInterfaces"></a> -<table summary="Describes the multicastInterfaces 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> - multicastInterfaces</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> <code>{@link java.net.NetworkInterface}[]</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> Use all network interfaces - <tr valign="top"> <td>   <th scope="row" align="right"> - Description: <td> Specifies the network interfaces to use to send and - receive multicast request and announcement packets as part of multicast - discovery. If no value is specified for this entry, then all network - interfaces of the host are used. If the entry value is <code>null</code>, - then the interface to which the operating system defaults is used. If the - entry value is a zero-length array, then multicast discovery is disabled. - This entry is consulted instead of the - <code>net.jini.discovery.interface</code> system property used by previous - implementations of Reggie, and is obtained at service start and restart. -</table> - -<table summary="Describes the multicastRequestSubjectChecker - 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> - multicastRequestSubjectChecker</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> {@link com.sun.jini.discovery.ClientSubjectChecker} - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> Do not check {@link javax.security.auth.Subject}s of - multicast requests - <tr valign="top"> <td>   <th scope="row" align="right"> - Description: <td> Specifies the object to use for screening multicast - requests based on their authenticated <code>Subject</code>s. This entry is - 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> <code>String</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> <em>Required: no default</em> - <tr valign="top"> <td>   <th scope="row" align="right"> - Description: <td> Specifies the directory where the service's persistent - state is recorded. This entry is obtained at service start and restart, - and is only supported by <code>PersistentRegistrarImpl</code>, which - requires it to be set. -</table> - -<a name="persistenceSnapshotThreshold"></a> -<table summary="Describes the persistenceSnapshotThreshold 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> - persistenceSnapshotThreshold</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>200</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Description: <td> Specifies the minimum number of log updates before a new - snapshot can be taken. This entry replaces the - <code>setLogToSnapshotThreshold</code> method of the - <code>RegistrarAdmin</code> interface supported by previous implementations - of Reggie. It is obtained at service start and restart, and is only - supported by <code>PersistentRegistrarImpl</code>. -</table> - -<a name="persistenceSnapshotWeight"></a> -<table summary="Describes the persistenceSnapshotWeight 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> - persistenceSnapshotWeight</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> <code>float</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> <code>10.0F</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Description: <td> Specifies the weight factor by which the snapshot size is - multiplied in order to determine when to take the next snapshot--when the - number of log records exceeds the product of - <code>persistenceSnapshotWeight</code> and the snapshot size and is larger - than the <code>persistenceSnapshotThreshold</code> value, then a snapshot - is taken. This entry replaces the <code>setSnapshotWeight</code> method of - the <code>RegistrarAdmin</code> interface supported by previous - implementations of Reggie. It is obtained at service start and restart, - and is only supported by <code>PersistentRegistrarImpl</code>. -</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> - <code>new {@link net.jini.security.BasicProxyPreparer}()</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Description: <td> Specifies the proxy preparer to use for {@link - net.jini.core.event.RemoteEventListener}s recovered from the service's - persistent state log. During event notification, this service calls the - {@link net.jini.core.event.RemoteEventListener#notify notify} method on - <code>RemoteEventListener</code> instances returned from this preparer. - This entry is obtained at service start and restart, and is only supported - by <code>PersistentRegistrarImpl</code>. -</table> - -<a name="recoveredLocatorPreparer"></a> -<table summary="Describes the recoveredLocatorPreparer 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> - recoveredLocatorPreparer</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> - <code>new {@link net.jini.security.BasicProxyPreparer}()</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Description: <td> Specifies the proxy preparer to use for {@link - net.jini.core.discovery.LookupLocator}s recovered from the service's - persistent state log. When registering with other lookup services, this - service may call or use the constraints assigned to the - <code>getRegistrar</code> methods of <code>LookupLocator</code> instances - returned from this preparer. This entry is obtained at service start and - restart, and is only supported by <code>PersistentRegistrarImpl</code>. -</table> - -<table summary="Describes the resourceIdGenerator 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> - resourceIdGenerator</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> {@link com.sun.jini.reggie.UuidGenerator} - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> <code>new UuidGenerator()</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Description: <td> Specifies the generator for producing {@link - net.jini.id.Uuid}s assigned to resources dispensed by the service, such as - leases and service registrations. This entry is obtained at service start - and restart. -</table> - -<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> -<pre> -// if non-activatable -new {@link net.jini.jeri.BasicJeriExporter}( - {@link net.jini.jeri.tcp.TcpServerEndpoint}.getInstance(0), - new {@link net.jini.jeri.BasicILFactory}()) - -// if activatable -new {@link net.jini.activation.ActivationExporter}( - activationID, - new BasicJeriExporter( - TcpServerEndpoint.getInstance(0), - new BasicILFactory())) -</pre> - <tr valign="top"> <td>   <th scope="row" align="right"> - Description: <td> Specifies the exporter to use to export this service. - Note that this entry, while supported by both - <code>TransientRegistrarImpl</code> and - <code>PersistentRegistrarImpl</code>, has a different default value for - <code>PersistentRegistrarImpl</code> in the activatable case. For the - activatable case, the <code>activationID</code> value is passed in as the - <code>data</code> argument in the call to {@link - net.jini.config.Configuration#getEntry(String,String,Class,Object,Object)}. - This entry is obtained at service start and restart. -</table> - -<table summary="Describes the serviceIdGenerator 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> - serviceIdGenerator</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> {@link com.sun.jini.reggie.UuidGenerator} - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> <code>new UuidGenerator()</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Description: <td> Specifies the generator for producing service IDs - assigned to services registering with this lookup service that do not - already have service IDs. This generator is also used to produce the - service ID for this lookup service. The {@link net.jini.id.Uuid}s returned - by the generator are converted into {@link net.jini.core.lookup.ServiceID} - instances by extracting their 128-bit values and using them to construct - corresponding <code>ServiceID</code>s. This entry is obtained at service - start and restart. -</table> - -<table summary="Describes the taskManager 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> - taskManager</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 TaskManager(50, 1000 * 15, 1.0F)</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Description: <td> Specifies the object that pools and manages the threads - used by this service to respond to discovery requests and send event - notifications. This entry is obtained at service start and restart. -</table> - -<a name="unexportTimeout"></a> -<table summary="Describes the unexportTimeout 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> - unexportTimeout</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 * 60 *2L</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Description: <td> Specifies the maximum time in milliseconds to wait for - in-progress calls to finish before forcibly unexporting Reggie during - shutdown. -</table> - -<a name="unexportWait"></a> -<table summary="Describes the unexportWait 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> - unexportWait</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>1000L</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Description: <td> Specifies the maximum time in milliseconds to wait - between unexport attempts during shutdown while <a href=#unexportTimeout> - <code>unexportTimeout</code></a> has not expired. -</table> - -<a name="unicastDiscoveryHost"></a> -<table summary="Describes the unicastDiscoveryHost 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> - unicastDiscoveryHost</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> <code>String</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> <code> - {@link java.net.InetAddress}.getLocalHost().getHostName()</code> - <tr valign="top"> <td>   <th scope="row" align="right"> - Description: <td> Specifies the host name for unicast discovery, which is - advertised in multicast announcements and (protocol 2) unicast discovery - responses. This entry is obtained at service start and restart. -</table> - -<table summary="Describes the unicastDiscoverySubjectChecker - 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> - unicastDiscoverySubjectChecker</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Type: <td> {@link com.sun.jini.discovery.ClientSubjectChecker} - <tr valign="top"> <td>   <th scope="row" align="right"> - Default: <td> Do not check client {@link javax.security.auth.Subject} - during unicast discovery - <tr valign="top"> <td>   <th scope="row" align="right"> - Description: <td> Specifies the object to use for screening unicast - discovery attempts based on their authenticated client - <code>Subject</code>s. This entry is obtained at service start and - restart. -</table> -<p> - -<h3>Other Configuration Entries</h3> - -Reggie passes its configuration when creating instances of the following -configurable classes, which may support additional configuration entries: -<ul> -<li> {@link net.jini.discovery.LookupDiscoveryManager}, used to discover - lookup services, as specified by the <a href="#discoveryManager"> - <code>discoveryManager</code></a> configuration entry -<li> {@link net.jini.lookup.JoinManager}, used to manage lookup service - registrations -</ul> <p> - -<a name="access_control"> -<h2>Access Control Permission Targets</h2> -</a> - -The following table lists the remote methods on Reggie's proxy objects and -the associated target names for enforcing access control using {@link -com.sun.jini.reggie.RegistrarPermission}: <p> - -<table border="1" cellpadding="5" - summary="Describes the proxy methods and associated target names for - RegistrarPermission"> - -<tr> <th> Proxy Method <th> Target Name - -<!-- ServiceRegistrar --> - -<tr> <td> {@link net.jini.core.lookup.ServiceRegistrar#getEntryClasses - ServiceRegistrar.getEntryClasses} - <td> <code>getEntryClasses</code> - -<tr> <td> {@link net.jini.core.lookup.ServiceRegistrar#getFieldValues - ServiceRegistrar.getFieldValues} - <td> <code>getFieldValues</code> - -<tr> <td> {@link net.jini.core.lookup.ServiceRegistrar#getGroups - ServiceRegistrar.getGroups} - <td> <code>getMemberGroups</code> - -<tr> <td> {@link net.jini.core.lookup.ServiceRegistrar#getLocator - ServiceRegistrar.getLocator} - <td> <code>getLocator</code> - -<tr> <td> {@link net.jini.core.lookup.ServiceRegistrar#getServiceTypes - ServiceRegistrar.getServiceTypes} - <td> <code>getServiceTypes</code> - -<tr> <td> {@link net.jini.core.lookup.ServiceRegistrar#lookup( - net.jini.core.lookup.ServiceTemplate) - ServiceRegistrar.lookup(ServiceTemplate)} - <td> <code>lookup</code> - -<tr> <td> {@link net.jini.core.lookup.ServiceRegistrar#lookup( - net.jini.core.lookup.ServiceTemplate, int) - ServiceRegistrar.lookup(ServiceTemplate, int)} - <td> <code>lookup</code> - -<tr> <td> {@link net.jini.core.lookup.ServiceRegistrar#notify - ServiceRegistrar.notify} - <td> <code>notify</code> - -<tr> <td> {@link net.jini.core.lookup.ServiceRegistrar#register - ServiceRegistrar.register} - <td> <code>register</code> - -<!-- Administrable --> - -<tr> <td> {@link net.jini.admin.Administrable#getAdmin Administrable.getAdmin} - <td> <code>getAdmin</code> - -<!-- ServiceProxyAccessor --> - -<tr> <td> {@link com.sun.jini.start.ServiceProxyAccessor#getServiceProxy - ServiceProxyAccessor.getServiceProxy} - <td> <code>getServiceProxy</code> - -<!-- ServiceRegistration --> - -<tr> <td> {@link net.jini.core.lookup.ServiceRegistration#addAttributes - ServiceRegistration.addAttributes} - <td> <code>addAttributes</code> - -<tr> <td> {@link net.jini.core.lookup.ServiceRegistration#modifyAttributes - ServiceRegistration.modifyAttributes} - <td> <code>modifyAttributes</code> - -<tr> <td> {@link net.jini.core.lookup.ServiceRegistration#setAttributes - ServiceRegistration.setAttributes} - <td> <code>setAttributes</code> - -<!-- Lease --> - -<tr> <td> {@link net.jini.core.lease.Lease#cancel Lease.cancel} - (for event leases) - <td> <code>cancelEventLease</code> - -<tr> <td> {@link net.jini.core.lease.Lease#renew Lease.renew} - (for event leases) - <td> <code>renewEventLease</code> - -<tr> <td> {@link net.jini.core.lease.Lease#cancel Lease.cancel} - (for service leases) - <td> <code>cancelServiceLease</code> - -<tr> <td> {@link net.jini.core.lease.Lease#renew Lease.renew} - (for service leases) - <td> <code>renewServiceLease</code> - -<!-- LeaseMap --> - -<tr> <td> {@link net.jini.core.lease.LeaseMap#cancelAll LeaseMap.cancelAll} - <td> <code>cancelLeases</code> - -<tr> <td> {@link net.jini.core.lease.LeaseMap#renewAll LeaseMap.renewAll} - <td> <code>renewLeases</code> - -<!-- DiscoveryAdmin --> - -<tr> <td> {@link net.jini.lookup.DiscoveryAdmin#addMemberGroups - DiscoveryAdmin.addMemberGroups} - <td> <code>addMemberGroups</code> - -<tr> <td> {@link net.jini.lookup.DiscoveryAdmin#getMemberGroups - DiscoveryAdmin.getMemberGroups} - <td> <code>getMemberGroups</code> - -<tr> <td> {@link net.jini.lookup.DiscoveryAdmin#getUnicastPort - DiscoveryAdmin.getUnicastPort} - <td> <code>getUnicastPort</code> - -<tr> <td> {@link net.jini.lookup.DiscoveryAdmin#removeMemberGroups - DiscoveryAdmin.removeMemberGroups} - <td> <code>removeMemberGroups</code> - -<tr> <td> {@link net.jini.lookup.DiscoveryAdmin#setMemberGroups - DiscoveryAdmin.setMemberGroups} - <td> <code>setMemberGroups</code> - -<tr> <td> {@link net.jini.lookup.DiscoveryAdmin#setUnicastPort - DiscoveryAdmin.setUnicastPort} - <td> <code>setUnicastPort</code> - -<!-- JoinAdmin --> - -<tr> <td> {@link net.jini.admin.JoinAdmin#addLookupAttributes - JoinAdmin.addLookupAttributes} - <td> <code>addLookupAttributes</code> - -<tr> <td> {@link net.jini.admin.JoinAdmin#addLookupGroups - JoinAdmin.addLookupGroups} - <td> <code>addLookupGroups</code> - -<tr> <td> {@link net.jini.admin.JoinAdmin#addLookupLocators - JoinAdmin.addLookupLocators} - <td> <code>addLookupLocators</code> - -<tr> <td> {@link net.jini.admin.JoinAdmin#getLookupAttributes - JoinAdmin.getLookupAttributes} - <td> <code>getLookupAttributes</code> - -<tr> <td> {@link net.jini.admin.JoinAdmin#getLookupGroups - JoinAdmin.getLookupGroups} - <td> <code>getLookupGroups</code> - -<tr> <td> {@link net.jini.admin.JoinAdmin#getLookupLocators - JoinAdmin.getLookupLocators} - <td> <code>getLookupLocators</code> - -<tr> <td> {@link net.jini.admin.JoinAdmin#modifyLookupAttributes - JoinAdmin.modifyLookupAttributes} - <td> <code>modifyLookupAttributes</code> - -<tr> <td> {@link net.jini.admin.JoinAdmin#removeLookupGroups - JoinAdmin.removeLookupGroups} - <td> <code>removeLookupGroups</code> - -<tr> <td> {@link net.jini.admin.JoinAdmin#removeLookupLocators - JoinAdmin.removeLookupLocators} - <td> <code>removeLookupLocators</code> - -<tr> <td> {@link net.jini.admin.JoinAdmin#setLookupGroups - JoinAdmin.setLookupGroups} - <td> <code>setLookupGroups</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> - -</table> <p> - -<a name="logging"> -<h2>Loggers and Logging Levels</h2> -</a> - -Both <code>PersistentRegistrarImpl</code> and -<code>TransientRegistrarImpl</code> log diagnostic information to the {@link -java.util.logging.Logger} named <code>com.sun.jini.reggie</code>. The -server-side components of each implementation log information at the following -logging levels: <p> - -<table border="1" cellpadding="5" - summary="Describes logging performed by Reggie's server-side components - at different logging levels"> - - <caption halign="center" valign="top"><b><code> - com.sun.jini.reggie</code> (server-side)</b></caption> - - <tr> <th scope="col"> Level <th scope="col"> Description - - <tr> <td> {@link java.util.logging.Level#SEVERE SEVERE} <td> - Exceptions that prevent service startup - - <tr> <td> {@link java.util.logging.Level#WARNING WARNING} <td> - Exceptions that, while non-fatal, indicate compromised service functionality, - such as failures to persist or recover state, or to send multicast - announcements on an explicitly configured interface - - <tr> <td> {@link java.util.logging.Level#INFO INFO} <td> - Service start, restart, or destruction events, as well as exceptions of - moderate severity, such as failures to send event notifications or multicast - announcements, or to establish a unicast discovery connection - - <tr> <td> {@link java.util.logging.Level#CONFIG CONFIG} <td> - Changes made to the service through administrative interfaces, as well as - high-level service configuration information, such as the persistence - directory (if any) and multicast interfaces (if any) used - - <tr> <td> {@link com.sun.jini.logging.Levels#HANDLED HANDLED} <td> - Minor exceptions involving activation, discovery, event handling, and - shutdown that are handled internally by the service, and not reflected to - callers - - <tr> <td> {@link java.util.logging.Level#FINE FINE} <td> - Changes in service state, such as the establishment, expiration, and - cancellation of service and event listener registrations, as well as invalid - service ID values - - <tr> <td> {@link java.util.logging.Level#FINER FINER} <td> - Persistent state log operations - -</table> <p> - -The service proxies for <code>PersistentRegistrarImpl</code> and -<code>TransientRegistrarImpl</code> log information at the following logging -levels: <p> - -<table border="1" cellpadding="5" - summary="Describes logging performed by Reggie's service proxy at - different logging levels"> - - <caption halign="center" valign="top"><b><code> - com.sun.jini.reggie</code> (service proxy)</b></caption> - - <tr> <th> Level <th> Description - - <tr> <td> {@link java.util.logging.Level#WARNING WARNING} <td> - Invalid service IDs used for registration - - <tr> <td> {@link java.util.logging.Level#INFO INFO} <td> - Service item unmarshalling exceptions - -</table> <p> - -<a name="system_properties"> -<h2>System Properties</h2> -</a> - -Both <code>TransientRegistrarImpl</code> and -<code>PersistentRegistrarImpl</code> service implementations support the -following system property: <p> - -<a name="enableImplToStubReplacement"></a> -<table summary="Describes the com.sun.jini.reggie.enableImplToStubReplacement - system property" - 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> - com.sun.jini.reggie.enableImplToStubReplacement</code></font> - <tr valign="top"> <td>   <th scope="row" align="right"> - Description: <td> This system property is interpreted as a - <code>boolean</code> value (see {@link java.lang.Boolean#getBoolean - Boolean.getBoolean}). If <code>true</code>, then JRMP impl-to-stub - replacement will be attempted on the service proxy objects contained in - {@link net.jini.core.lookup.ServiceItem}s passed to the {@link - net.jini.core.lookup.ServiceRegistrar#register register} method of Reggie's - proxy. By default, this behavior is not enabled--it is provided as a - transitional measure for services that depend on JRMP impl-to-stub - replacement when registering with Reggie. -</table> <p> - -<a name="examples"> -<h2>Examples for Running Reggie</h2> -</a> - -This section provides examples of running Reggie in various configurations. - -<ul> -<li> <a href="#assumptions">Assumptions for running the examples</a> -<li> <a href="#discovery_constraints">Setting Discovery Constraints</a> -<li> JRMP configurations - <ul> - <li> <a href="#transient_jrmp">Transient</a> - <li> <a href="#persistent_jrmp">Persistent</a> - <li> <a href="#activatable_jrmp">Activatable</a> - </ul> -<li> Jini extensible remote invocation (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> - -<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 host name is <var><b>your_host</b></var> -<li> The instance of Reggie to run will advertise itself as a member of the - group named <var><b>your.group</b></var> -<li> The HTTP server for download JAR files is running on - <var><b>your_host</b></var> 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 same - client and service configurations that enforce security. -<li> For activatable services, an activation system is running on - <var><b>your_host</b></var>. You can use the {@link - com.sun.jini.phoenix} implementation for this purpose. -</ul> <p> - -Throughout the example, items in <var><b>bold</b></var> need to be -customized for your local environment. - -<a name="discovery_constraints"> -<h3>Setting Discovery Constraints</h3> -</a> - -Discovery constraints for Reggie can be set by specifying a -<code>discoveryConstraints</code> entry under the -<code>com.sun.jini.reggie</code> component. For example, to specify that -Reggie must wait at most five seconds to connect to a client attempting -discovery and at most three minutes to read data from a connected client -attempting discovery, the following entry must be added to Reggie's -configuration source file under the <code>com.sun.jini.reggie</code> component: - -<blockquote> -<pre> -discoveryConstraints = new BasicMethodConstraints( - new MethodDesc[] { - new MethodDesc("unicastDiscovery", - new InvocationConstraints( - new InvocationConstraint[] { - new ConnectionRelativeTime(5000), - new UnicastSocketTimeout(180000) // 3*60*1000 - }, - null - ) - ) - } -); -</pre> -</blockquote><p> - -As another example, to specify that Reggie must use version two of of the -multicast request, multicast announcement, and unicast discovery protocols, the -following entry must be added to Reggie's configuration source file under the -<code>com.sun.jini.reggie</code> component. - -<blockquote> -<pre> -discoveryConstraints = new BasicMethodConstraints( - new InvocationConstraints(DiscoveryProtocolVersion.TWO, null) -); -</pre> -</blockquote><p> - -<a name="transient_jrmp"> -<h3>Starting Transient Reggie using JRMP</h3> -</a> - -To run a transient Reggie, which does not store any information -persistently or use the activation system to restart itself, using JRMP -for remote communication, run the following command. <p> - -<blockquote> -<pre> -java -Djava.security.policy=<a href="#jsk_all_policy"><var><b>config_dir</b></var>/jsk-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-reggie.config</a> -</pre> -</blockquote> <p> - -This configuration uses the following files. - -<a name="jsk_all_policy"> -<h4>File <var><b>config_dir</b></var>/jsk-all.policy</h4> -</a> - -Use this security policy file for starting and running all Reggie -configurations. This file grants all permissions to local code included -in the <code>lib</code> subdirectory of the Apache River release installation. <p> - -<blockquote> -<pre> -grant codebase "file:<var><b>install_dir</b></var>/lib/*" { - permission java.security.AllPermission; -}; -</pre> -</blockquote> - -<a name="start_transient_jrmp_config"> -<h4>File <var><b>config_dir</b></var>/start-transient-jrmp-reggie.config</h4> -</a> - -Use this configuration source file to start transient Reggie using -JRMP. <p> - -<blockquote> -<pre> -import com.sun.jini.start.NonActivatableServiceDescriptor; -import com.sun.jini.start.ServiceDescriptor; - -com.sun.jini.start { - private static codebase = "http://<var><b>your_host</b></var>:<var><b>http_port</b></var>/reggie-dl.jar" - + " http://<var><b>your_host</b></var>:<var><b>http_port</b></var>/jsk-dl.jar"; - private static policy = "<a href="#jsk_all_policy"><var><b>config_dir</b></var>/jsk-all.policy</a>"; - private static classpath = "<var><b>install_dir</b></var>/lib/reggie.jar"; - private static config = "<a href="#transient_jrmp_config"><var><b>config_dir</b></var>/transient-jrmp-reggie.config</a>"; - - static serviceDescriptors = new ServiceDescriptor[] { - new NonActivatableServiceDescriptor( - codebase, policy, classpath, - "com.sun.jini.reggie.TransientRegistrarImpl", - new String[] { config }) - }; -} -</pre> -</blockquote> - -<a name="transient_jrmp_config"> -<h4>File <var><b>config_dir</b></var>/transient-jrmp-reggie.config</h4> -</a> - -Use this configuration source file to run transient Reggie using JRMP. <p> - -<blockquote> -<pre> -import net.jini.jrmp.JrmpExporter; - -com.sun.jini.reggie { - initialMemberGroups = new String[] { "<var><b>your.group</b></var>" }; - serverExporter = new JrmpExporter(); -} -</pre> -</blockquote> - -<a name="persistent_jrmp"> -<h3>Starting Persistent Reggie using JRMP</h3> -</a> - -To run a persistent Reggie, which stores information persistently but does -not use the activation system to restart itself, using JRMP for remote -communication, run the following command. <p> - -<blockquote> -<pre> -java -Djava.security.policy=<a href="#jsk_all_policy"><var><b>config_dir</b></var>/jsk-all.policy</a> \ - -jar <var><b>install_dir</b></var>/lib/start.jar \ - <a href="#start_persistent_jrmp_config"><var><b>config_dir</b></var>/start-persistent-jrmp-reggie.config</a> -</pre> -</blockquote> <p> - -<b>Note:</b> Because JRMP does not provide a convenient way to specify -the same object ID each time a given object is exported, this -configuration is only useful for debugging -- an existing service proxy -cannot be used after the service is restarted. <p> - -This configuration uses the following additional files. - -<a name="start_persistent_jrmp_config"> -<h4>File <var><b>config_dir</b></var>/start-persistent-jrmp-reggie.config</h4> -</a> - -Use this configuration source file to start persistent Reggie using -JRMP. <p> - -<blockquote> -<pre> -import com.sun.jini.start.NonActivatableServiceDescriptor; -import com.sun.jini.start.ServiceDescriptor; - -com.sun.jini.start { - private static codebase = "http://<var><b>your_host</b></var>:<var><b>http_port</b></var>/reggie-dl.jar" - + " http://<var><b>your_host</b></var>:<var><b>http_port</b></var>/jsk-dl.jar"; - private static policy = "<a href="#jsk_all_policy"><var><b>config_dir</b></var>/jsk-all.policy</a>"; - private static classpath = "<var><b>install_dir</b></var>/lib/reggie.jar"; - private static config = "<a href="#persistent_jrmp_config"><var><b>config_dir</b></var>/persistent-jrmp-reggie.config</a>"; - - static serviceDescriptors = new ServiceDescriptor[] { - new NonActivatableServiceDescriptor( - codebase, policy, classpath, - "com.sun.jini.reggie.PersistentRegistrarImpl", - new String[] { config }) - }; -} -</pre> -</blockquote> - -<a name="persistent_jrmp_config"> -<h4>File <var><b>config_dir</b></var>/persistent-jrmp-reggie.config</h4> -</a> - -Use this configuration source file to run persistent Reggie using -JRMP. <p> - -<blockquote> -<pre> -import net.jini.jrmp.JrmpExporter; - -com.sun.jini.reggie { - initialMemberGroups = new String[] { "<var><b>your.group</b></var>" }; - persistenceDirectory = "<var><b>config_dir</b></var>/reggie.log"; - serverExporter = new JrmpExporter(); -} -</pre> -</blockquote> - -<a name="activatable_jrmp"> -<h3>Starting Activatable Reggie using JRMP</h3> -</a> - -To run an activatable Reggie, which stores information persistently and -uses the activation system to restart itself, using JRMP for remote -communication, run the following command. <p> - -<blockquote> -<pre> -java -Djava.security.policy=<a href="#jsk_all_policy"><var><b>config_dir</b></var>/jsk-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-reggie.config</a> -</pre> -</blockquote> <p> - -You should remove the <var><b>config_dir</b></var>/group.log directory -before running this command. Note that the activation system will -restart the activatable Reggie service as needed until Reggie is -shutdown. <p> - -Remember to remove the <var><b>config_dir</b></var>/reggie.log directory -before running this command if you want Reggie to forget registrations and -settings made in previous invocations. <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-reggie.config</h4> -</a> - -Use this configuration source file to start activatable Reggie using -JRMP. <p> - -<blockquote> -<pre> -import com.sun.jini.start.ServiceDescriptor; -import com.sun.jini.start.SharedActivatableServiceDescriptor; -import com.sun.jini.start.SharedActivationGroupDescriptor; - -com.sun.jini.start { - private static reggieCodebase = "http://<var><b>your_host</b></var>:<var><b>http_port</b></var>/reggie-dl.jar" - + " http://<var><b>your_host</b></var>:<var><b>http_port</b></var>/jsk-dl.jar"; - private static reggiePolicy = "<a href="#jsk_all_policy"><var><b>config_dir</b></var>/jsk-all.policy</a>"; - private static reggieClasspath = "<var><b>install_dir</b></var>/lib/reggie.jar"; - private static reggieConfig = "<a href="#activatable_jrmp_config"><var><b>config_dir</b></var>/activatable-jrmp-reggie.config</a>"; - - private static groupCodebase = "http://<var><b>your_host</b></var>:<var><b>http_port</b></var>/group-dl.jar"; - private static groupPolicy = "<a href="#jsk_all_policy"><var><b>config_dir</b></var>/jsk-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( - reggieCodebase, reggiePolicy, reggieClasspath, - "com.sun.jini.reggie.PersistentRegistrarImpl", - groupPersistenceDirectory, - new String[] { reggieConfig }, - true /* restart */) - }; -} -</pre> -</blockquote> - -<a name="activatable_jrmp_config"> -<h4>File <var><b>config_dir</b></var>/activatable-jrmp-reggie.config</h4> -</a> - -Use this configuration source file to run activatable Reggie using -JRMP. <p> - -<blockquote> -<pre> -import java.rmi.activation.ActivationID; -import net.jini.jrmp.JrmpExporter; - -com.sun.jini.reggie { - initialMemberGroups = new String[] { "<var><b>your.group</b></var>" }; - persistenceDirectory = "<var><b>config_dir</b></var>/reggie.log"; - serverExporter = new JrmpExporter((ActivationID) $data, 0); -} -</pre> -</blockquote> - -<a name="stop_activatable"> -<h3>Stopping Activatable Reggie</h3> -</a> - -To destroy the activation group running an activatable Reggie, run -using either JRMP or Jini ERI, run the following command. <p> - -<blockquote> -<pre> -java -Djava.security.policy=<a href="#jsk_all_policy"><var><b>config_dir</b></var>/jsk-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-reggie.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 Reggie's administrable interface, -or to remove the <var><b>config_dir</b></var>/reggie.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-reggie.config</h4> -</a> - -Use this configuration source file to destroy the activation group for -an activatable Reggie. <p> - -<blockquote> -<pre> -import com.sun.jini.start.ServiceDescriptor; -import com.sun.jini.start.SharedActivatableServiceDescriptor; - -com.sun.jini.start { - private static codebase = "http://<var><b>your_host</b></var>:<var><b>http_port</b></var>/group-dl.jar"; - private static policy = "<a href="#jsk_all_policy"><var><b>config_dir</b></var>/jsk-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 Reggie using Jini ERI</h3> -</a> - -To run a transient Reggie, which does not store any information -persistently or use the activation system to restart itself, using Jini -ERI for remote communication, run the following command. <p> - -<blockquote> -<pre> -java -Djava.security.policy=<a href="#jsk_all_policy"><var><b>config_dir</b></var>/jsk-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-reggie.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-reggie.config</h4> -</a> - -Use this configuration source file to start transient Reggie using -Jini ERI. <p> - -<blockquote> -<pre> -import com.sun.jini.start.NonActivatableServiceDescriptor; -import com.sun.jini.start.ServiceDescriptor; - -com.sun.jini.start { - private static codebase = "http://<var><b>your_host</b></var>:<var><b>http_port</b></var>/reggie-dl.jar" - + " http://<var><b>your_host</b></var>:<var><b>http_port</b></var>/jsk-dl.jar"; - private static policy = "<a href="#jsk_all_policy"><var><b>config_dir</b></var>/jsk-all.policy</a>"; - private static classpath = "<var><b>install_dir</b></var>/lib/reggie.jar"; - private static config = "<a href="#transient_config"><var><b>config_dir</b></var>/transient-reggie.config</a>"; - - static serviceDescriptors = new ServiceDescriptor[] { - new NonActivatableServiceDescriptor( - codebase, policy, classpath, - "com.sun.jini.reggie.TransientRegistrarImpl", - new String[] { config }) - }; -} -</pre> -</blockquote> - -<a name="transient_config"> -<h4>File <var><b>config_dir</b></var>/transient-reggie.config</h4> -</a> - -Use this configuration source file to run transient Reggie using Jini -ERI. <p> - -<blockquote> -<pre> -com.sun.jini.reggie { - initialMemberGroups = new String[] { "<var><b>your.group</b></var>" }; -} -</pre> -</blockquote> - -<a name="persistent"> -<h3>Starting Persistent Reggie using Jini ERI</h3> -</a> - -To run a persistent Reggie, which stores information persistently but does -not use the activation system to restart itself, using Jini ERI for -remote communication, run the following command. <p> - -<blockquote> -<pre> -java -Djava.security.policy=<a href="#jsk_all_policy"><var><b>config_dir</b></var>/jsk-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-reggie.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-reggie.config</h4> -</a> - -Use this configuration source file to start persistent Reggie using Jini -ERI. <p> - -<blockquote> -<pre> -import com.sun.jini.start.NonActivatableServiceDescriptor; -import com.sun.jini.start.ServiceDescriptor; - -com.sun.jini.start { - private static codebase = "http://<var><b>your_host</b></var>:<var><b>http_port</b></var>/reggie-dl.jar" - + " http://<var><b>your_host</b></var>:<var><b>http_port</b></var>/jsk-dl.jar"; - private static policy = "<a href="#jsk_all_policy"><var><b>config_dir</b></var>/jsk-all.policy</a>"; - private static classpath = "<var><b>install_dir</b></var>/lib/reggie.jar"; - private static config = "<a href="#persistent_config"><var><b>config_dir</b></var>/persistent-reggie.config</a>"; - - static serviceDescriptors = new ServiceDescriptor[] { - new NonActivatableServiceDescriptor( - codebase, policy, classpath, - "com.sun.jini.reggie.PersistentRegistrarImpl", - new String[] { config }) - }; -} -</pre> -</blockquote> - -<a name="persistent_config"> -<h4>File <var><b>config_dir</b></var>/persistent-reggie.config</h4> -</a> - -Use this configuration source file to run persistent Reggie using Jini -ERI. <p> - -<blockquote> -<pre> -import net.jini.id.UuidFactory; -import net.jini.jeri.BasicILFactory; -import net.jini.jeri.BasicJeriExporter; -import net.jini.jeri.tcp.TcpServerEndpoint; - -com.sun.jini.reggie { - initialMemberGroups = new String[] { "<var><b>your.group</b></var>" }; - persistenceDirectory = "<var><b>config_dir</b></var>/reggie.log"; - 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 to use for -listening for requests for this object. The -<var><b>obj_UUID_string</b></var> is the {@linkplain net.jini.id.Uuid -universally unique ID} for the exported object. These IDs have the form -<code>"01234567-89ab-cdef-0123-456789abcdef"</code>. <p> - -Remember to remove the <var><b>config_dir</b></var>/reggie.log directory -before restarting persistent Reggie if you want it to forget registrations -and settings made in previous invocations. - -<a name="activatable"> -<h3>Starting Activatable Reggie using Jini ERI</h3> -</a> - -To run an activatable Reggie, which stores information persistently and -uses the activation system to restart itself, using Jini ERI for remote -communication, run the following command. <p> - -<blockquote> -<pre> -java -Djava.security.policy=<a href="#jsk_all_policy"><var><b>config_dir</b></var>/jsk-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-reggie.config</a> -</pre> -</blockquote> <p> - -You should remove the <var><b>config_dir</b></var>/group.log directory -before running this command. Note that the activation system will -restart the activatable Reggie service as needed until Reggie is -shutdown. <p> - -Remember to remove the <var><b>config_dir</b></var>/reggie.log directory -before running this command if you want Reggie to forget registrations and -settings made in previous invocations. <p> - -This configuration uses the following additional files. - -<a name="start_activatable_config"> -<h4>File <var><b>config_dir</b></var>/start-activatable-reggie.config</h4> -</a> - -Use this configuration source file to start activatable Reggie using Jini -ERI. <p> - -<blockquote> -<pre> -import com.sun.jini.start.ServiceDescriptor; -import com.sun.jini.start.SharedActivatableServiceDescriptor; -import com.sun.jini.start.SharedActivationGroupDescriptor; - -com.sun.jini.start { - private static reggieCodebase = "http://<var><b>your_host</b></var>:<var><b>http_port</b></var>/reggie-dl.jar" - + " http://<var><b>your_host</b></var>:<var><b>http_port</b></var>/jsk-dl.jar"; - private static reggiePolicy = "<a href="#jsk_all_policy"><var><b>config_dir</b></var>/jsk-all.policy</a>"; - private static reggieClasspath = "<var><b>install_dir</b></var>/lib/reggie.jar"; - private static reggieConfig = "<a href="#activatable_config"><var><b>config_dir</b></var>/activatable-reggie.config</a>"; - - private static groupCodebase = "http://<var><b>your_host</b></var>:<var><b>http_port</b></var>/group-dl.jar"; - private static groupPolicy = "<a href="#jsk_all_policy"><var><b>config_dir</b></var>/jsk-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( - reggieCodebase, reggiePolicy, reggieClasspath, - "com.sun.jini.reggie.PersistentRegistrarImpl", - groupPersistenceDirectory, - new String[] { reggieConfig }, - true /* restart */) - }; -} -</pre> -</blockquote> - -<a name="activatable_config"> -<h4>File <var><b>config_dir</b></var>/activatable-reggie.config</h4> -</a> - -Use this configuration source file to run activatable Reggie using Jini -ERI. <p> - -<blockquote> -<pre> -com.sun.jini.reggie { - initialMemberGroups = new String[] { "<var><b>your.group</b></var>" }; - persistenceDirectory = "<var><b>config_dir</b></var>/reggie.log"; -} -</pre> -</blockquote> - -@see net.jini.core.lookup -@see net.jini.core.lookup.ServiceRegistrar - -</body> -</html> +<!-- + ! 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. + !--> + +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<html> +<head> + + +</head> +<body bgcolor="white"> + +Provides implementations of {@link net.jini.core.lookup.ServiceRegistrar}. +Two implementations are available for use with the {@link com.sun.jini.start} +package: + +<ul> + +<li> <code>com.sun.jini.reggie.PersistentRegistrarImpl</code> - a persistent + implementation which can be run either as activatable or non-activatable, + suitable for use with + {@link com.sun.jini.start.SharedActivatableServiceDescriptor} or + {@link com.sun.jini.start.NonActivatableServiceDescriptor} + +<li> <code>com.sun.jini.reggie.TransientRegistrarImpl</code> - a + non-activatable transient implementation, suitable for use with + {@link com.sun.jini.start.NonActivatableServiceDescriptor} + +</ul> <p> + +The name "Reggie" loosely refers to either implementation. The JAR file +<code>reggie.jar</code>, included in the <code>lib</code> subdirectory of the +Apache River release installation, contains the +classes for both Reggie service implementations. The <code>reggie-dl.jar</code> +and <code>jsk-dl.jar</code> files in the <code>lib-dl</code> subdirectory +contain the classes needed in the codebase for its downloaded proxies. +None of the JAR files include classes from <code>jsk-platform.jar</code>, +which are included by the service starter's <code>start.jar</code> JAR file, +and need to be included in the codebase of clients. <p> + +The main proxy of an instance of either of the implementations above implements +the <code>ServiceRegistrar</code>, {@link net.jini.admin.Administrable} and +{@link net.jini.id.ReferentUuid} interfaces. The admin proxy, obtainable by +calling the {@link net.jini.admin.Administrable#getAdmin getAdmin} method of +the main proxy, implements the {@link net.jini.lookup.DiscoveryAdmin}, {@link +net.jini.admin.JoinAdmin}, {@link com.sun.jini.admin.DestroyAdmin} and +<code>ReferentUuid</code> interfaces. <p> + +This document provides the following information about Reggie: +<ul> +<li> <a href="#configuration">Configuring Reggie</a> +<li> <a href="#access_control">Access Control Permission Targets</a> +<li> <a href="#logging">Loggers and Logging Levels</a> +<li> <a href="#system_properties">System Properties</a> +<li> <a href="#examples">Examples for Running Reggie</a> +</ul> <p> + +<a name="configuration"> +<h2>Configuring Reggie</h2> +</a> + +Both <code>TransientRegistrarImpl</code> and +<code>PersistentRegistrarImpl</code> service implementations obtain their +configurations 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 configuration entries supported by the two implementations are listed +below. <code>PersistentRegistrarImpl</code> supports all of the listed +entries. <code>TransientRegistrarImpl</code> supports all listed entries +except for the following persistence/activation-specific entries: +<ul> +<li> <a href="#activationIdPreparer"> + <code>activationIdPreparer</code></a> +<li> <a href="#activationSystemPreparer"> + <code>activationSystemPreparer</code></a> +<li> <a href="#persistenceDirectory"> + <code>persistenceDirectory</code></a> +<li> <a href="#persistenceSnapshotThreshold"> + <code>persistenceSnapshotThreshold</code></a> +<li> <a href="#persistenceSnapshotWeight"> + <code>persistenceSnapshotWeight</code></a> +<li> <a href="#recoveredListenerPreparer"> + <code>recoveredListenerPreparer</code></a> +<li> <a href="#recoveredLocatorPreparer"> + <code>recoveredLocatorPreparer</code></a> +</ul> <p> + +All configuration entries listed below have <code>com.sun.jini.reggie</code> as +their component. <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> + <code>new {@link net.jini.security.BasicProxyPreparer}()</code> + <tr valign="top"> <td>   <th scope="row" align="right"> + Description: <td> Specifies the proxy preparer to use for the {@link + java.rmi.activation.ActivationID} for this service, if this service is run + as activatable. This service does not invoke any methods on the prepared + <code>ActivationID</code> directly; however, it passes it to clients which + may call its {@link java.rmi.activation.ActivationID#activate activate} + method if they need to reactivate this service. This entry is obtained at + service start and restart if the service is running as activatable, and is + only supported by <code>PersistentRegistrarImpl</code>. +</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> + <code>new {@link net.jini.security.BasicProxyPreparer}()</code> + <tr valign="top"> <td>   <th scope="row" align="right"> + Description: <td> Specifies the proxy preparer to use for the {@link + java.rmi.activation.ActivationSystem} proxy. During shutdown, this service + calls the {@link java.rmi.activation.ActivationSystem#unregisterObject + unregisterObject} method on the <code>ActivationSystem</code> instance + returned from this preparer. This entry is obtained at service start and + restart if the service is running as activatable, and is only supported by + <code>PersistentRegistrarImpl</code>. +</table> + +<table summary="Describes the discoveryConstraints 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> + discoveryConstraints</code></font> + <tr valign="top"> <td>   <th scope="row" align="right"> + Type: <td> {@link net.jini.core.constraint.MethodConstraints} + <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> Specifies constraints to apply to the multicast request, + multicast announcement and unicast discovery protocols. Multicast request + constraints are derived by calling {@link + net.jini.core.constraint.MethodConstraints#getConstraints getConstraints} + on the obtained <code>MethodConstraints</code> instance with a + <code>Method</code> object for the {@link + com.sun.jini.discovery.DiscoveryConstraints#multicastRequest} method; + multicast announcement and unicast discovery constraints are similarly + obtained by passing <code>Method</code> objects for the {@link + com.sun.jini.discovery.DiscoveryConstraints#multicastAnnouncement} and + {@link com.sun.jini.discovery.DiscoveryConstraints#unicastDiscovery} + methods, respectively. A <code>null</code> value is interpreted as mapping + all methods to empty constraints. + <p> + Reggie supports use of the following constraint types to control + discovery behavior: + <ul> + <li> {@link com.sun.jini.discovery.DiscoveryProtocolVersion}: this + constraint can be used to control which version(s) of the multicast + request, multicast announcement, and unicast discovery protocols are + used. Reggie defaults to using version one of the discovery + protocols if this constraint is not specified and no other + constraints, besides the ones listed here, are specified. + <li> {@link com.sun.jini.discovery.MulticastMaxPacketSize}: this + constraint can be used to control the maximum size of multicast + announcement packets to send; it can also be used to specify the + size of the buffer used to receive incoming multicast request + packets. Reggie defaults to <code>512</code> bytes as the maximum + size for announcements sent if this constraint is not specified for + the {@link + com.sun.jini.discovery.DiscoveryConstraints#multicastAnnouncement} + method. Reggie defaults to <code>512</code> bytes as the size of + the buffer used to receive incoming multicast request packets if + this constraint is not specified for the {@link + com.sun.jini.discovery.DiscoveryConstraints#multicastRequest} + method.
[... 1604 lines stripped ...]
