org.apache.river.norm (River-Internet vtrunk API Documentation)

Class Summary
Class Description

NormPermission
Represents permissions that can be used to express the access control policy for the a Norm server exported with a BasicJeriExporter.
Exception Summary
Exception Description

InternalNormException
This exception denotes a problem with the local implementation of a Norm server.

Class Summary
Class	Description
NormPermission	Represents permissions that can be used to express the access control policy for the a Norm server exported with a `BasicJeriExporter`.

Exception Summary
Exception	Description
InternalNormException	This exception denotes a problem with the local implementation of a Norm server.

Package org.apache.river.norm Description

Provides implementations of LeaseRenewalService. Three implementations are available for use with the org.apache.river.start package:

org.apache.river.norm.ActivatableNormServerImpl - an activatable, persistent implementation, suitable for use with SharedActivatableServiceDescriptor
org.apache.river.norm.PersistentNormServerImpl - a non-activatable, persistent implementation, suitable for use with NonActivatableServiceDescriptor
org.apache.river.norm.TransientNormServerImpl - a transient implementation, also suitable for use with NonActivatableServiceDescriptor

The JAR file norm.jar, included in the lib subdirectory of the River-Internet release installation, contains the classes for the three Norm service implementations. The norm-dl.jar and jsk-dl.jar files in the lib-dl subdirectory contain the classes needed in the codebase for its downloaded proxies. None of these JAR files include classes from jsk-platform.jar, which are included by the service starter's start.jar JAR file, and need to be included in the codebase of clients.

The object returned by the Administrable.getAdmin method on a Norm service proxy implements JoinAdmin and DestroyAdmin.

This document provides the following information about Norm:

Configuring Norm
Access Control Permission Targets
Logging
Examples for Running Norm

Configuring Norm

The Norm 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 org.apache.river.norm:

•	`activationIdPreparer`
	Type:	`ProxyPreparer`
	Default:	`new BasicProxyPreparer()`
	Description:	The proxy preparer for the service's activation ID. The value should not be `null`. This entry is obtained at service start and restart. This entry is only used by the activatable implementation. Clients call the `activate` method on instances of `ActivationID` when they need to reactivate the service.

•	`activationSystemPreparer`
	Type:	`ProxyPreparer`
	Default:	`new BasicProxyPreparer()`
	Description:	The proxy preparer for the proxy for the activation system. The value should not be `null`. This entry is obtained at service start and restart. This entry is only used by the activatable implementation. The service calls the `unregisterObject` method on the `ActivationSystem` when the service is destroyed.

