| 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 | Description | 
|---|---|
| InternalNormException | 
 This exception denotes a problem with the local implementation of a
 Norm server. 
 | 
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 Apache River 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
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 
     | 
|   | 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   | 
| • |  
      activationSystemPreparer
     | |
|---|---|---|
|   | Type: |  ProxyPreparer
     | 
|   | Default: |  
        new 
     | 
|   | 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   | 
| • |  
      discoveryManager
     | |
|---|---|---|
|   | Type: |  DiscoveryManagement
     | 
|   | Default: | 
new  | 
|   | 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: |  
     | 
|   | 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: |  
     | 
|   | 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   | 
| • |  
      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   | 
| • |  
      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 
     | 
|   | 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 
     | 
|   | 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   | 
| • |  
      listenerPreparer
     | |
|---|---|---|
|   | Type: |  ProxyPreparer
     | 
|   | Default: |  
        new 
     | 
|   | 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   | 
| • |  
      locatorPreparer
     | |
|---|---|---|
|   | Type: |  ProxyPreparer
     | 
|   | Default: |  
        new 
     | 
|   | 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   | 
| • |  
      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 
     | 
|   | 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   | 
| • |  
      recoveredListenerPreparer
     | |
|---|---|---|
|   | Type: |  ProxyPreparer
     | 
|   | Default: |  
        new 
     | 
|   | 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   | 
| • |  
      recoveredLocatorPreparer
     | |
|---|---|---|
|   | Type: |  ProxyPreparer
     | 
|   | Default: |  
        new 
     | 
|   | 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   | 
| • |  
      serverExporter
     | |
|---|---|---|
|   | Type: |  Exporter
     | 
|   | Default: | 
// Activatable implementation new  | 
|   | 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: 
Loggers and Logging Levels
The Norm service implementation uses the Logger named org.apache.river.norm to log
information at the following logging levels: 
| 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
The examples below make the following assumptions: 
ClassServer class for this purpose.
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 Apache River release installation.
grant codebase "file:install_dir/lib/*" {
    permission java.security.AllPermission;
};
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 })
    };
}
import net.jini.jrmp.JrmpExporter;
org.apache.river.norm {
    initialLookupGroups = new String[] { "your.group" };
    serverExporter = new JrmpExporter();
}
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 })
    };
}
import net.jini.jrmp.JrmpExporter;
org.apache.river.norm {
    initialLookupGroups = new String[] { "your.group" };
    persistenceDirectory = "config_dir/norm.log";
    serverExporter = new JrmpExporter();
}
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 */)
    };
}
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);
}
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 */)
    };
}
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 })
    };
}
org.apache.river.norm {
    initialLookupGroups = new String[] { "your.group" };
}
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 })
    };
}
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 */)
    };
}
org.apache.river.norm {
    initialLookupGroups = new String[] { "your.group" };
    persistenceDirectory = "config_dir/norm.log";
}
LeaseRenewalServiceCopyright 2007-2013, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.