Package com.sun.jini.outrigger

This is an implementation of a JavaSpaces technology-enabled service.

See: Description

Package com.sun.jini.outrigger Description

This is an implementation of a JavaSpaces technology-enabled service. In addition to implementing the basic JavaSpace interface, it all implements the 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 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, 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. 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 Administrable in addition to JavaSpace and JavaSpace05. Outrigger's admin proxy can be obtained by calling Administrable.getAdmin. The admin proxy implements JoinAdmin and DestroyAdmin. The admin proxy will also implement ConstrainableJavaSpaceAdmin if the server has been set up with a Java(TM) remote method invocation (Java RMI) implementation that supports constraints, or 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:

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: 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 LookupDiscovery configuration entries.

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

plus the following configuration entries from LookupDiscovery : LookupLocatorDiscovery : and JoinManager : in addition to providing appropriate security policy files, key stores, login configuration files, etc.

The Outrigger service implementation obtains its configuration by calling 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: ProxyPreparer
  Default: An instance of BasicProxyPreparer that does nothing
  Description: Proxy preparer to use for the ActivationID passed to the activation constructor. Only obtained if being run as an activatable service. The preparer should expect Outrigger to call the activate method of the proxy being prepared. Obtained at activatable service start and restart.
• activationSystemPreparer
  Type: ProxyPreparer
  Default: An instance of BasicProxyPreparer that does nothing
  Description: Proxy preparer to use for the ActivationSystem proxy. Only obtained if being run as an activatable service. The preparer should expect Outrigger to call the unregisterGroup method of the proxy being prepared. Obtained at activatable service start and restart.
• contentsLeasePeriodPolicy
  Type: LeasePeriodPolicy
  Default: A new FixedLeasePeriodPolicy that allows leases up to one hour, and grants one hour leases for duration requests of Lease.ANY
  Description: Policy used to determine the length of initial grants and renewals of the leases on MatchSet instances. Obtained at service start and restart.
• discoveryManager
  Type: DiscoveryManagement
  Default: 
new LookupDiscoveryManager(
    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 DiscoveryGroupManagement and DiscoveryLocatorManagement. The 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 JoinAdmin interface). Note, if you use the default you should also consult the LookupDiscoveryManager documentation to see what configuration entries it reads. Obtained at service start and restart.
• entryLeasePeriodPolicy
  Type: LeasePeriodPolicy
  Default: A new FixedLeasePeriodPolicy that allows leases up to Long.MAX_VALUE, and grants one day leases for duration requests of 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: LeasePeriodPolicy
  Default: A new FixedLeasePeriodPolicy that allows leases up to one hour, and grants one hour leases for duration requests of 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: 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 JoinAdmin interface.
• initialLookupGroups
  Type: 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 JoinAdmin interface.
• initialLookupLocators
  Type: 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 JoinAdmin interface.
• iteratorBatchSize
  Type: int
  Default: 100
  Description: Fetch ahead limit for JavaSpace05.contents and 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: ProxyPreparer
  Default: An instance of BasicProxyPreparer that does nothing
  Description: Proxy preparer for RemoteEventListener proxies passed to JavaSpace.notify. The preparer should expect Outrigger to call the 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: 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: ProxyPreparer
  Default: An instance of BasicProxyPreparer that does nothing
  Description: Proxy preparer to use for instances of LookupLocator that are passed to various JoinAdmin methods. The preparer should expect Outrigger to call the 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 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: 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 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: TaskManager
  Default: new TaskManager()
  Description: The pool of threads used to make event delivery attempts. The terminate method of this object will be called when the service is destroyed. Obtained at service start and restart.
• persistenceDirectory
  Type: String
  Default: none
  Description: If the com.sun.jini.outrigger.snaplogstore.LogStore implementations of 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: 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 Thread.MIN_PRIORITY and Thread.MAX_PRIORITY inclusive. See also the reapingInterval configuration entry. Obtained at service start and restart.
