This project has retired. For details please refer to its Attic page.
org.apache.river.reggie (Apache River v3.0.0 API Documentation)
Skip navigation links

Package org.apache.river.reggie

Provides implementations of ServiceRegistrar.

See: Description

Package org.apache.river.reggie Description

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

The name "Reggie" loosely refers to either implementation. The JAR file reggie.jar, included in the lib subdirectory of the Apache River release installation, contains the classes for both Reggie service implementations. The reggie-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 the 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 main proxy of an instance of either of the implementations above implements the ServiceRegistrar, Administrable and ReferentUuid interfaces. The admin proxy, obtainable by calling the getAdmin method of the main proxy, implements the DiscoveryAdmin, JoinAdmin, DestroyAdmin and ReferentUuid interfaces.

This document provides the following information about Reggie:

Configuring Reggie

Both TransientRegistrarImpl and PersistentRegistrarImpl service implementations obtain their configurations by calling ConfigurationProvider.getInstance with the specified configOptions and the class loader for the implementation class.

The configuration entries supported by the two implementations are listed below. PersistentRegistrarImpl supports all of the listed entries. TransientRegistrarImpl supports all listed entries except for the following persistence/activation-specific entries:

All configuration entries listed below have org.apache.river.reggie as their component.

activationIdPreparer
  Type: ProxyPreparer
  Default: new BasicProxyPreparer()
  Description: Specifies the proxy preparer to use for the ActivationID for this service, if this service is run as activatable. This service does not invoke any methods on the prepared ActivationID directly; however, it passes it to clients which may call its activate method if they need to reactivate this service. This entry is obtained at service start and restart if the service is running as activatable, and is only supported by PersistentRegistrarImpl.
activationSystemPreparer
  Type: ProxyPreparer
  Default: new BasicProxyPreparer()
  Description: Specifies the proxy preparer to use for the ActivationSystem proxy. During shutdown, this service calls the unregisterObject method on the ActivationSystem instance returned from this preparer. This entry is obtained at service start and restart if the service is running as activatable, and is only supported by PersistentRegistrarImpl.
discoveryConstraints
  Type: MethodConstraints
  Default: null
  Description: Specifies constraints to apply to the multicast request, multicast announcement and unicast discovery protocols. Multicast request constraints are derived by calling getConstraints on the obtained MethodConstraints instance with a Method object for the DiscoveryConstraints.multicastRequest() method; multicast announcement and unicast discovery constraints are similarly obtained by passing Method objects for the DiscoveryConstraints.multicastAnnouncement() and DiscoveryConstraints.unicastDiscovery() methods, respectively. A null value is interpreted as mapping all methods to empty constraints.

Reggie supports use of the following constraint types to control discovery behavior:

  • DiscoveryProtocolVersion: this constraint can be used to control which version(s) of the multicast request, multicast announcement, and unicast discovery protocols are used. Reggie defaults to using version one of the discovery protocols if this constraint is not specified and no other constraints, besides the ones listed here, are specified.
  • MulticastMaxPacketSize: this constraint can be used to control the maximum size of multicast announcement packets to send; it can also be used to specify the size of the buffer used to receive incoming multicast request packets. Reggie defaults to 512 bytes as the maximum size for announcements sent if this constraint is not specified for the DiscoveryConstraints.multicastAnnouncement() method. Reggie defaults to 512 bytes as the size of the buffer used to receive incoming multicast request packets if this constraint is not specified for the DiscoveryConstraints.multicastRequest() method.
  • MulticastTimeToLive: this constraint can be used to control the time to live (TTL) value set on outgoing multicast request packets. Reggie defaults to sending multicast announcements with a TTL of 15 if this constraint is not specified for the DiscoveryConstraints.multicastAnnouncement() method.
  • UnicastSocketTimeout: this constraint can be used to control the read timeout set on sockets over which unicast discovery is performed. In other words, it controls the amount of time Reggie waits to read data from a connected client attempting to discover Reggie. Reggie defaults to one minute as the read timeout on sockets over which unicast discovery is performed if this constraint is not specified for the DiscoveryConstraints.unicastDiscovery() method.
  • ConnectionRelativeTime: this constraint can be used to control the connection timeout set on sockets over which unicast discovery is performed. In other words, it controls the amount of time Reggie waits to connect to a client attempting to discover Reggie. If this constraint is not specified for the DiscoveryConstraints.unicastDiscovery() method, the connection attempt will block until the connection is established or an error occurs.
  • ConnectionAbsoluteTime: This constraint can be used to set a time after which reggie will cease to respond to discovery requests. By default, Reggie has no limitation on how long to continue responding to discovery requests.
