Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

## Package com.sun.jini.outrigger

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

See:
Description

Interface Summary
AdminIterator | Interface for the iterators returned by the `contents()` method of `JavaSpaceAdmin`.
ConstrainableJavaSpaceAdmin | Sub-interface of `JavaSpaceAdmin` that adds a method that allows iterators to be created with a given set of constraints.
JavaSpaceAdmin | This interface contains all the administrative methods that Outrigger provides to control its JavaSpacesTM service.
LogOps | Methods that log an operation.
OutriggerServer.QueryCookie | Marker interface for objects that represent state that the server finds useful to share across sub-queries.
Recover | Methods that recover the state of the space after a restart.
StorableObject | Interface that must be implemented by objects that must persist their state.
StorableResource | Sub-interface of `StorableObject` that must be implemented by objects that represent leased resources and must persist their state.
Store | This interface defines the methods that any OutriggerServerImpl store must implement.
StoredObject | Interface for a stored resource.
StoredResource | Interface for a stored resource.

Class Summary
OutriggerPermission | Permission that can be used to express the access control policy for an instance of an Outrigger server exported with a `BasicJeriExporter`.
OutriggerServerImpl | A basic implementation of a JavaSpacesTM service.

## Package com.sun.jini.outrigger Description

This is an implementation of a JavaSpaces(TM) technology-enabled service. There are two ways to run it — 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.

The JAR file `outrigger.jar`, included in the `lib` subdirectory of the Jini(TM) Technology Starter Kit (starter kit) installation, contains the classes for `TransientOutriggerImpl`. `outrigger.jar` also includes, via JAR file manifest classpath directives, references to `outrigger-logstore.jar` and (via `outrigger-logstore.jar` manifest) `pro.zip`. These two files add the necessary classes to run `PersistentOutriggerImpl` with the default store implementation. `outrigger-logstore.jar` and `pro.zip` must be in the same directory as `outrigger.jar` for `PersistentOutriggerImpl` to operate properly.

The JAR file `outrigger-dl.jar` in the `lib` directory contains the classes needed in an Outrigger server's codebase for its downloaded proxies. None of the JAR files includes classes from `jsk-platform.jar`, which are included by the service starter's `start.jar` JAR file, and are assumed to be present in the classpath of clients.

Outrigger's top level proxy implements `Administrable` in addition to `JavaSpace`. The proxy returned by `Administrable.getAdmin` implements `JavaSpaceAdmin`. It will also implement `ConstrainableJavaSpaceAdmin` if the server has been set up with a Java(TM) remote method invocation (Java RMI) implementation that supports constraints.

This document provides the following information about Outrigger:

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

## Configuration Entries Consulted By Outrigger

The Outrigger service implementation consults a number of configuration entries. Most deployments will find it useful to provide values for one or more of the following configuration entries:

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

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

Deployments that want to use a Java RMI implementation other than Jini(TM) 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:

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

plus the following configuration entries from `LookupDiscovery` :

- `registrarPreparer`
- `discoveryConstraints`

`LookupLocatorDiscovery` :

- `registrarPreparer`

and `JoinManager` :

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

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

The Outrigger service implementation obtains its configuration by calling `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.

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

• | `gcInterval`
--- | ---
| Type: | `int`
| Default: | `5`
| Description: | How often should Outrigger garbage collect the persistent store. Only consulted if `LogStore` is being used for the `store` configuration entry. Outrigger writes directives into logs that are consumed by a consumer thread. The consumer thread applies the directives to the persistent store. This configuration entry represents how many logs must be consumed before the persistent store is garbage collected. Must be a positive `int` value. See also the `maxOps` configuration entry. 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.

• | `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 `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. See also the `gcInterval` configuration entry. 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.

• | `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 default `Store` implementation 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 and template objects. 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 thread that periodically wakes up and removes entries and templates 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 `LookupLocator`s 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 a `TcpServerEndpoint` created on a random port, a `BasicILFactory`, distributed garbage collection turned off, keep alive on. 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: | `new` `LogStore(this)` `// `this' == the configuration object`
| 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.

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

### 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`, `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`
`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.

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

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

### Assumptions for Running the Examples

The examples below make the following assumptions:

- The Java(TM) 2 Platform, Standard Edition, (J2SE(TM)) has been installed, and its commands are available in the current path
- The starter kit 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 directory. You can use the `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 `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

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/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-logstore.jar" {
>         permission java.security.AllPermission;
>     };

>     grant codebase "file:install_dir/lib/pro.zip" {
>         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 codebase = ConfigUtil.concat(new Object[] {
>             "http://",
>             ConfigUtil.getHostName(),
>             ":http_port/outrigger-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 :

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

If you want to replace the first space with a new and empty space that has a new identity, you should first destroy the original space using Outrigger's administrable interface. You may also want to destroy the original activation group. If you destroy the entire activation group you can skip using Outrigger's administrable interface to destroy the Outrigger service instance, and instead remove config_dir/outrigger.log after destroying the activation group.

This configuration uses the following additional files.

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

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

>     import 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 outriggerCodebase = ConfigUtil.concat(new Object[] {
>             "http://",
>             ConfigUtil.getHostName(),
>             ":http_port/outrigger-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 groupCodebase = ConfigUtil.concat(new Object[] {
>             "http://",
>             ConfigUtil.getHostName(),
>             ":http_port/outrigger-dl.jar"});
>         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.

>     import java.rmi.activation.ActivationID;
>     import net.jini.jrmp.JrmpExporter;

>     com.sun.jini.outrigger {
>         initialLookupGroups = new String[] { "your.group" };
>         persistenceDirectory = "config_dir/outrigger.log";
>         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 = ConfigUtil.concat(new Object[] {
>             "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 starter kit) 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 codebase = ConfigUtil.concat(new Object[] {
>             "http://",
>             ConfigUtil.getHostName(),
>             ":http_port/outrigger-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 codebase = ConfigUtil.concat(new Object[] {
>             "http://",
>             ConfigUtil.getHostName(),
>             ":http_port/outrigger-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.

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

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

If you want to replace the first space with a new and empty space that has a new identity, you should first destroy the original space using Outrigger's administrable interface. You may also want to destroy the original activation group. If you destroy the entire activation group you can skip using Outrigger's administrable interface to destroy the Outrigger service instance, and instead remove config_dir/outrigger.log after destroying the activation group.

This configuration uses the following additional files.

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

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

>     import 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 outriggerCodebase = ConfigUtil.concat(new Object[] {
>             "http://",
>             ConfigUtil.getHostName(),
>             ":http_port/outrigger-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 groupCodebase = ConfigUtil.concat(new Object[] {
>             "http://",
>             ConfigUtil.getHostName(),
>             ":http_port/group-dl.jar"});
>         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.

>     com.sun.jini.outrigger {
>         initialLookupGroups = new String[] { "your.group" };
>         persistenceDirectory = "config_dir/outrigger.log";
>     }

See Also:
  `JavaSpace`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

Copyright © 2004 Sun Microsystems, Inc. All rights reserved