Provides the capability to deploy and monitor OperationalStrings.
The ProvisionMonitor can be run in one of 2 ways: (1) A transient ProvisionMonitor which loses state between executions, or (2) A persistent ProvisionMonitor, which maintains state between executions.
This document provides the following information about ProvisionMonitor

- Configuring ProvisionMonitor
- Examples for Running ProvisionMonitor

## Configuring ProvisionMonitor

The ProvisionMonitor package supports the following configuration entries; where each configuration entry name is associated with the component name org.jini.rio.monitor``

- faultDetectionHandler

  Type: | org.jini.rio.core.FaultDetectionHandler
  Default: | A new org.jini.rio.resources.client.StandardFaultDetectionHandler
  Description: | The faultDetectionHandler is used to configure the FaultDetectionHandler to determine reachability for the service.

- initialLookupGroups

  Type: | String[]
  Default: | All groups
  Description: | This entry will be read at initialization by a ProvisionMonitor to determine the initial set of multicast discovery groups the ProvisionMonitor should participate in. Any future changes to the set of discovery groups should be made via ProvisionMonitor 's admin proxy using the `JoinAdmin` interface.

- initialLookupLocators

  Type: | LookupLocator[]
  Default: | null
  Description: | This entry will be read at initialization by a ProvisionMonitor to determine the initial set of specific lookup services the ProvisionMonitor should register with. Any future changes to the set of discovery groups should be made via ProvisionMonitor 's admin proxy using the `JoinAdmin` interface.

- initialOpStrings

  Type: | String[]
  Default: | none
  Description: | An array of OperationalString files. The OperationalString file(s) will be loaded and managed at startup. Example : org.jini.rio.monitor { initialOpStrings = new String[]{"../opstrings/hello.xml"}; }

- initialOpStringLoadDelay

  Type: | long
  Default: | 5 seconds
  Description: | The amount of time (in milliseconds) to wait to load OperationalString files declared in the initialOpStrings property.

- dropDeployDir

  Type: | String
  Default: | ${RIO_HOME}/deploy
  Description: | This property is read at startup and defines the directory path that is used to enable hot deployment of OARs. The Provision Monitor will poll this directory at fixed intervals looking for files with a "oar" extension. For each OAR, the file will be moved to a subdirectory under the org.jini.rio.monitor.installDir directory and processed accordingly. If this directory does not exist it will be created.

- dropDeployDirScan

  Type: | long
  Default: | 5 seconds
  Description: | This property is read at startup and defines the amount of time (in milliseconds) dropdeployDir will be scanned for new entries

- installDir

  Type: | String
  Default: | ${RIO_HOME}/deploy
  Description: | This property is read at startup and defines the directory path that is used to install and service deployed OARs and application resources. OARs are installed to a subdirectory (as per the rules of OAR-Name) and extracted. If this directory does not exist it will be created.

- loginContext

  Type: | LoginContext
  Default: | Do not perform JAAS login
  Description: | Specifies the JAAS login context to use for performing a JAAS login and supplying the `Subject` to use when running the service. If this entry is not specified, no JAAS login is performed. This entry is obtained at service start and restart.

- logDirectory

  Type: | String
  Default: | none
  Description: | If the a log directory is being used, the value of this entry is the name of the directory that will be used to persist the ProvisionMonitor's state.

- opStringName

  Type: | String
  Default: | ""
  Description: | The name of the OperationalString the ProvisionMonitor is a part of

- opStringManagerExporter

  Type: | Exporter
  Default: | A new `BasicJeriExporter` with a `TcpServerEndpoint` created on a random port, a `BasicILFactory`, distributed garbage collection turned off, keep alive on. ``
  Description: | The exporter used to export the OpStringManager. The OpStringManager is a remote object which manages OperationalString instances. A new exporter is obtained every time an OpStringManager needs to export itself.

- provisionMonitorEventTaskPoolMinimum

  Type: | int
  Default: | 5
  Description: | The minimum amount of Thread instances to have in the pool of Thread instances used to notify interested clients of ProvisionMonitorEvent instances

- provisionMonitorEvent TaskPoolMaximum

  Type: | int
  Default: | 20
  Description: | The minimum amount of Thread instances to have in the pool of Thread instances used to notify interested clients of ProvisionMonitorEvent instances

- serviceComment

  Type: | String
  Default: | null
  Description: | The comment the ProvisionMonitor will use to construct a Comment Entry

- 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. 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 a ProvisionMonitorImpl needs to export itself.

- serviceName

  Type: | String
  Default: | ProvisionMonitor
  Description: | The name the ProvisionMonitor should use as a Name Entry, and for display purposes

- serviceResourceSelector

  Type: | ServiceResourceSelector
  Default: | RoundRobinSelector
  Description: | The ServiceResourceSelector provides a mechanism to select Cybernodes in a particular fashion

- instantiatorPreparer

  Type: | ProxyPreparer
  Default: | An instance of `BasicProxyPreparer` that does nothing
  Description: | ProxyPreparer for ServiceInstantiator proxies. The preparer should expect the net.jini.core.event.RemoteEventListener.notify method on the returned proxy.

