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.

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 `org.apache.river.outrigger.TransientOutriggerImpl`; the second by `org.apache.river.outrigger.PersistentOutriggerImpl`. `TransientOutriggerImpl` can only be run as a non-activatable server, while `PersistentOutriggerImpl` can be run as an activatable or non-activatable server.

`PersistentOutriggerImpl` relies on a pluggable persistence layer, {@link org.apache.river.outrigger.Store}. Which implementation of the `Store` interface to use is controlled by the `store` configuration entry. Unlike some previous releases there is no default `Store` implementation.

This release includes one implementation of the `Store` interface. {@link org.apache.river.outrigger.snaplogstore.LogStore org.apache.river.outrigger.snaplogstore.LogStore}, also called Snaplogstore. Snaplogstore was introduced in the 2.1beta2 release. The original implementation of the `Store` interface, `org.apache.river.outrigger.logstore.LogStore`, or Logstore 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 `Store` implementation if you are using `PersistentOutriggerImpl` you will need to provide a value for the `store` configuration entry (as well as the `persistenceDirectory` configuration entry).

The storage formats used by Snaplogstore and Logstore are mutually incompatible.

The JAR file `outrigger.jar`, included in the `lib` subdirectory of the Apache River release installation, contains the classes for `TransientOutriggerImpl`. `outrigger.jar` also includes, via a JAR file manifest classpath directive, a reference to `jsk-lib.jar`. `jsk-lib.jar` must be in the same directory as `outrigger.jar` for Outrigger to operate properly.

`outrigger.jar` also includes, via a JAR file manifest classpath directive, a reference to `outrigger-snaplogstore.jar`. `outrigger-snaplogstore.jar` adds the classes necessary to run `PersistentOutriggerImpl` with the Snaplogstore implementation of `Store`, and must be in the same directory as `outrigger.jar` for `PersistentOutriggerImpl` to operate properly with snaplogstore.

The JAR files `outrigger-dl.jar` and `jsk-dl.jar` in the `lib-dl` directory contain the classes needed to instantiate Outrigger's proxy objects in a client. Outrigger's codebase should include both of these files.

None of the JAR files discussed in the previous paragraphs include classes from `jsk-platform.jar`. On the server side service starter, the service launcher utility, ensures that `jsk-platform.jar` is available to Outrigger. On the client it is the responsibility of the client to make `jsk-platform.jar` available. Typically this is done by including `jsk-platform.jar` in the client's classpath.