• recoveredListenerPreparer
  Type: ProxyPreparer
  Default: An instance of BasicProxyPreparer that does nothing
  Description: Proxy preparer for RemoteEventListener proxies that have been persisted and recovered. The preparer should expect Outrigger to call the 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: ProxyPreparer
  Default: An instance of BasicProxyPreparer that does nothing
  Description: Proxy preparer to use for instances of LookupLocator that have been persisted and recovered. This will include LookupLocators passed into various JoinAdmin methods as well as the initial set of locators obtained from the initialLookupLocators configuration entry. The preparer should expect Outrigger to call the 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: ProxyPreparer
  Default: An instance of BasicProxyPreparer that does nothing
  Description: Proxy preparer for TransactionManager proxies that have been persisted and recovered. The preparer should expect Outrigger to call the 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: Exporter
  Default: A new BasicJeriExporter with If activatable, the same default will be used but wrapped in an ActivationExporter and created with the service's 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: 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 com.sun.jini.outrigger.snaplogstore.LogStore instance can be created like this:

new com.sun.jini.outrigger.snaplogstore.LogStore(this) // `this' == the configuration object

• takeMultipleLimit
  Type: int
  Default: 100
  Description: Maximum number of entries a JavaSpace05.take call may return. Must be a positive int value. Obtained at service start and restart.
• transactionManagerPreparer
  Type: ProxyPreparer
  Default: An instance of BasicProxyPreparer that does nothing
  Description: Proxy preparer for TransactionManager proxies managing transactions Outrigger is participating in. The preparer should expect Outrigger to call the join, 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: TaskManager
  Default: new TaskManager()
  Description: The pool of threads used to check the status of transactions that have been prepared or have locked contended resources. The 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 Exporter.unexport calls. Obtained at service start and restart. See maxUnexportDelay for additional details.

Other Configuration Entries

Outrigger uses JoinManager to manage its lookup service registrations, passing in the configuration, the DiscoveryManagement object obtained from the discoveryManager configuration entry, and null for the LeaseRenewalManager. The JoinManager documentation should be consulted to see what configuration entries JoinManager reads.

Blocking Queries

 Outrigger implements blocking queries (read, take, take, readIfExists, and 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 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

The following table lists the remote methods on Outrigger's proxy objects and the associated target names for enforcing access control using OutriggerPermission:

Proxy Method Target Name
JavaSpace.write write
JavaSpace.take take
JavaSpace.read read
JavaSpace.takeIfExists takeIfExists
JavaSpace.readIfExists readIfExists
JavaSpace.notify notify
JavaSpace05.write write
JavaSpace05.take take
JavaSpace05.contents contents
JavaSpace05.registerForAvailabilityEvent registerForAvailabilityEvent
MatchSet.next nextBatch
TransactionParticipant.prepare prepare
TransactionParticipant.commit commit
TransactionParticipant.abort abort
TransactionParticipant.prepareAndCommit prepareAndCommit
Lease.renew renew
Lease.cancel cancel
LeaseMap.renewAll renewAll
LeaseMap.cancelAll cancelAll
Administrable.getAdmin getAdmin
JoinAdmin.getLookupAttributes getLookupAttributes
JoinAdmin.addLookupAttributes addLookupAttributes
JoinAdmin.modifyLookupAttributes modifyLookupAttributes
JoinAdmin.getLookupGroups getLookupGroups
JoinAdmin.addLookupGroups addLookupGroups
JoinAdmin.removeLookupGroups removeLookupGroups
JoinAdmin.setLookupGroups setLookupGroups
JoinAdmin.getLookupLocators getLookupLocators
JoinAdmin.addLookupLocators addLookupLocators
JoinAdmin.removeLookupLocators removeLookupLocators
JoinAdmin.setLookupLocators setLookupLocators
DestroyAdmin.destroy destroy
ProxyTrust.getProxyVerifier getProxyVerifier
ServiceProxyAccessor.getServiceProxy getServiceProxy
JavaSpaceAdmin.space space
JavaSpaceAdmin.contents(Entry, Transaction),
JavaSpaceAdmin.contents(Entry, Transaction, int),
ConstrainableJavaSpaceAdmin.contents(Entry, Transaction, int, MethodConstraints) 		contents
AdminIterator.next next
AdminIterator.delete delete
AdminIterator.close close

Logging

 The Outrigger service implementation uses a number of different Logger objects:

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

This section provides examples of running Outrigger in various 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:

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

File config_dir/transient-jrmp-outrigger.config

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

import net.jini.jrmp.JrmpExporter;

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

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 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 */)
    };
}

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

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 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 */)
    };
}

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

File config_dir/transient-outrigger.config

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

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

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 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"));
}
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 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 :

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 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 */)
    };
}

File config_dir/activatable-outrigger.config

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


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);
}
See Also:
JavaSpace, JavaSpace05

Copyright 2007-2013, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.