•	`discoveryManager`
	Type:	`DiscoveryManagement`
	Default:	new `LookupDiscoveryManager`( `DiscoveryGroupManagement.NO_GROUPS`, null, // locators null, // listener this) // config
	Description:	Supplies an object used to discover the lookup services with which this service should register. The value should not be `null`. The object returned must also implement `DiscoveryGroupManagement` and `DiscoveryLocatorManagement`, and should be configured initially to discover no groups or specific lookup services. This entry is obtained at service start and restart.

•	`initialLookupAttributes`
	Type:	`Entry[]`
	Default:	`null`
	Description:	Entries to include in the set of attributes the service supplies when registering with lookup services, in addition to `ServiceInfo` and `BasicServiceType` instances provided by the service. An empty array or `null` specifies that only the service-provided attributes should be added. The array must not contain `null` elements. This entry is obtained and used when the service is first started. Following initial startup, the set of attributes is controlled though the service's `JoinAdmin` administrable interface.

•	`initialLookupGroups`
	Type:	`String[]`
	Default:	`new String[] { "" } /* public group */`
	Description:	The names of the lookup groups that the service should discover and join. An empty array specifies that no groups should be joined. A `null` value specifies that all groups should be joined. Otherwise, the value specifies the names of the groups to join. The array must not contain `null` elements. This entry is obtained and used when the service is first started. Following initial startup, the set of lookup groups is controlled through the service's `JoinAdmin` administrable interface.

•	`initialLookupLocators`
	Type:	`LookupLocator[]`
	Default:	`null /* no locators */`
	Description:	The locations of specific lookup services that the service should discover and join. An empty array or `null` specifies that no specific lookup services should be joined. The array must not contain `null` elements. This entry is obtained and used when the service is first started. Following initial startup, the set of specific lookup services is controlled through the service's `JoinAdmin` administrable interface. The `LookupLocator` instances specified in this entry will not be prepared by the proxy preparer specified in the `locatorPreparer` entry, and will only be prepared by the preparer in the `recoveredLocatorPreparer` entry when they are being recovered.

•	`isolateSets`
	Type:	`boolean`
	Default:	`false`
	Description:	Whether to isolate leases in their own renewal sets rather than batching leases in different sets. This entry is obtained at service start and restart. Setting this entry to `false` (the default) makes it more likely that the service can achieve better performance by batching leases, because it permits leases in different lease sets to be batched together. Note that batching leases across sets introduces the risk that mutually mistrustful leases in different sets will "capture" each other when they are batched, allowing an untrustworthy lease to gain access to leases in other sets.

•	`leaseManager`
	Type:	`LeaseRenewalManager`
	Default:	`new LeaseRenewalManager(this /* config */)`
	Description:	Supplies the lease renewal manager that Norm both uses to renew client leases and passes to the constructor when creating its `JoinManager`. The value should not be `null`. This entry is obtained at service start and restart.

•	`leasePolicy`
	Type:	`LeasePeriodPolicy`
	Default:	new `FixedLeasePeriodPolicy`( 2 * 60 * 60 * 1000L, // max = 2 hours 60 * 60 * 1000L) // default = 1 hour
	Description:	The policy for calculating lease grants and renewals. The value should not be `null`. The default grants leases with a maximum duration of 2 hours and a default duration of 1 hour. This entry is obtained at service start and restart.

• leasePreparer

Type: ProxyPreparer

Default: new BasicProxyPreparer()

Description:

Prepares client leases for use when they are supplied in calls to LeaseRenewalSet.renewFor or LeaseRenewalSet.remove. The value should not be null. The preparer must return a lease which is equal to the original lease as determined by Object.equals. This entry is obtained at service start and restart.

This preparer needs to perform all operations needed to use a newly received lease, typically including verifying trust in the lease proxy, granting permissions, and setting constraints. The prepared lease will be retained by the service in its persistent store.

The service calls the renew method on Lease instances, and the renewAll method on lease maps it creates (via the LeaseRenewalManager) from the leases.

• listenerPreparer

Type: ProxyPreparer

Default: new BasicProxyPreparer()

Description:

Prepares expiration warning and renewal failure listeners for use when they are supplied in calls to LeaseRenewalSet.setExpirationWarningListener and LeaseRenewalSet.setRenewalFailureListener. The value should not be null. The preparer must return a listener which is equal to the original listener as determined by Object.equals. This entry is obtained at service start and restart.

This preparer needs to perform all operations needed to use a newly received listener, typically including verifying trust in the listener proxy, granting permissions, and setting constraints. The prepared listener will be retained by the service in its persistent store.

The service calls the notify method on RemoteEventListener objects.

• locatorPreparer

Type: ProxyPreparer

Default: new BasicProxyPreparer()

Description:

Prepares LookupLocator instances for use that are passed to JoinAdmin methods. The value should not be null. When registering with lookup services, this service may call or use the constraints assigned to the getRegistrar methods of LookupLocator instances returned from this preparer. This entry is obtained at service start and restart.

This preparer needs to perform all operations needed to use a newly received lookup locator, typically including verifying trust in the lookup locator and setting constraints. The prepared lookup locator will be retained by the service in its persistent store.

The LookupLocator instances obtained from the initialLookupLocators configuration entry will not be prepared by this preparer.

•	`loginContext`
	Type:	`LoginContext`
	Default:	`null`
	Description:	If not `null`, specifies the JAAS login context to use for performing a JAAS login and supplying the `Subject` to use when running the service. If `null`, no JAAS login is performed. This entry is obtained at service start and restart.

•	`persistenceDirectory`
	Type:	`String`
	Default:	Required for persistent implementations: no default
	Description:	The directory where the service's persistent state is recorded. The value should not be `null`. This entry is obtained at service start and restart. This entry is required for persistent implementations and is otherwise not used.

•	`persistenceSnapshotThreshold`
	Type:	`int`
	Default:	`200`
	Description:	The threshold used to determine whether or not to take a snapshot of the server's state. The value should not be negative. The service will delay making new snapshots until the number of log updates is greater than this value. This entry is obtained at service start and restart. This entry is only used by persistent implementations.

•	`persistenceSnapshotWeight`
	Type:	`float`
	Default:	`10.0f`
	Description:	The weight factor used to determine whether or not to take a snapshot of the server's state. The value should not be negative. The value represents the ratio of the size of an item in a snapshot versus the size of a log update. This entry is obtained at service start and restart. This entry is only used by persistent implementations.

• recoveredLeasePreparer

Type: ProxyPreparer

Default: new BasicProxyPreparer()

Description:

Prepares client leases for use when they are recovered from persistent storage. The value should not be null. The preparer must return a lease which is equal to the original lease as determined by Object.equals. This entry is obtained at service start and restart. This entry is only used by persistent implementations.

This preparer needs to perform only those operations whose results are not retained in the lease proxy itself, but need to be performed in the environment in which the proxy is unmarshalled, typically just granting permissions.

The service calls the renew method on Lease instances, and the renewAll method on lease maps it creates (via the LeaseRenewalManager) from the leases.

• recoveredListenerPreparer

Type: ProxyPreparer

Default: new BasicProxyPreparer()

Description:

Prepares expiration warning and renewal failure listeners for use when they are recovered from persistent storage. The value should not be null. The preparer must return a listener which is equal to the original listener as determined by Object.equals. This entry is obtained at service start and restart. This entry is only used by persistent implementations.

This preparer needs to perform only those operations whose results are not retained in the listener proxy itself, but need to be performed in the environment in which the proxy is unmarshalled, typically just granting permissions.

The service calls the notify method on RemoteEventListener objects.

• recoveredLocatorPreparer

Type: ProxyPreparer

Default: new BasicProxyPreparer()

Description:

Prepares LookupLocator instances for use when they are recovered from persistent storage. The value should not be null. When registering with lookup services, this service may call or use the constraints assigned to the getRegistrar methods of LookupLocator instances returned from this preparer. This entry is obtained at service start and restart. This entry is only used by persistent implementations.

This preparer needs to perform only those operations whose results are not retained in the lookup locator itself, but need to be performed in the environment in which the lookup locator is unmarshalled. Typically no operations are needed.

The LookupLocator instances obtained from the initialLookupLocators configuration entry will not be prepared by this preparer until they are being recovered.

•	`serverExporter`
	Type:	`Exporter`
	Default:	// Activatable implementation new `ActivationExporter`( activationID, new `BasicJeriExporter`( `TcpServerEndpoint.getInstance`(0), new `BasicILFactory`())) // Non-activatable implementations new `BasicJeriExporter`( `TcpServerEndpoint.getInstance`(0), new `BasicILFactory`())
	Description:	The object to use for exporting the service. The value should not be `null`. In the activatable case, the call to `getEntry` will supply the activation ID in the `data` argument. This entry is obtained at service start and restart.

Norm passes its configuration when creating instances of the following configurable classes, which may support additional configuration entries:

LeaseRenewalManager, used to renew leases, as specified by the leaseManager configuration entry
LookupDiscoveryManager, used to discover lookup services, as specified by the discoveryManager configuration entry
JoinManager, used to manage lookup service registrations

Access Control Permission Targets

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

Proxy Method	Target Name
`LeaseRenewalService.createLeaseRenewalSet`	createLeaseRenewalSet
`LeaseRenewalSet.renewFor(Lease, long)`, `LeaseRenewalSet.renewFor(Lease, long, long)`	renewFor
`LeaseRenewalSet.remove`	remove
`LeaseRenewalSet.getLeases`	getLeases
`LeaseRenewalSet.setExpirationWarningListener`, `LeaseRenewalSet.clearExpirationWarningListener`	setExpirationWarningListener
`LeaseRenewalSet.setRenewalFailureListener`, `LeaseRenewalSet.clearRenewalFailureListener`	setRenewalFailureListener
`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

Loggers and Logging Levels

The Norm service implementation uses the Logger named org.apache.river.norm to log information at the following logging levels:

**`org.apache.river.norm`**
Level	Description
`SEVERE`	Problems that prevent service startup
`WARNING`	Problems making modifications to persistent storage, unexpected internal errors
`INFO`	Service start, restart, or destruction; problems recovering lookup locators or lookup attributes; thread problems; leases or event listeners dropped because of definite exceptions; or problems when destroying the service, or in cleaning up after start up fails
`CONFIG`	Changes made to the service through administrative interfaces
`HANDLED`	Indefinite exceptions renewing leases or delivering events, when preparing or unmarshalling leases or events, or for exceptions handled when destroying the service
`FINE`	Adding or removing leases, leases reaching desired expiration, creating lease renewal sets
`FINER`	Attempting to renew leases, taking persistence snapshots, persistence recovery
`FINEST`	Low level operation tracing

See the LogManager class for one way to use the HANDLED logging level in standard logging configuration files.

Examples for Running Norm

This section provides examples of running Norm in various configurations.

Assumptions for running the examples
JRMP configurations
Jini extensible remote invocation (Jini ERI) configurations
Stopping activatable configurations

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 River-Internet release has been installed in the install_dir directory
The example configuration and policy files described below are available in the config_dir directory
The local host name is your_host
The local lookup group name is your.group
The HTTP server for download JAR files is running on your_host and is available on port http_port. This HTTP server is serving files located in the install_dir/lib-dl directory. You can use the 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 same client and service configurations that enforce security.
For activatable services, an activation system is running on your_host. You can use the org.apache.river.phoenix implementation for this purpose.

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

Starting Transient Norm using JRMP

To run a transient Norm, which does not store any information persistently or use the activation system to restart itself, using JRMP for remote communication, run the following command.

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

This configuration uses the following files.

File `config_dir`/jsk-all.policy

Use this security policy file for starting and running all Norm configurations. This file grants all permissions to local code included in the lib subdirectory of the River-Internet release installation.

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

File `config_dir`/start-transient-jrmp-norm.config

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

import org.apache.river.start.NonActivatableServiceDescriptor;
import org.apache.river.start.ServiceDescriptor;

org.apache.river.start {
    private static codebase = "http://your_host:http_port/norm-dl.jar"
       + " http://your_host:http_port/jsk-dl.jar";
    private static policy = "config_dir/jsk-all.policy";
    private static classpath = "install_dir/lib/norm.jar";
    private static config = "config_dir/transient-jrmp-norm.config";

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

File `config_dir`/transient-jrmp-norm.config

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

import net.jini.jrmp.JrmpExporter;

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

Starting Persistent Norm using JRMP

To run a persistent Norm, which stores information persistently but does not use the activation system to restart itself, using JRMP for remote communication, run the following command.

java -Djava.security.policy=config_dir/jsk-all.policy \
     -jar install_dir/lib/start.jar \
     config_dir/start-persistent-jrmp-norm.config

Note: Because JRMP does not provide a convenient way to specify the same object ID each time a given object is exported, this configuration is only useful for debugging -- an existing service proxy cannot be used after the service is restarted.

This configuration uses the following additional files.

File `config_dir`/start-persistent-jrmp-norm.config

Use this configuration source file to start persistent Norm using JRMP.

import org.apache.river.start.NonActivatableServiceDescriptor;
import org.apache.river.start.ServiceDescriptor;

org.apache.river.start {
    private static codebase = "http://your_host:http_port/norm-dl.jar"
       + " http://your_host:http_port/jsk-dl.jar";
    private static policy = "config_dir/jsk-all.policy";
    private static classpath = "install_dir/lib/norm.jar";
    private static config = "config_dir/persistent-jrmp-norm.config";

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

File `config_dir`/persistent-jrmp-norm.config

Use this configuration source file to run persistent Norm using JRMP.

import net.jini.jrmp.JrmpExporter;

org.apache.river.norm {
    initialLookupGroups = new String[] { "your.group" };
    persistenceDirectory = "config_dir/norm.log";
    serverExporter = new JrmpExporter();
}

Starting Activatable Norm using JRMP

To run an activatable Norm, which stores information persistently and uses the activation system to restart itself, using JRMP for remote communication, run the following command.

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

You should remove the config_dir/group.log directory before running this command. Note that the activation system will restart the activatable Norm service as needed until Norm is shutdown.

Remember to remove the config_dir/norm.log directory before running this command if you want Norm to forget registrations and settings made in previous invocations.

This configuration uses the following additional files.

File `config_dir`/start-activatable-jrmp-norm.config

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

import org.apache.river.start.ServiceDescriptor;
import org.apache.river.start.SharedActivatableServiceDescriptor;
import org.apache.river.start.SharedActivationGroupDescriptor;

org.apache.river.start {
    private static normCodebase = "http://your_host:http_port/norm-dl.jar"
       + " http://your_host:http_port/jsk-dl.jar";
    private static normPolicy = "config_dir/jsk-all.policy";
    private static normClasspath = "install_dir/lib/norm.jar";
    private static normConfig = "config_dir/activatable-jrmp-norm.config";

    private static groupCodebase = "http://your_host:http_port/group-dl.jar";
    private static groupPolicy = "config_dir/jsk-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(
            normCodebase, normPolicy, normClasspath,
            "org.apache.river.norm.ActivatableNormServerImpl",
            groupPersistenceDirectory,
            new String[] { normConfig },
            true /* restart */)
    };
}

File `config_dir`/activatable-jrmp-norm.config

Use this configuration source file to run activatable Norm using JRMP.

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

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

Stopping Activatable Norm

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

java -Djava.security.policy=config_dir/jsk-all.policy \
     -jar install_dir/lib/destroy.jar \
     config_dir/stop-activatable-norm.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 Norm's administrable interface, or to remove the config_dir/norm.log directory after destroying the activation group.

This command uses the following additional file.

File `config_dir`/stop-activatable-norm.config

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

import org.apache.river.start.ServiceDescriptor;
import org.apache.river.start.SharedActivatableServiceDescriptor;

org.apache.river.start {
    private static codebase = "http://your_host:http_port/group-dl.jar";
    private static policy = "config_dir/jsk-all.policy";
    private static classpath = "install_dir/lib/group.jar";
    private static persistenceDirectory = "config_dir/group.log";

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

Starting Transient Norm using Jini ERI

To run a transient Norm, which does not store any information persistently or use the activation system to restart itself, using Jini ERI for remote communication, run the following command.

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

This configuration uses the following additional files.

File `config_dir`/start-transient-norm.config

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

import org.apache.river.start.NonActivatableServiceDescriptor;
import org.apache.river.start.ServiceDescriptor;

org.apache.river.start {
    private static codebase = "http://your_host:http_port/norm-dl.jar"
       + " http://your_host:http_port/jsk-dl.jar";
    private static policy = "config_dir/jsk-all.policy";
    private static classpath = "install_dir/lib/norm.jar";
    private static config = "config_dir/transient-norm.config";

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

File `config_dir`/transient-norm.config

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

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

Starting Persistent Norm using Jini ERI

To run a persistent Norm, which stores information persistently but does not use the activation system to restart itself, using Jini ERI for remote communication, run the following command.

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

This configuration uses the following additional files.

File `config_dir`/start-persistent-norm.config

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

import org.apache.river.start.NonActivatableServiceDescriptor;
import org.apache.river.start.ServiceDescriptor;

org.apache.river.start {
    private static codebase = "http://your_host:http_port/norm-dl.jar"
       + " http://your_host:http_port/jsk-dl.jar";
    private static policy = "config_dir/jsk-all.policy";
    private static classpath = "install_dir/lib/norm.jar";
    private static config = "config_dir/persistent-norm.config";

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

File `config_dir`/persistent-norm.config

Use this configuration source file to run persistent Norm using Jini ERI.

import net.jini.id.UuidFactory;
import net.jini.jeri.BasicILFactory;
import net.jini.jeri.BasicJeriExporter;
import net.jini.jeri.tcp.TcpServerEndpoint;

org.apache.river.norm {
    initialLookupGroups = new String[] { "your.group" };
    persistenceDirectory = "config_dir/norm.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 to use for listening for requests for this object. The obj_UUID_string is the universally unique ID for the exported object. These IDs have the form "01234567-89ab-cdef-0123-456789abcdef".

Remember to remove the config_dir/norm.log directory before restarting persistent Norm if you want it to forget registrations and settings made in previous invocations.

Starting Activatable Norm using Jini ERI

To run an activatable Norm, which stores information persistently and uses the activation system to restart itself, using Jini ERI for remote communication, run the following command.

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

You should remove the config_dir/group.log directory before running this command. Note that the activation system will restart the activatable Norm service as needed until Norm is shutdown.

Remember to remove the config_dir/norm.log directory before running this command if you want Norm to forget registrations and settings made in previous invocations.

This configuration uses the following additional files.

File `config_dir`/start-activatable-norm.config

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

import org.apache.river.start.ServiceDescriptor;
import org.apache.river.start.SharedActivatableServiceDescriptor;
import org.apache.river.start.SharedActivationGroupDescriptor;

org.apache.river.start {
    private static normCodebase = "http://your_host:http_port/norm-dl.jar"
       + " http://your_host:http_port/jsk-dl.jar";
    private static normPolicy = "config_dir/jsk-all.policy";
    private static normClasspath = "install_dir/lib/norm.jar";
    private static normConfig = "config_dir/activatable-norm.config";

    private static groupCodebase = "http://your_host:http_port/group-dl.jar";
    private static groupPolicy = "config_dir/jsk-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(
            normCodebase, normPolicy, normClasspath,
            "org.apache.river.norm.ActivatableNormServerImpl",
            groupPersistenceDirectory,
            new String[] { normConfig },
            true /* restart */)
    };
}

File `config_dir`/activatable-norm.config

Use this configuration source file to run activatable Norm using Jini ERI.

org.apache.river.norm {
    initialLookupGroups = new String[] { "your.group" };
    persistenceDirectory = "config_dir/norm.log";
}

See Also:: LeaseRenewalService

Package org.apache.river.norm

Package org.apache.river.norm Description

File config_dir/start-transient-jrmp-norm.config

File config_dir/transient-jrmp-norm.config

Starting Persistent Norm using JRMP

File config_dir/persistent-jrmp-norm.config

Starting Activatable Norm using JRMP

File config_dir/activatable-jrmp-norm.config

Stopping Activatable Norm

Starting Transient Norm using Jini ERI

File config_dir/transient-norm.config

Starting Persistent Norm using Jini ERI

File config_dir/persistent-norm.config

File config_dir/activatable-norm.config

File `config_dir`/start-transient-jrmp-norm.config

File `config_dir`/transient-jrmp-norm.config

File `config_dir`/persistent-jrmp-norm.config

File `config_dir`/activatable-jrmp-norm.config

File `config_dir`/transient-norm.config

File `config_dir`/persistent-norm.config

File `config_dir`/activatable-norm.config