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 com.sun.jini.outrigger.TransientOutriggerImpl; the second by com.sun.jini.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 com.sun.jini.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 com.sun.jini.outrigger.snaplogstore.LogStore com.sun.jini.outrigger.snaplogstore.LogStore}, also called Snaplogstore. Snaplogstore was introduced in the 2.1beta2 release. The original implementation of the Store interface, com.sun.jini.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 com.sun.jini.admin.DestroyAdmin}. The admin proxy will also implement {@link com.sun.jini.outrigger.ConstrainableJavaSpaceAdmin} if the server has been set up with a Java(TM) remote method invocation (Java RMI) implementation that supports constraints, or {@link com.sun.jini.outrigger.JavaSpaceAdmin} if constraints are not supported. However, 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

• persistenceDirectory (required if using PersistentOutriggerImpl)
• store (required if using PersistentOutriggerImpl)
• initialLookupGroups
• initialLookupLocators
• initialLookupAttributes

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)

• registrarPreparer
• discoveryConstraints

• registrarPreparer

• registrarPreparer
• registrationPreparer
• serviceLeasePreparer

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 com.sun.jini.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 com.sun.jini.landlord.LeasePeriodPolicy}
	Default:	A new {@link com.sun.jini.landlord.FixedLeasePeriodPolicy} that allows leases up to one hour, and grants one hour leases for duration requests of {@link net.jini.core.lease.Lease#ANY Lease.ANY}
	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 com.sun.jini.landlord.LeasePeriodPolicy}
	Default:	A new {@link com.sun.jini.landlord.FixedLeasePeriodPolicy} that allows leases up to {@link java.lang.Long#MAX_VALUE Long.MAX_VALUE}, and grants one day leases for duration requests of {@link net.jini.core.lease.Lease#ANY Lease.ANY}
	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 com.sun.jini.landlord.LeasePeriodPolicy}
	Default:	A new {@link com.sun.jini.landlord.FixedLeasePeriodPolicy} that allows leases up to one hour, and grants one hour leases for duration requests of {@link net.jini.core.lease.Lease#ANY Lease.ANY}
	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 com.sun.jini.outrigger.snaplogstore.LogStore com.sun.jini.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.

•	notificationsTaskManager
	Type:	{@link com.sun.jini.thread.TaskManager}
	Default:	new {@link com.sun.jini.thread.TaskManager#TaskManager() TaskManager()}
	Description:	The pool of threads used to make event delivery attempts. The {@link com.sun.jini.thread.TaskManager#terminate terminate} method of this object will be called when the service is destroyed. Obtained at service start and restart.

•	persistenceDirectory
	Type:	{@link java.lang.String}
	Default:	none
	Description:	If the {@link com.sun.jini.outrigger.snaplogstore.LogStore com.sun.jini.outrigger.snaplogstore.LogStore} implementations of {@link com.sun.jini.outrigger.Store} is being used, the value of this entry is the name of the directory that should be used to persist Outrigger's state. Obtained at persistent service start and restart.

•	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 LookupLocators 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 com.sun.jini.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 com.sun.jini.outrigger.snaplogstore.LogStore com.sun.jini.outrigger.snaplogstore.LogStore} instance can be created like this: new {@link com.sun.jini.outrigger.snaplogstore.LogStore#LogStore com.sun.jini.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.

•	txnMonitorTaskManager
	Type:	{@link com.sun.jini.thread.TaskManager}
	Default:	new {@link com.sun.jini.thread.TaskManager#TaskManager() TaskManager()}
	Description:	The pool of threads used to check the status of transactions that have been prepared or have locked contended resources. The {@link com.sun.jini.thread.TaskManager#terminate terminate} method of this object will be called when the service is destroyed. Obtained at service start and restart.

•	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

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 com.sun.jini.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

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 com.sun.jini.admin.DestroyAdmin#destroy DestroyAdmin.destroy}	destroy
{@link net.jini.security.proxytrust.ProxyTrust#getProxyVerifier ProxyTrust.getProxyVerifier}	getProxyVerifier
{@link com.sun.jini.start.ServiceProxyAccessor#getServiceProxy ServiceProxyAccessor.getServiceProxy}	getServiceProxy
{@link com.sun.jini.outrigger.JavaSpaceAdmin#space JavaSpaceAdmin.space}	space
{@link com.sun.jini.outrigger.JavaSpaceAdmin#contents( net.jini.core.entry.Entry, net.jini.core.transaction.Transaction) JavaSpaceAdmin.contents(Entry, Transaction)}, {@link com.sun.jini.outrigger.JavaSpaceAdmin#contents( net.jini.core.entry.Entry, net.jini.core.transaction.Transaction, int) JavaSpaceAdmin.contents(Entry, Transaction, int)}, {@link com.sun.jini.outrigger.ConstrainableJavaSpaceAdmin#contents( net.jini.core.entry.Entry, net.jini.core.transaction.Transaction, int, net.jini.core.constraint.MethodConstraints) ConstrainableJavaSpaceAdmin.contents(Entry, Transaction, int, MethodConstraints)}	contents
{@link com.sun.jini.outrigger.AdminIterator#next AdminIterator.next}	next
{@link com.sun.jini.outrigger.AdminIterator#delete AdminIterator.delete}	delete
{@link com.sun.jini.outrigger.AdminIterator#close AdminIterator.close}	close

Logging

Logger Name	Description
com.sun.jini.outrigger.lifecycle	Starting/restarting/destroying the service
com.sun.jini.outrigger.operations	Top level space operations
com.sun.jini.outrigger.transactions	Transactions
com.sun.jini.outrigger.leases	Leases and leasing
com.sun.jini.outrigger.iterator	Iterators
com.sun.jini.outrigger.join	Outrigger's join state
com.sun.jini.outrigger.entryMatching	Entry matching
com.sun.jini.outrigger.event	Events and event delivery
com.sun.jini.outrigger.store	Persistence
com.sun.jini.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

• 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 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 com.sun.jini.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 com.sun.jini.phoenix} implementation for this purpose.

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

Starting Transient Outrigger using JRMP

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

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;
};

import com.sun.jini.start.NonActivatableServiceDescriptor;
import com.sun.jini.start.ServiceDescriptor;
import com.sun.jini.config.ConfigUtil;

com.sun.jini.start {
    private static basecodebase = "http://" + ConfigUtil.getHostName() +
        ":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,
	    "com.sun.jini.outrigger.TransientOutriggerImpl",
	    new String[] { config })
    };
}

import net.jini.jrmp.JrmpExporter;

com.sun.jini.outrigger {
    initialLookupGroups = new String[] { "your.group" };
    serverExporter = new JrmpExporter();
}

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

import com.sun.jini.start.ServiceDescriptor;
import com.sun.jini.start.SharedActivatableServiceDescriptor;
import com.sun.jini.start.SharedActivationGroupDescriptor;
import com.sun.jini.config.ConfigUtil;

com.sun.jini.start {
    private static basecodebase = "http://" + ConfigUtil.getHostName() +
        ":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,
	    "com.sun.jini.outrigger.PersistentOutriggerImpl",
	    groupPersistenceDirectory,
	    new String[] { outriggerConfig },
	    true /* restart */)
    };
}

import com.sun.jini.outrigger.snaplogstore.LogStore;
import java.rmi.activation.ActivationID;
import net.jini.jrmp.JrmpExporter;

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

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

import com.sun.jini.start.ServiceDescriptor;
import com.sun.jini.start.SharedActivatableServiceDescriptor;
import com.sun.jini.config.ConfigUtil;

com.sun.jini.start {
    private static codebase = "http://" + ConfigUtil.getHostName() +
        ":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,
	    "com.sun.jini.start.SharedGroupImpl",
	    persistenceDirectory,
	    null /* config */,
	    false /* restart */)
    };
}

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

import com.sun.jini.start.NonActivatableServiceDescriptor;
import com.sun.jini.start.ServiceDescriptor;
import com.sun.jini.config.ConfigUtil;

com.sun.jini.start {
    private static basecodebase = "http://" + ConfigUtil.getHostName() +
        ":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,
	    "com.sun.jini.outrigger.TransientOutriggerImpl",
	    new String[] { config })
    };
}

com.sun.jini.outrigger {
    initialLookupGroups = new String[] { "your.group" };
}

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

import com.sun.jini.start.NonActivatableServiceDescriptor;
import com.sun.jini.start.ServiceDescriptor;
import com.sun.jini.config.ConfigUtil;

com.sun.jini.start {
    private static basecodebase = "http://" + ConfigUtil.getHostName() +
        ":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,
	    "com.sun.jini.outrigger.PersistentOutriggerImpl",
	    new String[] { config })
    };
}

import com.sun.jini.outrigger.snaplogstore.LogStore;
import net.jini.id.UuidFactory;
import net.jini.jeri.BasicILFactory;
import net.jini.jeri.BasicJeriExporter;
import net.jini.jeri.tcp.TcpServerEndpoint;

com.sun.jini.outrigger {
    initialLookupGroups = new String[] { "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"));
}

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

Starting Activatable Outrigger using Jini ERI

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

import com.sun.jini.start.ServiceDescriptor;
import com.sun.jini.start.SharedActivatableServiceDescriptor;
import com.sun.jini.start.SharedActivationGroupDescriptor;
import com.sun.jini.config.ConfigUtil;

com.sun.jini.start {
    private static basecodebase = "http://" + ConfigUtil.getHostName() +
        ":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,
	    "com.sun.jini.outrigger.PersistentOutriggerImpl",
	    groupPersistenceDirectory,
	    new String[] { outriggerConfig },
	    true /* restart */)
    };
}

import com.sun.jini.outrigger.snaplogstore.LogStore;

com.sun.jini.outrigger {
    initialLookupGroups = new String[] { "your.group" };
    persistenceDirectory = "config_dir/outrigger.log";
    store = new LogStore(this);
}