Constraints other than those listed above are passed on to the underlying implementations of versions 1 and 2 of the discovery protocols. This entry is obtained at service start and restart.
discoveryManager
  Type: DiscoveryManagement
  Default:
new LookupDiscoveryManager(
    DiscoveryGroupManagement.NO_GROUPS,
    null, // locators
    null, // listener
    this) // config
  Description: Specifies DiscoveryManagement instance to use to discover other lookup services with which this service should register. 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: new Entry[0]
  Description: Specifies initial attributes to use when registering with lookup services (including self). The null value is equivalent to an empty Entry array. This service implementation provides two additional hardcoded attributes--a ServiceInfo instance with name field set to the string "Lookup", and a BasicServiceType instance with type field also set to "Lookup"--which are combined with the entry-specified attributes to obtain the total set of initial attributes with which to register. This entry is obtained once at service start; the current set of attributes (modifiable via the JoinAdmin methods of Reggie's admin object) is persisted across restarts.
initialLookupGroups
  Type: String[]
  Default: DiscoveryGroupManagement.NO_GROUPS
  Description: Specifies initial groups for determining the set of lookup services with which to register. This entry is obtained once at service start; the current set of lookup groups (modifiable via the JoinAdmin methods of Reggie's admin object) is persisted across restarts.
initialLookupLocators
  Type: LookupLocator[]
  Default: new LookupLocator[0]
  Description: Specifies initial list of locators indicating other lookup services with which to register. This entry is obtained once at service start; the current set of lookup locators (modifiable via the JoinAdmin methods of Reggie's admin object) is persisted across restarts.
initialMemberGroups
  Type: String[]
  Default: new String[]{ "" }
  Description: Specifies initial groups for this lookup service to be a member of. The value should not be null (which is equal to DiscoveryGroupManagement.ALL_GROUPS). This entry is obtained once at service start; the current set of member groups (modifiable via the DiscoveryAdmin methods of Reggie's admin object) is persisted across restarts.
initialUnicastDiscoveryPort
  Type: int
  Default: 0
  Description: Specifies the initial number of the port on which to listen for unicast discovery queries. If the port number is 0, then an arbitrary port is selected (with preference given to Constants.discoveryPort, if available). This entry is obtained once at service start; the current value (modifiable via the DiscoveryAdmin methods of Reggie's admin object) is persisted across restarts.
listenerPreparer
  Type: ProxyPreparer
  Default: new BasicProxyPreparer()
  Description: Specifies the proxy preparer to use for RemoteEventListeners registered with this service in calls to ServiceRegistrar.notify(net.jini.core.lookup.ServiceTemplate, int, net.jini.core.event.RemoteEventListener, java.rmi.MarshalledObject, long). During event notification, this service calls the notify method on RemoteEventListener instances returned from this preparer. This entry is obtained at service start and restart.
locatorPreparer
  Type: ProxyPreparer
  Default: new BasicProxyPreparer()
  Description: Specifies the proxy preparer to use for LookupLocators passed to this service in calls to the addLookupLocators, setLookupLocators and removeLookupLocators methods of its admin object. When registering with other 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.
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 or if it is specified with a value of null, no JAAS login is performed. This entry is obtained at service start and restart.
minMaxEventLease
  Type: long
  Default: 1000 * 60 * 30L
  Description: Specifies the lower bound for the maximum value allowed for event leases, in milliseconds. The maximum event lease granted is never less than the specified value, but may be greater than it if the expected average time between lease renewals (based on the current number of service and event registrations) would be less than the value of the minRenewalInterval configuration entry. This entry replaces in function the setMinMaxEventLease method of the RegistrarAdmin interface supported by previous implementations of Reggie, and is obtained at service start and restart.
minMaxServiceLease
  Type: long
  Default: 1000 * 60 * 5L
  Description: Specifies the lower bound for the maximum value allowed for service leases, in milliseconds. The maximum service lease granted is never less than the specified value, but may be greater than it if the expected average time between lease renewals (based on the current number of service and event registrations) would be less than the value of the minRenewalInterval configuration entry. This entry replaces in function the setMinMaxServiceLease method of the RegistrarAdmin interface supported by previous implementations of Reggie, and is obtained at service start and restart.
minRenewalInterval
  Type: long
  Default: 100L
  Description: Specifies the minimum average time to maintain between lease renewals, in milliseconds. This entry replaces in function the setMinRenewalInterval method of the RegistrarAdmin interface supported by previous implementations of Reggie, and is obtained at service start and restart.
multicastAnnouncementInterval
  Type: long
  Default: 1000 * 60 * 2L
  Description: Specifies the number of milliseconds to wait in between sending multicast announcement packets. This entry is consulted instead of the net.jini.discovery.announce system property used by previous implementations of Reggie. This entry is obtained at service start and restart.
multicastInterfaceRetryInterval
  Type: int
  Default: 1000 * 60 * 5
  Description: Specifies the number of milliseconds to wait in between retrying multicast interfaces for which initial attempts at enablement failed. Failed interfaces are retried at the given interval until they are successfully enabled; the overall set of multicast interfaces to use is configurable via the multicastInterfaces configuration entry. This entry is obtained at service start and restart.
multicastInterfaces
  Type: NetworkInterface[]
  Default: Use all network interfaces
  Description: Specifies the network interfaces to use to send and receive multicast request and announcement packets as part of multicast discovery. If no value is specified for this entry, then all network interfaces of the host are used. If the entry value is null, then the interface to which the operating system defaults is used. If the entry value is a zero-length array, then multicast discovery is disabled. This entry is consulted instead of the net.jini.discovery.interface system property used by previous implementations of Reggie, and is obtained at service start and restart.
multicastRequestSubjectChecker
  Type: ClientSubjectChecker
  Default: Do not check Subjects of multicast requests
  Description: Specifies the object to use for screening multicast requests based on their authenticated Subjects. This entry is obtained at service start and restart.
persistenceDirectory
  Type: String
  Default: Required: no default
  Description: Specifies the directory where the service's persistent state is recorded. This entry is obtained at service start and restart, and is only supported by PersistentRegistrarImpl, which requires it to be set.
persistenceSnapshotThreshold
  Type: int
  Default: 200
  Description: Specifies the minimum number of log updates before a new snapshot can be taken. This entry replaces the setLogToSnapshotThreshold method of the RegistrarAdmin interface supported by previous implementations of Reggie. It is obtained at service start and restart, and is only supported by PersistentRegistrarImpl.
persistenceSnapshotWeight
  Type: float
  Default: 10.0F
  Description: Specifies the weight factor by which the snapshot size is multiplied in order to determine when to take the next snapshot--when the number of log records exceeds the product of persistenceSnapshotWeight and the snapshot size and is larger than the persistenceSnapshotThreshold value, then a snapshot is taken. This entry replaces the setSnapshotWeight method of the RegistrarAdmin interface supported by previous implementations of Reggie. It is obtained at service start and restart, and is only supported by PersistentRegistrarImpl.
recoveredListenerPreparer
  Type: ProxyPreparer
  Default: new BasicProxyPreparer()
  Description: Specifies the proxy preparer to use for RemoteEventListeners recovered from the service's persistent state log. During event notification, this service calls the notify method on RemoteEventListener instances returned from this preparer. This entry is obtained at service start and restart, and is only supported by PersistentRegistrarImpl.
recoveredLocatorPreparer
  Type: ProxyPreparer
  Default: new BasicProxyPreparer()
  Description: Specifies the proxy preparer to use for LookupLocators recovered from the service's persistent state log. When registering with other 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, and is only supported by PersistentRegistrarImpl.
resourceIdGenerator
  Type: UuidGenerator
  Default: new UuidGenerator()
  Description: Specifies the generator for producing Uuids assigned to resources dispensed by the service, such as leases and service registrations. This entry is obtained at service start and restart.
serverExporter
  Type: Exporter
  Default:
// if non-activatable
new BasicJeriExporter(
    TcpServerEndpoint.getInstance(0),
    new BasicILFactory())

// if activatable
new ActivationExporter(
    activationID,
    new BasicJeriExporter(
        TcpServerEndpoint.getInstance(0),
        new BasicILFactory()))
  Description: Specifies the exporter to use to export this service. Note that this entry, while supported by both TransientRegistrarImpl and PersistentRegistrarImpl, has a different default value for PersistentRegistrarImpl in the activatable case. For the activatable case, the activationID value is passed in as the data argument in the call to Configuration.getEntry(String,String,Class,Object,Object). This entry is obtained at service start and restart.
serviceIdGenerator
  Type: UuidGenerator
  Default: new UuidGenerator()
  Description: Specifies the generator for producing service IDs assigned to services registering with this lookup service that do not already have service IDs. This generator is also used to produce the service ID for this lookup service. The Uuids returned by the generator are converted into ServiceID instances by extracting their 128-bit values and using them to construct corresponding ServiceIDs. This entry is obtained at service start and restart.
eventNotifierExecutor
  Type: ScheduledExecutorService
  Default: new ScheduledThreadPoolExecutor( poolSizeLimit, /* = (numberOfCPUCores / 0.3) */ new NamedThreadFactory("Reggie_Event_Notifier", false))
  Description: Specifies the object that pools and manages the threads used by this service to send event notifications. The shutdown method of this object will be called when the service is destroyed. This entry is obtained at service start and restart.
discoveryResponseExecutor
  Type: ExecutorService
  Default: new ThreadPoolExecutor( poolSizeLimit, /* = (numberOfCPUCores / 0.3) */ poolSizeLimit, /* Ignored */ 15L, TimeUnit.MINUTES, new LinkedBlockingQueue(), /* Unbounded Queue */ new NamedThreadFactory("Reggie_Discovery_Response", false) )
  Description: Specifies the object that pools and manages the threads used by this service to respond to discovery requests. The shutdownNow method of this object will be called when the service is destroyed. Sockets for remaining tasks will be closed after this method returns. This entry is obtained at service start and restart.
unexportTimeout
  Type: long
  Default: 1000 * 60 *2L
  Description: Specifies the maximum time in milliseconds to wait for in-progress calls to finish before forcibly unexporting Reggie during shutdown.
unexportWait
  Type: long
  Default: 1000L
  Description: Specifies the maximum time in milliseconds to wait between unexport attempts during shutdown while unexportTimeout has not expired.
unicastDiscoveryHost
  Type: String
  Default: InetAddress.getLocalHost().getHostName()
  Description: Specifies the host name for unicast discovery, which is advertised in multicast announcements and (protocol 2) unicast discovery responses. This entry is obtained at service start and restart.
unicastDiscoverySubjectChecker
  Type: ClientSubjectChecker
  Default: Do not check client Subject during unicast discovery
  Description: Specifies the object to use for screening unicast discovery attempts based on their authenticated client Subjects. This entry is obtained at service start and restart.

Other Configuration Entries

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

Access Control Permission Targets

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

Proxy Method Target Name
ServiceRegistrar.getEntryClasses getEntryClasses
ServiceRegistrar.getFieldValues getFieldValues
ServiceRegistrar.getGroups getMemberGroups
ServiceRegistrar.getLocator getLocator
ServiceRegistrar.getServiceTypes getServiceTypes
ServiceRegistrar.lookup(ServiceTemplate) lookup
ServiceRegistrar.lookup(ServiceTemplate, int) lookup
ServiceRegistrar.notify notify
ServiceRegistrar.register register
Administrable.getAdmin getAdmin
ServiceProxyAccessor.getServiceProxy getServiceProxy
ServiceRegistration.addAttributes addAttributes
ServiceRegistration.modifyAttributes modifyAttributes
ServiceRegistration.setAttributes setAttributes
Lease.cancel (for event leases) cancelEventLease
Lease.renew (for event leases) renewEventLease
Lease.cancel (for service leases) cancelServiceLease
Lease.renew (for service leases) renewServiceLease
LeaseMap.cancelAll cancelLeases
LeaseMap.renewAll renewLeases
DiscoveryAdmin.addMemberGroups addMemberGroups
DiscoveryAdmin.getMemberGroups getMemberGroups
DiscoveryAdmin.getUnicastPort getUnicastPort
DiscoveryAdmin.removeMemberGroups removeMemberGroups
DiscoveryAdmin.setMemberGroups setMemberGroups
DiscoveryAdmin.setUnicastPort setUnicastPort
JoinAdmin.addLookupAttributes addLookupAttributes
JoinAdmin.addLookupGroups addLookupGroups
JoinAdmin.addLookupLocators addLookupLocators
JoinAdmin.getLookupAttributes getLookupAttributes
JoinAdmin.getLookupGroups getLookupGroups
JoinAdmin.getLookupLocators getLookupLocators
JoinAdmin.modifyLookupAttributes modifyLookupAttributes
JoinAdmin.removeLookupGroups removeLookupGroups
JoinAdmin.removeLookupLocators removeLookupLocators
JoinAdmin.setLookupGroups setLookupGroups
JoinAdmin.setLookupLocators setLookupLocators
DestroyAdmin.destroy destroy
ProxyTrust.getProxyVerifier getProxyVerifier

Loggers and Logging Levels

Both PersistentRegistrarImpl and TransientRegistrarImpl log diagnostic information to the Logger named org.apache.river.reggie. The server-side components of each implementation log information at the following logging levels:

org.apache.river.reggie (server-side)
Level Description
SEVERE Exceptions that prevent service startup
WARNING Exceptions that, while non-fatal, indicate compromised service functionality, such as failures to persist or recover state, or to send multicast announcements on an explicitly configured interface
INFO Service start, restart, or destruction events, as well as exceptions of moderate severity, such as failures to send event notifications or multicast announcements, or to establish a unicast discovery connection
CONFIG Changes made to the service through administrative interfaces, as well as high-level service configuration information, such as the persistence directory (if any) and multicast interfaces (if any) used
HANDLED Minor exceptions involving activation, discovery, event handling, and shutdown that are handled internally by the service, and not reflected to callers
FINE Changes in service state, such as the establishment, expiration, and cancellation of service and event listener registrations, as well as invalid service ID values
FINER Persistent state log operations

The service proxies for PersistentRegistrarImpl and TransientRegistrarImpl log information at the following logging levels:

org.apache.river.reggie (service proxy)
Level Description
WARNING Invalid service IDs used for registration
INFO Service item unmarshalling exceptions

System Properties

Both TransientRegistrarImpl and PersistentRegistrarImpl service implementations support the following system property:

org.apache.river.reggie.enableImplToStubReplacement
  Description: This system property is interpreted as a boolean value (see Boolean.getBoolean). If true, then JRMP impl-to-stub replacement will be attempted on the service proxy objects contained in ServiceItems passed to the register method of Reggie's proxy. By default, this behavior is not enabled--it is provided as a transitional measure for services that depend on JRMP impl-to-stub replacement when registering with Reggie.

Examples for Running Reggie

This section provides examples of running Reggie in various configurations.

Assumptions for Running the Examples

The examples below make the following assumptions:

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

Setting Discovery Constraints

Discovery constraints for Reggie can be set by specifying a discoveryConstraints entry under the org.apache.river.reggie component. For example, to specify that Reggie must wait at most five seconds to connect to a client attempting discovery and at most three minutes to read data from a connected client attempting discovery, the following entry must be added to Reggie's configuration source file under the org.apache.river.reggie component:
discoveryConstraints = new BasicMethodConstraints(
    new MethodDesc[] {
        new MethodDesc("unicastDiscovery", 
            new InvocationConstraints(
                new InvocationConstraint[] {
                    new ConnectionRelativeTime(5000),
                    new UnicastSocketTimeout(180000) // 3*60*1000
                }, 
                null
            )
        )    
    }
);

As another example, to specify that Reggie must use version two of of the multicast request, multicast announcement, and unicast discovery protocols, the following entry must be added to Reggie's configuration source file under the org.apache.river.reggie component.

discoveryConstraints = new BasicMethodConstraints(
    new InvocationConstraints(DiscoveryProtocolVersion.TWO, null)
);

Starting Transient Reggie using JRMP

To run a transient Reggie, 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-reggie.config

This configuration uses the following files.

File config_dir/jsk-all.policy

Use this security policy file for starting and running all Reggie 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;
};

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

Use this configuration source file to start transient Reggie 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/reggie-dl.jar"
        + " http://your_host:http_port/jsk-dl.jar";
    private static policy = "config_dir/jsk-all.policy";
    private static classpath = "install_dir/lib/reggie.jar";
    private static config = "config_dir/transient-jrmp-reggie.config";

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

File config_dir/transient-jrmp-reggie.config

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

import net.jini.jrmp.JrmpExporter;

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

Starting Persistent Reggie using JRMP

To run a persistent Reggie, 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-reggie.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-reggie.config

Use this configuration source file to start persistent Reggie 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/reggie-dl.jar"
        + " http://your_host:http_port/jsk-dl.jar";
    private static policy = "config_dir/jsk-all.policy";
    private static classpath = "install_dir/lib/reggie.jar";
    private static config = "config_dir/persistent-jrmp-reggie.config";

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

File config_dir/persistent-jrmp-reggie.config

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

import net.jini.jrmp.JrmpExporter;

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

Starting Activatable Reggie using JRMP

To run an activatable Reggie, 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-reggie.config

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

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

This configuration uses the following additional files.

File config_dir/start-activatable-jrmp-reggie.config

Use this configuration source file to start activatable Reggie 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 reggieCodebase = "http://your_host:http_port/reggie-dl.jar"
        + " http://your_host:http_port/jsk-dl.jar";
    private static reggiePolicy = "config_dir/jsk-all.policy";
    private static reggieClasspath = "install_dir/lib/reggie.jar";
    private static reggieConfig = "config_dir/activatable-jrmp-reggie.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(
            reggieCodebase, reggiePolicy, reggieClasspath,
            "org.apache.river.reggie.PersistentRegistrarImpl",
            groupPersistenceDirectory,
            new String[] { reggieConfig },
            true /* restart */)
    };
}

File config_dir/activatable-jrmp-reggie.config

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

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

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

Stopping Activatable Reggie

To destroy the activation group running an activatable Reggie, 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-reggie.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 Reggie's administrable interface, or to remove the config_dir/reggie.log directory after destroying the activation group.

This command uses the following additional file.

File config_dir/stop-activatable-reggie.config

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

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 Reggie using Jini ERI

To run a transient Reggie, 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-reggie.config

This configuration uses the following additional files.

File config_dir/start-transient-reggie.config

Use this configuration source file to start transient Reggie 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/reggie-dl.jar"
        + " http://your_host:http_port/jsk-dl.jar";
    private static policy = "config_dir/jsk-all.policy";
    private static classpath = "install_dir/lib/reggie.jar";
    private static config = "config_dir/transient-reggie.config";

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

File config_dir/transient-reggie.config

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

org.apache.river.reggie {
    initialMemberGroups = new String[] { "your.group" };
}

Starting Persistent Reggie using Jini ERI

To run a persistent Reggie, 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-reggie.config

This configuration uses the following additional files.

File config_dir/start-persistent-reggie.config

Use this configuration source file to start persistent Reggie 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/reggie-dl.jar"
        + " http://your_host:http_port/jsk-dl.jar";
    private static policy = "config_dir/jsk-all.policy";
    private static classpath = "install_dir/lib/reggie.jar";
    private static config = "config_dir/persistent-reggie.config";

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

File config_dir/persistent-reggie.config

Use this configuration source file to run persistent Reggie 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.reggie {
    initialMemberGroups = new String[] { "your.group" };
    persistenceDirectory = "config_dir/reggie.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/reggie.log directory before restarting persistent Reggie if you want it to forget registrations and settings made in previous invocations.

Starting Activatable Reggie using Jini ERI

To run an activatable Reggie, 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-reggie.config

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

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

This configuration uses the following additional files.

File config_dir/start-activatable-reggie.config

Use this configuration source file to start activatable Reggie 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 reggieCodebase = "http://your_host:http_port/reggie-dl.jar"
        + " http://your_host:http_port/jsk-dl.jar";
    private static reggiePolicy = "config_dir/jsk-all.policy";
    private static reggieClasspath = "install_dir/lib/reggie.jar";
    private static reggieConfig = "config_dir/activatable-reggie.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(
            reggieCodebase, reggiePolicy, reggieClasspath,
            "org.apache.river.reggie.PersistentRegistrarImpl",
            groupPersistenceDirectory,
            new String[] { reggieConfig },
            true /* restart */)
    };
}

File config_dir/activatable-reggie.config

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

org.apache.river.reggie {
    initialMemberGroups = new String[] { "your.group" };
    persistenceDirectory = "config_dir/reggie.log";
}
See Also:
net.jini.core.lookup, ServiceRegistrar
Skip navigation links

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