Outrigger's top level proxy implements {@link net.jini.admin.Administrable} in addition to `JavaSpace` and `JavaSpace05`. Outrigger's admin proxy can be obtained by calling {@link net.jini.admin.Administrable#getAdmin Administrable.getAdmin}. The admin proxy implements {@link net.jini.admin.JoinAdmin} and {@link org.apache.river.admin.DestroyAdmin}. The admin proxy will also implement {@link org.apache.river.outrigger.ConstrainableJavaSpaceAdmin} if the server has been set up with a Java(TM) remote method invocation (Java RMI) implementation that supports constraints, or {@link org.apache.river.outrigger.JavaSpaceAdmin} if constraints are not supported. However, `ConstrainableJavaSpaceAdmin` and `JavaSpaceAdmin` have been depreciated and should not be used.

This document provides the following information about Outrigger:

- Configuring Outrigger
- Blocking Queries
- Access Control Permission Targets
- Logging
- Examples for Running Outrigger

## Configuration Entries Consulted By Outrigger

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:

- `persistenceDirectory` (required if using `PersistentOutriggerImpl`)
- `store` (required if using `PersistentOutriggerImpl`)
- `initialLookupGroups`
- `initialLookupLocators`
- `initialLookupAttributes`

Each of these, except for `persistenceDirectory` and `store`, has reasonable defaults.

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 `serverExporter` 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.

Secure deployments will need to provide values for most if not all of these configuration entries:

- `serverExporter`
- `loginContext`
- `listenerPreparer`
- `recoveredListenerPreparer` (if using `PersistentOutriggerImpl`)
- `transactionManagerPreparer`
- `recoveredTransactionManagerPreparer` (if using `PersistentOutriggerImpl`)
- `activationIdPreparer` (if using activation)
- `activationSystemPreparer` (if using activation)
- `lookupLocatorPreparer`
- `recoveredLookupLocatorPreparer` (if using `PersistentOutriggerImpl`)

plus the following configuration entries from {@link net.jini.discovery.LookupDiscovery} :

- `registrarPreparer`
- `discoveryConstraints`

{@link net.jini.discovery.LookupLocatorDiscovery} :

- `registrarPreparer`

and {@link net.jini.lookup.JoinManager} :

- `registrarPreparer`
- `registrationPreparer`
- `serviceLeasePreparer`

in addition to providing appropriate security policy files, key stores, login configuration files, etc.

The Outrigger service implementation obtains its configuration by calling {@link net.jini.config.ConfigurationProvider#getInstance(String[], ClassLoader) ConfigurationProvider.getInstance} with the specified configOptions and the class loader for the implementation class.

The implementation supports the following configuration entries, with component `org.apache.river.outrigger`:

• | `activationIdPreparer`
--- | ---
| Type: | {@link net.jini.security.ProxyPreparer}
| Default: | An instance of {@link net.jini.security.BasicProxyPreparer} that does nothing
| Description: | 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.

• | `activationSystemPreparer`
--- | ---
| Type: | {@link net.jini.security.ProxyPreparer}
| Default: | An instance of {@link net.jini.security.BasicProxyPreparer} that does nothing
| Description: | 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.

• | `contentsLeasePeriodPolicy`
--- | ---
| Type: | {@link org.apache.river.landlord.LeasePeriodPolicy}
| Default: | A `new` {@link org.apache.river.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}
| Description: | 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.

• | `discoveryManager`
--- | ---
| Type: | {@link net.jini.discovery.DiscoveryManagement}
| Default: |
    new {@link net.jini.discovery.LookupDiscoveryManager}(
        {@link net.jini.discovery.DiscoveryGroupManagement#NO_GROUPS},
        null,  // locators
        null,  // listener
        this)  // config
| Description: | The object Outrigger should use to find lookups to register with. In addition to `DiscoveryManagement` 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 `initialLookupGroups` and `initialLookupLocators` 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 `LookupDiscoveryManager` documentation} to see what configuration entries it reads. Obtained at service start and restart.

• | `entryLeasePeriodPolicy`
--- | ---
| Type: | {@link org.apache.river.landlord.LeasePeriodPolicy}
| Default: | A `new` {@link org.apache.river.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}
| Description: | Policy used to determine the length of initial grants and renewals of the leases on entries. Obtained at service start and restart.

• | `eventLeasePolicy`
--- | ---
| Type: | {@link org.apache.river.landlord.LeasePeriodPolicy}
| Default: | A `new` {@link org.apache.river.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}
| Description: | Policy used to determine the length of initial grants and renewals of the leases on event registrations. Obtained at service start and restart.

• | `initialLookupAttributes`
--- | ---
| Type: | {@link net.jini.core.entry.Entry Entry[]}
| Default: | `new Entry[0]`
| Description: | This configuration entry will be read the first time 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.

• | `initialLookupGroups`
--- | ---
| Type: | {@link java.lang.String String[]}
| Default: | `new String[]{""}` (aka the "public" group)
| Description: | This entry will be read the first time 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.

• | `initialLookupLocators`
--- | ---
| Type: | {@link net.jini.core.discovery.LookupLocator LookupLocator[]}
| Default: | `new LookupLocator[0]`
| Description: | This entry will be read the first time 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.

• | `iteratorBatchSize`
--- | ---
| Type: | `int`
| Default: | `100`
| Description: | Fetch ahead limit for {@link net.jini.space.JavaSpace05#contents JavaSpace05.contents} and {@link net.jini.space.MatchSet#next MatchSet.next} calls. A given `contents` or `next` invocation will never fetch more than this many entries. Must be a positive `int` value. Obtained at service start and restart.

• | `listenerPreparer`
--- | ---
| Type: | {@link net.jini.security.ProxyPreparer}
| Default: | An instance of {@link net.jini.security.BasicProxyPreparer} that does nothing
| Description: | 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. 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 `recoveredListenerPreparer`. Obtained at service start and restart.

• | `loginContext`
--- | ---
| Type: | {@link javax.security.auth.login.LoginContext}
| Default: | `null`
| Description: | If non-`null`, JAAS login context for performing a JAAS login, after which the service is run as the resulting subject. If `null`, no JAAS login is performed. Obtained at service start and restart.

• | `lookupLocatorPreparer`
--- | ---
| Type: | {@link net.jini.security.ProxyPreparer}
| Default: | An instance of {@link net.jini.security.BasicProxyPreparer} that does nothing
| Description: | 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}, `equals`, and `hashCode` methods of the proxy being prepared. The object returned by this preparer must be equal (in the sense of the `equals` method) to the object passed in. If a `LookupLocator` instance passed in via the methods of `JoinAdmin` is persisted, the version returned by this preparer will be the one that is persisted. The `LookupLocator` instances obtained from `initialLookupLocators` will not be prepared by this preparer. Obtained at service start and restart.

• | `maxOps`
--- | ---
| Type: | `int`
| Default: | `1000`
| Description: | Maximum number of persistent store directives that can be written to a log. Only consulted if {@link org.apache.river.outrigger.snaplogstore.LogStore org.apache.river.outrigger.snaplogstore.LogStore} is being used for the store 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 `int` value. Obtained at service start and restart.

• | `maxServerQueryTimeout`
--- | ---
| Type: | `long`
| Default: | {@link java.lang.Long#MAX_VALUE Long.MAX_VALUE}
| Description: | Controls the default value of the maximum server query timeout for proxies created by this server. Must be a positive long value. See Blocking Queries 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.

• | `maxUnexportDelay`
--- | ---
| Type: | `long`
| Default: | `120000` (2 minutes)
| Description: | 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 `Exporter` used to export the server (see `serverExporter`). The initial `unexport` call passes `false` for the value of the `force` parameter. This is done in order to allow the destroy call to return cleanly to the client. If the initial `unexport` call fails, Outrigger will retry calling `unexport(false)` for up to `maxUnexportDelay` milliseconds before giving up and calling `unexport(true)`. `maxUnexportDelay` must be a non-negative long value. If `maxUnexportDelay` is zero then the very first call to `unexport` passes `true` for the value of the `force` parameter, no nice unexport attempt is made. Obtained at service start and restart. Note, the delay between attempted `unexport` calls is controlled by the `unexportRetryDelay` configuration entry.

• | `notificationsExecutorService`
--- | ---
| Type: | {@link java.util.concurrent/ExecutorService ExecutorService}
| Default: | `new` {@link java.util.concurrent/ThreadPoolExecutor ThreadPoolExecutor}( 10, 10, 15, TimeUnit.SECONDS, new LinkedBlockingQueue(), new NamedThreadFactory("OutriggerServerImpl Notifier", false) )
| Description: | The pool of threads used to make event delivery attempts. The {@link java.util.concurrent/ExecutorService#shutdown shutdown} method of this object will be called when the service is destroyed. Obtained at service start and restart.

• | `persistenceDirectory`
--- | ---
| Type: | {@link java.lang.String}
| Default: | none
| Description: | If the {@link org.apache.river.outrigger.snaplogstore.LogStore org.apache.river.outrigger.snaplogstore.LogStore} implementations of {@link org.apache.river.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.

• | `reapingInterval`
--- | ---
| Type: | `long`
| Default: | `60000`
| Description: | How often, in milliseconds, should Outrigger go through its internal tables and remove unused entries, templates, contents queries, etc. Must be a positive `long` value. See also the `reapingPriority` configuration entry. Obtained at service start and restart.

• | `reapingPriority`
--- | ---
| Type: | `int`
| Default: | {@link java.lang.Thread#NORM_PRIORITY Thread.NORM_PRIORITY}
| Description: | 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 `reapingInterval` configuration entry. Obtained at service start and restart.

• | `recoveredListenerPreparer`
--- | ---
| Type: | {@link net.jini.security.ProxyPreparer}
| Default: | An instance of {@link net.jini.security.BasicProxyPreparer} that does nothing
| Description: | 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 `listenerPreparer` configuration entry. Obtained at persistent service start and restart. 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.

• | `recoveredLookupLocatorPreparer`
--- | ---
| Type: | {@link net.jini.security.ProxyPreparer}
| Default: | An instance of {@link net.jini.security.BasicProxyPreparer} that does nothing
| Description: | Proxy preparer to use for instances of {@link net.jini.core.discovery.LookupLocator} that have been persisted and recovered. This will include `LookupLocator`s passed into various {@link net.jini.admin.JoinAdmin} methods as well as the initial set of locators obtained from the `initialLookupLocators` configuration entry. The preparer should expect Outrigger to call the {@link net.jini.core.discovery.LookupLocator#getRegistrar LookupLocator.getRegistrar}, `equals`, and `hashCode` 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 `equals` method) to the object passed in. Only read if Outrigger is being run as a persistent service. See also the `lookupLocatorPreparer` configuration entry. Obtained at persistent service start and restart. 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.

• | `recoveredTransactionManagerPreparer`
--- | ---
| Type: | {@link net.jini.security.ProxyPreparer}
| Default: | An instance of {@link net.jini.security.BasicProxyPreparer} that does nothing
| Description: | 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}, `equals`, and `hashCode` methods on the returned proxy. In a given VM, the preparer may be asked to prepare proxies for the same `TransactionManager` 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 `equals` method) to the object passed in. See also the `transactionManagerPreparer` configuration entry. Obtained at persistent service start and restart. 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.

• | `serverExporter`
--- | ---
| Type: | {@link net.jini.export.Exporter}
| Default: | A new {@link net.jini.jeri.BasicJeriExporter} with a {@link net.jini.jeri.tcp.TcpServerEndpoint} created on a random port, a {@link net.jini.jeri.BasicILFactory}, distributed garbage collection turned off, keep alive on. 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}
| Description: | The exporter used to export the server. The resulting proxy is used as the inner proxy for all of Outrigger's proxies. If the server is activatable, the service's `ActivationID` will be passed as the `data` argument, otherwise the `data` argument will be `null`. A new exporter is obtained every time Outrigger needs to export itself, currently at service start and restart.

• | `store`
--- | ---
| Type: | {@link org.apache.river.outrigger.Store}
| Default: | none
| Description: | 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. A {@link org.apache.river.outrigger.snaplogstore.LogStore org.apache.river.outrigger.snaplogstore.LogStore} instance can be created like this: `new` {@link org.apache.river.outrigger.snaplogstore.LogStore#LogStore org.apache.river.outrigger.snaplogstore.LogStore(this)} `// `this' == the configuration object`

• | `takeMultipleLimit`
--- | ---
| Type: | `int`
| Default: | `100`
| Description: | Maximum number of entries a {@link net.jini.space.JavaSpace05#take JavaSpace05.take} call may return. Must be a positive `int` value. Obtained at service start and restart.

• | `transactionManagerPreparer`
--- | ---
| Type: | {@link net.jini.security.ProxyPreparer}
| Default: | An instance of {@link net.jini.security.BasicProxyPreparer} that does nothing
| Description: | 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}, `equals`, and `hashCode` methods on the returned proxy. The preparer may be asked to prepare proxies for the same `TransactionManager` multiple times. Outrigger attempts to minimize the number of times the `TransactionManager` 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 `TransactionManager` 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 `equals` method) to the object passed in. Only `TransactionManager` proxies that have been returned by this preparer will be persisted. If a `TransactionManager` proxy is recovered it will be re-prepared by the `recoveredTransactionManagerPreparer`. Obtained at service start and restart.

• | `txnMonitorExecutorService`
--- | ---
| Type: | {@link java.util.concurrent/ExecutorService ExecutorService}
| Default: | `new` {@link java.util.concurrent/ThreadPoolExecutor ThreadPoolExecutor}( 10, 10, 15, TimeUnit.SECONDS, new LinkedBlockingQueue(), new NamedThreadFactory("OutriggerServerImpl TxnMonitor", false) )
| Description: | The pool of threads used to check the status of transactions that have been prepared or have locked contended resources. The {@link java.util.concurrent/ExecutorService#shutdown shutdown} method of this object will be called when the service is destroyed. Obtained at service start and restart.

• | `unexportRetryDelay`
--- | ---
| Type: | `long`
| Default: | `1000` (1 second)
| Description: | When destroying an Outrigger server how long to wait between unexport attempts. `unexportRetryDelay` must be a positive long value. When destroying itself Outrigger will sleep for `unexportRetryDelay` milliseconds between {@link net.jini.export.Exporter#unexport Exporter.unexport} calls. Obtained at service start and restart. See `maxUnexportDelay` for additional details.

### Other Configuration Entries

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 `discoveryManager` configuration entry, and `null` for the {@link net.jini.lease.LeaseRenewalManager}. The {@linkplain net.jini.lookup.JoinManager `JoinManager` documentation} should be consulted to see what configuration entries `JoinManager` reads.

## Blocking Queries

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 maximum server query timeout 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.

When Outrigger's proxy handles a query with a non-zero client timeout, it passes a non-zero server timeout 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 maximum server query timeout 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.

When Outrigger creates a proxy it provides a default value for the maximum server query timeout. This default is controlled by the `maxServerQueryTimeout` configuration entry. This value can be overridden in the client by setting the `org.apache.river.outrigger.maxServerQueryTimeout` property to a positive `long` value.

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.

## Access Control Permission Targets

The following table lists the remote methods on Outrigger's proxy objects and the associated target names for enforcing access control using {@link org.apache.river.outrigger.OutriggerPermission}:

Proxy Method | Target Name
--- | ---
{@link net.jini.space.JavaSpace#write JavaSpace.write} | `write`
{@link net.jini.space.JavaSpace#take JavaSpace.take} | `take`
{@link net.jini.space.JavaSpace#read JavaSpace.read} | `read`
{@link net.jini.space.JavaSpace#takeIfExists JavaSpace.takeIfExists} | `takeIfExists`
{@link net.jini.space.JavaSpace#readIfExists JavaSpace.readIfExists} | `readIfExists`
{@link net.jini.space.JavaSpace#notify JavaSpace.notify} | `notify`
{@link net.jini.space.JavaSpace05#write JavaSpace05.write} | `write`
{@link net.jini.space.JavaSpace05#take JavaSpace05.take} | `take`
{@link net.jini.space.JavaSpace05#contents JavaSpace05.contents} | `contents`
{@link net.jini.space.JavaSpace05#registerForAvailabilityEvent JavaSpace05.registerForAvailabilityEvent} | `registerForAvailabilityEvent`
{@link net.jini.space.MatchSet#next MatchSet.next} | `nextBatch`
{@link net.jini.core.transaction.server.TransactionParticipant#prepare TransactionParticipant.prepare} | `prepare`
{@link net.jini.core.transaction.server.TransactionParticipant#commit TransactionParticipant.commit} | `commit`
{@link net.jini.core.transaction.server.TransactionParticipant#abort TransactionParticipant.abort} | `abort`
{@link net.jini.core.transaction.server.TransactionParticipant#prepareAndCommit TransactionParticipant.prepareAndCommit} | `prepareAndCommit`
{@link net.jini.core.lease.Lease#renew Lease.renew} | `renew`
{@link net.jini.core.lease.Lease#cancel Lease.cancel} | `cancel`
{@link net.jini.core.lease.LeaseMap#renewAll LeaseMap.renewAll} | `renewAll`
{@link net.jini.core.lease.LeaseMap#cancelAll LeaseMap.cancelAll} | `cancelAll`
{@link net.jini.admin.Administrable#getAdmin Administrable.getAdmin} | `getAdmin`
{@link net.jini.admin.JoinAdmin#getLookupAttributes JoinAdmin.getLookupAttributes} | `getLookupAttributes`
{@link net.jini.admin.JoinAdmin#addLookupAttributes JoinAdmin.addLookupAttributes} | `addLookupAttributes`
{@link net.jini.admin.JoinAdmin#modifyLookupAttributes JoinAdmin.modifyLookupAttributes} | `modifyLookupAttributes`
{@link net.jini.admin.JoinAdmin#getLookupGroups JoinAdmin.getLookupGroups} | `getLookupGroups`
{@link net.jini.admin.JoinAdmin#addLookupGroups JoinAdmin.addLookupGroups} | `addLookupGroups`
{@link net.jini.admin.JoinAdmin#removeLookupGroups JoinAdmin.removeLookupGroups} | `removeLookupGroups`
{@link net.jini.admin.JoinAdmin#setLookupGroups JoinAdmin.setLookupGroups} | `setLookupGroups`
{@link net.jini.admin.JoinAdmin#getLookupLocators JoinAdmin.getLookupLocators} | `getLookupLocators`
{@link net.jini.admin.JoinAdmin#addLookupLocators JoinAdmin.addLookupLocators} | `addLookupLocators`
{@link net.jini.admin.JoinAdmin#removeLookupLocators JoinAdmin.removeLookupLocators} | `removeLookupLocators`
{@link net.jini.admin.JoinAdmin#setLookupLocators JoinAdmin.setLookupLocators} | `setLookupLocators`
{@link org.apache.river.admin.DestroyAdmin#destroy DestroyAdmin.destroy} | `destroy`
{@link net.jini.security.proxytrust.ProxyTrust#getProxyVerifier ProxyTrust.getProxyVerifier} | `getProxyVerifier`
{@link org.apache.river.start.ServiceProxyAccessor#getServiceProxy ServiceProxyAccessor.getServiceProxy} | `getServiceProxy`
{@link org.apache.river.outrigger.JavaSpaceAdmin#space JavaSpaceAdmin.space} | `space`
{@link org.apache.river.outrigger.JavaSpaceAdmin#contents( net.jini.core.entry.Entry, net.jini.core.transaction.Transaction) JavaSpaceAdmin.contents(Entry, Transaction)}, {@link org.apache.river.outrigger.JavaSpaceAdmin#contents( net.jini.core.entry.Entry, net.jini.core.transaction.Transaction, int) JavaSpaceAdmin.contents(Entry, Transaction, int)}, {@link org.apache.river.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)} | `contents`
{@link org.apache.river.outrigger.AdminIterator#next AdminIterator.next} | `next`
{@link org.apache.river.outrigger.AdminIterator#delete AdminIterator.delete} | `delete`
{@link org.apache.river.outrigger.AdminIterator#close AdminIterator.close} | `close`

## Logging

The Outrigger service implementation uses a number of different {@link java.util.logging.Logger} objects:

Logger Name | Description
`org.apache.river.outrigger.lifecycle` | Starting/restarting/destroying the service
`org.apache.river.outrigger.operations` | Top level space operations
`org.apache.river.outrigger.transactions` | Transactions
`org.apache.river.outrigger.leases` | Leases and leasing
`org.apache.river.outrigger.iterator` | Iterators
`org.apache.river.outrigger.join` | Outrigger's join state
`org.apache.river.outrigger.entryMatching` | Entry matching
`org.apache.river.outrigger.event` | Events and event delivery
`org.apache.river.outrigger.store` | Persistence
`org.apache.river.outrigger.proxy` | The operation of Outrigger's proxies

Each of these loggers logs information at the following logging levels:

Level | Description
--- | ---
SEVERE | Problems which prevent startup or cause shutdown of Outrigger, or which generally prevent Outrigger from continuing with its processing
WARNING | 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
INFO | 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
CONFIG | Trace information related to the configuration and administration of Outrigger
FAILED | 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
FINE | Information related to tracing Outrigger at a high level, which might provide a logical view of the operations being performed.
FINER | 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.
FINEST | Information related to Outrigger's internal state that might be useful in debugging or testing

## Examples for Running Outrigger

This section provides examples of running Outrigger in various configurations.

- Assumptions for running the examples
- JRMP configurations
  - Transient
  - Activatable
- Jini ERI configurations
  - Transient
  - Persistent
  - Activatable
- Stopping activatable configurations

No example is included for a non-activatable, persistent JRMP configuration because this is unlikely to have the expected result.

### Assumptions for Running the Examples

The examples below make the following assumptions:

- The Java(TM) 2 Platform, Standard Edition, (J2SE(TM)) has been installed, and its commands are available in the current path
- The Apache River release has been installed in the install_dir directory
- The example configuration and policy files described below are available in the config_dir directory
- The local lookup group name is your.group
- The HTTP server for download JAR files is running on the local host and is available on port http_port. This HTTP server is serving files located in the install_dir/lib-dl directory. You can use the {@link org.apache.river.tool.ClassServer} class for this purpose.
- The examples are being run on UNIX platforms
- The examples are being run on a secure network where access control and authentication are not needed. See the hello example for some client and service configurations that enforce security.
- For activatable services, an activation system is running on your machine. You can use the {@link org.apache.river.phoenix} implementation for this purpose.

Throughout the examples, items in bold need to be customized for your local environment.

### Starting Transient Outrigger using JRMP

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 configuration that uses Jini ERI) 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.

>     java -Djava.security.policy=config_dir/outrigger-all.policy \
>          -jar install_dir/lib/start.jar \
>          config_dir/start-transient-jrmp-outrigger.config

This configuration uses the following files.

#### File config_dir/outrigger-all.policy

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 hello example for some client and service configurations that enforce security.

>     grant codebase "file:install_dir/lib/jsk-platform.jar" {
>         permission java.security.AllPermission;
>     };

>     grant codebase "file:install_dir/lib/jsk-lib.jar" {
>         permission java.security.AllPermission;
>     };

>     grant codebase "file:install_dir/lib/start.jar" {
>         permission java.security.AllPermission;
>     };

>     grant codebase "file:install_dir/lib/destroy.jar" {
>         permission java.security.AllPermission;
>     };

>     grant codebase "file:install_dir/lib/sharedvm.jar" {
>         permission java.security.AllPermission;
>     };

>     grant codebase "file:install_dir/lib/group.jar" {
>         permission java.security.AllPermission;
>     };

>     grant codebase "file:install_dir/lib/outrigger.jar" {
>         permission java.security.AllPermission;
>     };

>     grant codebase "file:install_dir/lib/outrigger-snaplogstore.jar" {
>         permission java.security.AllPermission;
>     };

>     grant codebase "file:install_dir/lib/phoenix-group.jar" {
>         permission java.security.AllPermission;
>     };

>     grant codebase "file:install_dir/lib/phoenix-init.jar" {
>         permission java.security.AllPermission;
>     };

#### File config_dir/start-transient-jrmp-outrigger.config

Use this configuration source file to start transient Outrigger using JRMP.

>     import org.apache.river.start.NonActivatableServiceDescriptor;
>     import org.apache.river.start.ServiceDescriptor;
>     import org.apache.river.config.ConfigUtil;

>     org.apache.river.start {
>         private static basecodebase = "http://" + ConfigUtil.getHostName() +
>             ":http_port/";
>         private static codebase = basecodebase + "outrigger-dl.jar " +
>              basecodebase + "jsk-dl.jar";

>         private static policy = "config_dir/outrigger-all.policy";
>         private static classpath = "install_dir/lib/outrigger.jar";
>         private static config = "config_dir/transient-jrmp-outrigger.config";

>         static serviceDescriptors = new ServiceDescriptor[] {
>     	new NonActivatableServiceDescriptor(
>     	    codebase, policy, classpath,
>     	    "org.apache.river.outrigger.TransientOutriggerImpl",
>     	    new String[] { config })
>         };
>     }

#### File config_dir/transient-jrmp-outrigger.config

Use this configuration source file to run transient Outrigger using JRMP.

>     import net.jini.jrmp.JrmpExporter;

>     org.apache.river.outrigger {
>         initialLookupGroups = new String[] { "your.group" };
>         serverExporter = new JrmpExporter();
>     }

### Starting Activatable Outrigger using JRMP

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).

If you are not familiar with Java RMI activation you should read this note on activation first. For day to day development, or if you are just starting with Jini technology you may be better served with either the transient JRMP or transient Jini ERI configurations. If you require persistence you may also want to try the persistent Jini ERI configuration.

>     java -Djava.security.policy=config_dir/outrigger-all.policy \
>          -jar install_dir/lib/start.jar \
>          config_dir/start-activatable-jrmp-outrigger.config

This command will create a new activation group and create a new 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.

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 `persistenceDirectory` configuration entry in `activatable-jrmp-outrigger.config` and either :

- Change the value of the `groupPersistenceDirectory` configuration entry in start-activatable-jrmp-outrigger.config, which will give you two spaces in two activation groups.
- Remove the `SharedActivationGroupDescriptor` instance from the `serviceDescriptors` configuration entry in start-activatable-jrmp-outrigger.config, which will give you two spaces in one activation group.

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 destroy the original activation group. If you destroy the entire activation group you can skip using Outrigger's administrable interface to destroy the Outrigger service instance, and instead remove config_dir/outrigger.log after destroying the activation group.

This configuration uses the following additional files.

#### File config_dir/start-activatable-jrmp-outrigger.config

Use this configuration source file to start activatable Outrigger using JRMP.

>     import org.apache.river.start.ServiceDescriptor;
>     import org.apache.river.start.SharedActivatableServiceDescriptor;
>     import org.apache.river.start.SharedActivationGroupDescriptor;
>     import org.apache.river.config.ConfigUtil;

>     org.apache.river.start {
>         private static basecodebase = "http://" + ConfigUtil.getHostName() +
>             ":http_port/";
>         private static outriggerCodebase = basecodebase + "outrigger-dl.jar " +
>              basecodebase + "jsk-dl.jar";

>         private static outriggerPolicy = "config_dir/outrigger-all.policy";
>         private static outriggerClasspath = "install_dir/lib/outrigger.jar";
>         private static outriggerConfig = "config_dir/activatable-jrmp-outrigger.config";

>         private static groupPolicy = "config_dir/outrigger-all.policy";
>         private static groupClasspath = "install_dir/lib/sharedvm.jar";
>         private static groupPersistenceDirectory = "config_dir/group.log";

>         static serviceDescriptors = new ServiceDescriptor[] {
>     	new SharedActivationGroupDescriptor(
>     	    groupPolicy, groupClasspath, groupPersistenceDirectory,
>     	    null /* serverCommand */,
>     	    null /* serverOptions */,
>     	    null /* serverProperties */),
>     	new SharedActivatableServiceDescriptor(
>     	    outriggerCodebase, outriggerPolicy, outriggerClasspath,
>     	    "org.apache.river.outrigger.PersistentOutriggerImpl",
>     	    groupPersistenceDirectory,
>     	    new String[] { outriggerConfig },
>     	    true /* restart */)
>         };
>     }

#### File config_dir/activatable-jrmp-outrigger.config

Use this configuration source file to run activatable Outrigger using JRMP and the Snaplogstore implementation of `Store`.

>     import org.apache.river.outrigger.snaplogstore.LogStore;
>     import java.rmi.activation.ActivationID;
>     import net.jini.jrmp.JrmpExporter;

>     org.apache.river.outrigger {
>         initialLookupGroups = new String[] { "your.group" };
>         persistenceDirectory = "config_dir/outrigger.log";
>         store = new LogStore(this);
>         serverExporter = new JrmpExporter((ActivationID) $data, 0);
>     }

### Stopping Activatable Outrigger

To destroy the activation group running an activatable Outrigger, running under either JRMP or Jini ERI, run the following command.

>     java -Djava.security.policy=config_dir/outrigger-all.policy \
>          -jar install_dir/lib/destroy.jar \
>          config_dir/stop-activatable-outrigger.config

Running this command will remove the config_dir/group.log directory.

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 config_dir/outrigger.log directory after destroying the activation group.

This command uses the following additional file.

#### File config_dir/stop-activatable-outrigger.config

Use this configuration source file to destroy the activation group for an activatable Outrigger.

>     import org.apache.river.start.ServiceDescriptor;
>     import org.apache.river.start.SharedActivatableServiceDescriptor;
>     import org.apache.river.config.ConfigUtil;

>     org.apache.river.start {
>         private static codebase = "http://" + ConfigUtil.getHostName() +
>             ":http_port/group-dl.jar";
>         private static policy = "config_dir/outrigger-all.policy";
>         private static classpath = "install_dir/lib/group.jar";
>         private static persistenceDirectory = "config_dir/group.log";

>         static serviceDestructors = new ServiceDescriptor[] {
>     	new SharedActivatableServiceDescriptor(
>     	    codebase, policy, classpath,
>     	    "org.apache.river.start.SharedGroupImpl",
>     	    persistenceDirectory,
>     	    null /* config */,
>     	    false /* restart */)
>         };
>     }

### Starting Transient Outrigger using Jini ERI

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 configuration that uses JRMP) 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.

>     java -Djava.security.policy=config_dir/outrigger-all.policy \
>          -jar install_dir/lib/start.jar \
>          config_dir/start-transient-outrigger.config

This configuration uses the following additional files.

#### File config_dir/start-transient-outrigger.config

Use this configuration source file to start transient Outrigger using Jini ERI.

>     import org.apache.river.start.NonActivatableServiceDescriptor;
>     import org.apache.river.start.ServiceDescriptor;
>     import org.apache.river.config.ConfigUtil;

>     org.apache.river.start {
>         private static basecodebase = "http://" + ConfigUtil.getHostName() +
>             ":http_port/";
>         private static codebase = basecodebase + "outrigger-dl.jar " +
>              basecodebase + "jsk-dl.jar";

>         private static policy = "config_dir/outrigger-all.policy";
>         private static classpath = "install_dir/lib/outrigger.jar";
>         private static config = "config_dir/transient-outrigger.config";

>         static serviceDescriptors = new ServiceDescriptor[] {
>     	new NonActivatableServiceDescriptor(
>     	    codebase, policy, classpath,
>     	    "org.apache.river.outrigger.TransientOutriggerImpl",
>     	    new String[] { config })
>         };
>     }

#### File config_dir/transient-outrigger.config

Use this configuration source file to run transient Outrigger using Jini ERI.

>     org.apache.river.outrigger {
>         initialLookupGroups = new String[] { "your.group" };
>     }

### Starting Persistent Outrigger using Jini ERI

This configuration starts a persistent, but non-activatable Outrigger server that will use Jini ERI to communicate between proxies and the server. Like the transient Jini ERI and transient JRMP 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 activatable Jini ERI and activatable JRMP 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.

>     java -Djava.security.policy=config_dir/outrigger-all.policy \
>          -jar install_dir/lib/start.jar \
>          config_dir/start-persistent-outrigger.config

This configuration uses the following additional files.

#### File config_dir/start-persistent-outrigger.config

Use this configuration source file to start persistent Outrigger using Jini ERI.

>     import org.apache.river.start.NonActivatableServiceDescriptor;
>     import org.apache.river.start.ServiceDescriptor;
>     import org.apache.river.config.ConfigUtil;

>     org.apache.river.start {
>         private static basecodebase = "http://" + ConfigUtil.getHostName() +
>             ":http_port/";
>         private static codebase = basecodebase + "outrigger-dl.jar " +
>              basecodebase + "jsk-dl.jar";

>         private static policy = "config_dir/outrigger-all.policy";
>         private static classpath = "install_dir/lib/outrigger.jar";
>         private static config = "config_dir/persistent-outrigger.config";

>         static serviceDescriptors = new ServiceDescriptor[] {
>     	new NonActivatableServiceDescriptor(
>     	    codebase, policy, classpath,
>     	    "org.apache.river.outrigger.PersistentOutriggerImpl",
>     	    new String[] { config })
>         };
>     }

#### File config_dir/persistent-outrigger.config

Use this configuration source file to run persistent Outrigger using Jini ERI and the Snaplogstore implementation of `Store`.

>     import org.apache.river.outrigger.snaplogstore.LogStore;
>     import net.jini.id.UuidFactory;
>     import net.jini.jeri.BasicILFactory;
>     import net.jini.jeri.BasicJeriExporter;
>     import net.jini.jeri.tcp.TcpServerEndpoint;

>     org.apache.river.outrigger {
>         initialLookupGroups = new String[] { "your.group" };
>         persistenceDirectory = "config_dir/outrigger.log";
>         store = new LogStore(this);
>         serverExporter = new BasicJeriExporter(
>     	TcpServerEndpoint.getInstance(obj_port),
>     	new BasicILFactory(),
>     	false,
>     	true,
>     	UuidFactory.create("obj_UUID_string"));
>     }

The obj_port is the fixed TCP port that the server will use to listen for incoming remote calls. The obj_UUID_string 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 `"01234567-89ab-cdef-0123-456789abcdef"`. By keeping the UUID and port constant you will ensure that old references to the space will still function after a re-start.

Remember to remove the config_dir/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 `persistenceDirectory` configuration entry.

#### Persistent Outrigger using JRMP

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 new, 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.

### Starting Activatable Outrigger using Jini ERI

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).

If you are not familiar with Java RMI activation you should read this note on activation first. For day to day development, or if you are just starting with Jini technology you may be better served with either the transient JRMP or transient Jini ERI configurations. If you require persistence you may also want to try the persistent Jini ERI configuration.

>     java -Djava.security.policy=config_dir/outrigger-all.policy \
>          -jar install_dir/lib/start.jar \
>          config_dir/start-activatable-outrigger.config

This command will create a new activation group and create a new 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.

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 `persistenceDirectory` configuration entry in `activatable-outrigger.config` and either :

- Change the value of the `groupPersistenceDirectory` configuration entry in start-activatable-outrigger.config, which will give you two spaces in two activation groups.
- Remove the `SharedActivationGroupDescriptor` instance from the `serviceDescriptors` configuration entry in start-activatable-outrigger.config, which will give you two spaces in one activation group.

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 destroy the original activation group. If you destroy the entire activation group you can skip using Outrigger's administrable interface to destroy the Outrigger service instance, and instead remove config_dir/outrigger.log after destroying the activation group.

This configuration uses the following additional files.

#### File config_dir/start-activatable-outrigger.config

Use this configuration source file to start activatable Outrigger using Jini ERI.

>     import org.apache.river.start.ServiceDescriptor;
>     import org.apache.river.start.SharedActivatableServiceDescriptor;
>     import org.apache.river.start.SharedActivationGroupDescriptor;
>     import org.apache.river.config.ConfigUtil;

>     org.apache.river.start {
>         private static basecodebase = "http://" + ConfigUtil.getHostName() +
>             ":http_port/";
>         private static outriggerCodebase = basecodebase + "outrigger-dl.jar " +
>              basecodebase + "jsk-dl.jar";

>         private static outriggerPolicy = "config_dir/outrigger-all.policy";
>         private static outriggerClasspath = "install_dir/lib/outrigger.jar";
>         private static outriggerConfig = "config_dir/activatable-outrigger.config";

>         private static groupPolicy = "config_dir/outrigger-all.policy";
>         private static groupClasspath = "install_dir/lib/sharedvm.jar";
>         private static groupPersistenceDirectory = "config_dir/group.log";

>         static serviceDescriptors = new ServiceDescriptor[] {
>     	new SharedActivationGroupDescriptor(
>     	    groupPolicy, groupClasspath, groupPersistenceDirectory,
>     	    null /* serverCommand */,
>     	    null /* serverOptions */,
>     	    null /* serverProperties */),
>     	new SharedActivatableServiceDescriptor(
>     	    outriggerCodebase, outriggerPolicy, outriggerClasspath,
>     	    "org.apache.river.outrigger.PersistentOutriggerImpl",
>     	    groupPersistenceDirectory,
>     	    new String[] { outriggerConfig },
>     	    true /* restart */)
>         };
>     }

#### File config_dir/activatable-outrigger.config

Use this configuration source file to run activatable Outrigger using Jini ERI the Snaplogstore implementation of `Store`.

>     import org.apache.river.outrigger.snaplogstore.LogStore;

>     org.apache.river.outrigger {
>         initialLookupGroups = new String[] { "your.group" };
>         persistenceDirectory = "config_dir/outrigger.log";
>         store = new LogStore(this);
>     }

@see net.jini.space.JavaSpace @see net.jini.space.JavaSpace05