- provisioner `LeasePeriodPolicy`

  Type: | com.sun.jini.landlord.LeasePeriodPolicy
  Default: | 5 minutes A new ``com.sun.jini.landlord.FixedLeasePeriodPolicy that allows leases up to 10 minutes with a default lease grant of 5 minutes
  Description: | Policy used to determine the length of initial grants and renewals of the leases for ServiceInstantiator instances

- activationIdPreparer

  Type: | {@link net.jini.security.ProxyPreparer}
  Default: | new {@link net.jini.security.BasicProxyPreparer}()
  Description: | Specifies the proxy preparer to use for the {@link java.rmi.activation.ActivationID}for this service, if this service is run as activatable

- activationSystemPreparer

  Type: | {@link net.jini.security.ProxyPreparer}
  Default: | new {@link net.jini.security.BasicProxyPreparer}()
  Description: | Specifies the proxy preparer to use for the {@link java.rmi.activation.ActivationSystem}proxy. During shutdown, this service calls the {@link java.rmi.activation.ActivationSystem#unregisterObject unregisterObject} method on the ActivationSystem instance returned from this preparer

## Examples for Running Provision Monitor

This section provides examples of running a Provision Monitor.

- Starting a Transient ProvisionMonitor
- Starting a Persistent ProvisionMonitor
- Starting an Activatable ProvisionMonitor

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

### Starting a Transient Provision Monitor

This startup invocation will use a configuration which starts a transient Provision Monitor

    $JAVA_HOME/bin/java -server -cp rio_home/lib/boot.jar:jini_home/lib/start.jar \
    -Djava.security.policy=rio_home/policy/policy.all \
    -Djava.protocol.handler.pkgs=net.jini.url -DRIO_HOME=rio_home \
    -DJINI_HOME=jini_home -DRIO_LOG_DIR=rio_log_dir com.sun.jini.start.ServiceStarter \
    rio_home/configs/start-monitor.config

The configuration file rio_home\configs\start-monitor.config is as follows:

    /*
     * This configuration is used by the com.sun.jini.start utility to start a
     * ProvisionMonitor, including an embedded Webster, JMX Connector Service and
     * a Jini Lookup Service
     */
    import java.net.URL;
    import org.jini.rio.boot.BootUtil;
    import org.jini.rio.boot.ServiceDescriptorUtil;
    import com.sun.jini.config.ConfigUtil;
    import com.sun.jini.start.NonActivatableServiceDescriptor;
    import com.sun.jini.start.ServiceDescriptor;

    com.sun.jini.start {
        jiniLibPath = "${JINI_HOME}${/}lib";
        jiniLibDLPath = "${JINI_HOME}${/}lib-dl";
        rioLibPath = "${RIO_HOME}${/}lib";
        deployDir = "${RIO_HOME}${/}deploy";
        policy = "${RIO_HOME}${/}policy${/}policy.all";

        reggieConfig = "${RIO_HOME}${/}config${/}reggie.config";
        monitorConfig = "${RIO_HOME}${/}config${/}monitor.config";

        serviceDescriptors = new ServiceDescriptor[] {
            /* Rio Webster, set to serve up 3 directories */
            ServiceDescriptorUtil.getWebster(policy,
                                             "0",
                                             new String[] {jiniLibDLPath,";",
                                                           jiniLibPath,";",
                                                           rioLibPath, ";",
                                                           deployDir}),

            /* JMX Connector */
            ServiceDescriptorUtil.getJMXConnector(policy, "-"),

            /* Jini Lookup Service */
            ServiceDescriptorUtil.getLookup(policy, reggieConfig),

            /* Rio Provision Monitor */
            ServiceDescriptorUtil.getMonitor(policy, monitorConfig)
        };

    }

### Starting a Persistent Provision Monitor

This startup invocation will use a configuration which starts a persistent Provision Monitor

    $JAVA_HOME/bin/java -server -cp rio_home/lib/boot.jar:jini_home/lib/start.jar \
    -Djava.security.policy=rio_home/policy/policy.all \
    -Djava.protocol.handler.pkgs=net.jini.url -DRIO_HOME=rio_home \
    -DJINI_HOME=jini_home -DRIO_LOG_DIR=rio_log_dir com.sun.jini.start.ServiceStarter \
    rio_home/configs/start-persistent-monitor.config

The configuration file rio_home\configs\start-persistent-monitor.config is as follows:

    /*
     * This configuration is used by the com.sun.jini.start utility to start a
     * Persistent ProvisionMonitor, including an embedded Webster, JMX Connector
     * Service and a Jini Lookup Service
     */
    import java.net.URL;
    import org.jini.rio.boot.BootUtil;
    import org.jini.rio.boot.ServiceDescriptorUtil;
    import com.sun.jini.start.ServiceDescriptor;

    com.sun.jini.start {
        jiniLibPath = "${JINI_HOME}${/}lib";
        jiniLibDLPath = "${JINI_HOME}${/}lib-dl";
        rioLibPath = "${RIO_HOME}${/}lib";
        deployDir = "${RIO_HOME}${/}deploy";
        policy = "${RIO_HOME}${/}policy${/}policy.all";

        reggieConfig = "${RIO_HOME}${/}config${/}reggie.config";
        monitorConfig = "${RIO_HOME}${/}config${/}monitor.config";
        overrideFile = "${RIO_HOME}${/}config${/}overrides${/}persistent-overrides.properties";
        overrides = BootUtil.parseOverrides(overrideFile,
                                            new String[]{"org.jini.rio.monitor"});

        serviceDescriptors = new ServiceDescriptor[] {
            /* Rio Webster, set to serve up 3 directories */
            ServiceDescriptorUtil.getWebster(policy,
                                             "9001",
                                             new String[] {jiniLibDLPath,";",
                                                           jiniLibPath,";",
                                                           rioLibPath, ";",
                                                           deployDir}),
            /* JMX Connector */
            ServiceDescriptorUtil.getJMXConnector(policy, "-"),

            /* Jini Lookup Service */
            ServiceDescriptorUtil.getLookup(policy, reggieConfig),

            /* Rio Provision Monitor */
            ServiceDescriptorUtil.getMonitor(policy, monitorConfig, overrides)
        };

    }

### Starting an Activatable Provision Monitor

This startup invocation will use a configuration which starts an activatable Provision Monitor

    $JAVA_HOME/bin/java -server -cp rio_home/lib/boot.jar:jini_home/lib/start.jar \
    -Djava.security.policy=rio_home/policy/policy.all \
    -Djava.protocol.handler.pkgs=net.jini.url -DRIO_HOME=rio_home \
    -DJINI_HOME=jini_home -DRIO_LOG_DIR=rio_log_dir com.sun.jini.start.ServiceStarter \
    rio_home/configs/start-activatable-monitor.config

The configuration file rio_home\configs\start-activatable-monitor.config is as follows :
/*
* This configuration is used by the com.sun.jini.start utility to start an
* Activatable Provision Monitor
*/
import org.jini.rio.boot.BootUtil;
import org.jini.rio.boot.RioActivatableServiceDescriptor;
import com.sun.jini.start.SharedActivatableServiceDescriptor;
import com.sun.jini.start.SharedActivationGroupDescriptor;
import com.sun.jini.start.ServiceDescriptor;
import java.net.URL;
com.sun.jini.start {
/* Configure the codebase */
static port = "9010";
policy = "${RIO_HOME}${/}policy${/}policy.all";
/* Configure the SharedGroup attributes */
groupCodebase = BootUtil.getCodebase("group-dl.jar", port);
groupClasspath = BootUtil.getClasspath(new String[] {
"${RIO_HOME}${/}lib${/}boot.jar",
"${JINI_HOME}${/}lib${/}start.jar",
"${JINI_HOME}${/}lib${/}jsk-platform.jar"
});
groupPersistenceDirectory = "${RIO_HOME}${/}logs/act-monitor.log";
/* System properties for the activation group */
sysProperties = new String[] {
"JINI_HOME", "${JINI_HOME}",
"RIO_HOME", "${RIO_HOME}",
"RIO_LOG_DIR", "${RIO_LOG_DIR}",
"java.protocol.handler.pkgs", "net.jini.url"
};
/* Load the overrides */
overrideFile = "${RIO_HOME}${/}config${/}overrides${/}persistent-overrides.properties";
static overrides = BootUtil.parseOverrides(overrideFile);
reggieCodebase = BootUtil.getCodebase(new String[] {"reggie-dl.jar",
"jsk-dl.jar"},
port);
reggieClasspath = "${JINI_HOME}${/}lib${/}reggie.jar";
/* Assemble Reggie configuration arguments */
reggieConfig = "${RIO_HOME}${/}config${/}reggie.config";
reggieConfigArgs = BootUtil.createConfigArgs(reggieConfig, overrides);
monitorCodebase = BootUtil.getCodebase(new String[] {
"monitor-dl.jar",
"rio-dl.jar",
"jsk-dl.jar"},
port);
monitorClasspath = "${RIO_HOME}${/}lib${/}monitor.jar";
/* Assemble Provision Monitor configuration arguments */
monitorConfig = "${RIO_HOME}${/}config${/}monitor.config";
monitorConfigArgs = BootUtil.createConfigArgs(monitorConfig, overrides);
serviceDescriptors = new ServiceDescriptor[] {
new SharedActivationGroupDescriptor(policy,
groupClasspath,
groupPersistenceDirectory,
null, /* serverCommand */
null, /* serverOptions */
sysProperties /* serverProperties */),
/* Rio Provision Monitor */
new RioActivatableServiceDescriptor(monitorCodebase,
policy,
monitorClasspath,
"org.jini.rio.monitor.ProvisionMonitorImpl",
groupPersistenceDirectory,
monitorConfigArgs,
true), /* restart */
/* Jini Lookup Service */
new SharedActivatableServiceDescriptor(reggieCodebase,
policy,
reggieClasspath,
"com.sun.jini.reggie.PersistentRegistrarImpl",
groupPersistenceDirectory,
reggieConfigArgs,
true) /* restart */
};
}