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

## Package org.jini.rio.cybernode

A Cybernode represents a compute resource as a service available through the network, offering dynamic allocation and provisioning capabilities.

See:
Description

Interface Summary
Cybernode | A Cybernode represents a compute resource as a service available through the network.
CybernodeAdmin | CybernodeAdmin defines methods used to administer a Cybernode
CybernodeImplMBean | Provides a standard MBean to use when administering the Cybernode using JMX

Class Summary
CybernodePermission | Permission that can be used to express the access control policy for an instance of an Cybernode server exported with a `BasicJeriExporter`.
ServiceCostCalculator | Used to calculate resource costs for a service.

## Package org.jini.rio.cybernode Description

A Cybernode represents a compute resource as a service available through the network, offering dynamic allocation and provisioning capabilities. The Cybernode represents the capabilities of compute resource through quantitative & qualitative mechanisms. Cybernode instances dynamically discover and enlist with dynamic provisioning agents, and provides a dynamic lightweight container to instantiate dynamic services.
The Cybernode can be run in one of 2 ways: (1) A transient Cybernode which loses state between executions, or (2) A persistent Cybernode, which maintains state between executions.
This document provides the following information about Cybernode

- Configuring Cybernode
- Examples for Running Cybernode
- Native Library Support

## Configuring Cybernode

Cybernode supports the following configuration entries; where each configuration entry name is associated with the component name org.jini.rio.cybernode``

- 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

- 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

- availabilitySchedule

  Type: | `Schedule`
  Default: | null
  Description: | Specifies the availability schedule for a Cybernode. If a Schedule is provided, the Cybernode will register and unregister to discovered `ProvisionMonitor` instances based on the declared schedule. For example, if the Cybernode were to be available every day from 9 to 5, the following schedule would be declared : org.jini.rio.cybernode { ... eightHours = 28800000; sixteenHours = 57600000; availablitySchedule = new Schedule(9, /* hour */ 0, /* minute */ eightHours, /* duration */ Schedule.INDEFINITE, /* repeats */ sixteenHours); }

- 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 Cybernode to determine the initial set of multicast discovery groups the Cybernode should participate in. Any future changes to the set of discovery groups should be made via Cybernode 's admin proxy using the `JoinAdmin` interface.

- initialLookupLocators

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

- initialServices

  Type: | String[]
  Default: | null
  Description: | An array of OperationalString files. The OperationalString file(s) will be loaded at startup, creating a service instance for each service bean declared in the loaded OperationalString(s). The implications of using this property are that the services loaded are not managed by the Provision Manager, resulting in no management for fault detection & recovery, or declared behavioral policies which require the assistance of the `OperationalStringManager` (such as the ScalablePolicyHandler or RelocationPolicyHandler). Example of using the declaration: org.jini.rio.cybernode { initialServices = new String[]{"../opstrings/hello.xml"}; }

- 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 Cybernode 's state. Obtained at persistent 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, no JAAS login is performed. This entry is obtained at service start and restart.

- opStringName

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

- nativeLibDirectory

  Type: | String[]
  Default: | The default directory to load native libraries from is <rio-home-directory>/native. The Rio home directory is determined by the system property org.jini.rio.home. If the org.jini.rio.home property does not exist, the default location is <user-home-directory>/.rio/native
  Description: | An array of directory names to load native libraries from. At startup this value is used to create org.jini.rio.qos.capability.software.NativeLibrarySupport objects which represent native libraries found in these locatons

- provisionEnabled

  Type: | boolean
  Default: | false
  Description: | ServiceBean instances may require external software to be resident on compute resource the Cybernode represents. Setting this property will allow the Cybernode to install external software defined by ServiceBeans

- provisionerLeaseDuration

  Type: | long
  Default: | 30 minutes
  Description: | The value is rad at startup and used to specificy the duration of the Lease requested (in seconds) by the ServiceInstantiator to ProvisionManager instances. The value is in the range of 10 seconds to a Long.MAX_VALUE

- provisionerPreparer

  Type: | ProxyPreparer
  Default: | An instance of `BasicProxyPreparer` that does nothing
  Description: | ProxyPreparer for ProvisionManager proxies. The preparer should expect the `register and update` methods to be called on the returned proxy.

- provisionerRetryCount

  Type: | int
  Default: | 3
  Description: | The number of times the ServiceInstantiator consumer should attempt to reconnect to a ProvisionManager instance if that instance could not be reached for Lease renewal.

- provisionerRetryDelay

  Type: | long
  Default: | 1 second
  Description: | The length of time (in seconds) the ServiceInstantiator should wait before attempting to reconnect to a ProvisionManager instance if that instance could not be reached for LeaseRenewal

- provisionRoot

  Type: | String
  Default: | If no provision root is provided, the Cybernode will establish the provision root using the home directory of the user, followed by the .rio subdirectory and add an external directory. For example: `/usr/home/rio/.rio/external`
  Description: | The directory to provision external software to. This is the root directory where software may be installed by ServiceBean instances which require external software to be resident on compute resource the Cybernode represents

- recordAge

  Type: | long
  Default: | 30. If no record age is provided, the Cybernode will remove persisted ServiceStatement instances if they are over 30 days old
  Description: | The age a persisted ServiceStatement instance should remain on the filesystem before its removed. Persisted ServiceStatement instances will be removed if they are older then the alloted age and if all the ServiceRecord instances within the ServiceStatement are INACTIVE. The value provided represents the number of days a record can age before its removed. If records should live forever, then a value of 0 should be provided

- recordDirectory

Type: | String
Default: | If no record directory root is provided, the Cybernode will establish the record directory root using the home directory of the user, followed by the .rio subdirectory and add a records directory. For example: `/usr/home/rio/.rio/records`
Description: | The directory to persist ServiceStatement instances to. ServiceStatement instances are created to record a ServiceBean's instantiation and resource usage.

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

- serviceBeanFactory

  Type: | `ServiceBeanFactory`
  Default: | org.jini.rio.jsb.JSBLoader
  Description: | The org.jini.rio.core.jsb.ServiceBeanFactory defines the semantics to create a service which wil be hosted by the Cybernode. The implementation of the org.jini.rio.core.jsb.ServiceBeanFactory creates a service implementation and proxy to communicate with the service. Implementations of this interface may provide support for interoperbility with external systems and native applications. See `ServiceBeanFactory` and `JSBLoader`

- serviceComment

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

- serviceCostCalculator

  Type: | `ServiceCostCalculator`
  Default: | new `ServiceCostCalculator`()
  Description: | The serviceCostCalculator provides the support needed to determine an instantiated service's `ResourceCost`. This entry is obtained at service startup (each time a service is instantiated) and loaded from the Cybernode's configuration. Configurations wanted to customize this behavior should extend the ServiceCostCalculator class

- serviceLimit

  Type: | int
  Default: | 500
  Description: | The serviceLimit indicates the maximum amount of ServiceBean instances the Cybernode instance will instantiate

- serviceName

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

- serviceRecordUpdateTaskTimer

  Type: | long
  Default: | 60 seconds
  Description: | The serviceRecordUpdateTaskTimer specifies the amount of time (in seconds) between ServiceRecordUpdateTask scheduling. A ServiceRecordUpdateTask is scheduled at repeated fixed-rate execution, beginning after the specified delay. Subsequent executions take place at approximately regular intervals, separated by the specified period. ServiceStatement instances are updated with ServiceRecords for active ServiceBeans.

- serviceSecurityPolicy

  Type: | String
  Default: | If no serviceSecurityPolicy is provided the policy file used will the the policy set for the VM, obtained from System.getProperty("java.security.policy");
  Description: | The security policy to apply to services which are instantiated by the Cybernode. The Cybernode uses a com.sun.jini.start.AggregatePolicyProvider which associates security sub-policies with context class loaders

- serviceStatementManager

  Type: | ServiceStatementManager
  Default: | If no ServiceStatementManager is provided a TransientServiceStatementManager will be used
  Description: | The ServiceStatementManager to use for managing ServiceStatements. This value must be suitable for Class.forName() use.

- serviceTerminationOnUnregister

  Type: | boolean
  Default: | true
  Description: | If the Cybernode has been configured with an availability Schedule, and the Cybernode removes itself as an asset, this property determines whether instantiated services should be terminated upon unregistration

- slaThresholdTaskPoolMaximum

  Type: | int
  Default: | 20
  Description: | The maximum amount of Thread instances to have in the pool of Thread instances used to notify interested clients of SLA Thresholds which have been set for the Cybernode and crossed

- slaThresholdTaskPoolMinimum

  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 SLA Thresholds which have been set for the Cybernode and crossed

## Examples for Running Cybernode

This section provides examples of running a Cybernode.

- Starting a Transient Cybernode
- Starting a Persistent Cybernode
- Starting an Activatable Cybernode

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

### Starting a Transient Cybernode

This startup invocation will use a configuration which starts a transient Cybernode

    $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-cybernode.config

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

    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";
        policy = "${RIO_HOME}${/}policy${/}policy.all";

        cybernodeConfig = "${RIO_HOME}${/}config${/}cybernode.config";

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

            /* Rio Cybernode */
            ServiceDescriptorUtil.getCybernode(policy, cybernodeConfig)

        };

    }

### Starting a Persistent Cybernode

This startup invocation will use a configuration which starts a persistent Cybernode

    $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-cybernode.config

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

    /*
     * This configuration is used by the com.sun.jini.start utility to start a
     * Persistent Cybernode, including an embedded Webster and a JMX Connector
     * 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";
        policy = "${RIO_HOME}${/}policy${/}policy.all";

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

        cybernodeLogDir = "${RIO_HOME}${/}logs${/}cybernode.log";

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

            /* Rio Cybernode */
            ServiceDescriptorUtil.getCybernode(policy, cybernodeConfig, overrides)
        };
    }

### Starting an Activatable Cybernode

This startup invocation will use a configuration which starts an activatable Cybernode

    $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-cybernode.config

The configuration file rio_home\config\start-activatable-cybernode.config is as follows:
/*
* This configuration is used by the com.sun.jini.start utility to start an
* Activatable Cybernode
*/
import java.net.URL;
import org.jini.rio.boot.BootUtil;
import org.jini.rio.boot.RioActivatableServiceDescriptor;
import com.sun.jini.start.SharedActivationGroupDescriptor;
import com.sun.jini.start.ServiceDescriptor;
com.sun.jini.start {
/* Configure the codebase */
static port = "9010";
policy = "${RIO_HOME}${/}policy${/}policy.all";
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-cybernode.log";
/* System properties for the activation group */
sysProperties = new String[] {
"JINI_HOME", "${JINI_HOME}",
"RIO_HOME", "${RIO_HOME}",
"RIO_NATIVE_DIR", "${RIO_NATIVE_DIR}",
"org.jini.rio.home", "${RIO_HOME}",
"RIO_LOG_DIR", "${RIO_LOG_DIR}",
"java.protocol.handler.pkgs", "net.jini.url"
};
/* Cybernode configuration attributes */
cybernodeClasspath = "${RIO_HOME}${/}lib${/}cybernode.jar";
cybernodeCodebase = BootUtil.getCodebase(new String[] {
"cybernode-dl.jar",
"rio-dl.jar",
"jsk-dl.jar",
"platform-capabilities.jar"},
port);
/* Load the overrides and assemble configuration arguments */
overrideFile = "${RIO_HOME}${/}config${/}overrides${/}persistent-overrides.properties";
static overrides = BootUtil.parseOverrides(overrideFile);
cybernodeConfig = "${RIO_HOME}${/}config${/}cybernode.config";
cybernodeConfigArgs = BootUtil.createConfigArgs(cybernodeConfig, overrides);
serviceDescriptors = new ServiceDescriptor[] {
new SharedActivationGroupDescriptor(policy,
groupClasspath,
groupPersistenceDirectory,
null, /* serverCommand */
null, /* serverOptions */
sysProperties /* serverProperties */),
/* Rio Cybernode */
new RioActivatableServiceDescriptor(cybernodeCodebase,
policy,
cybernodeClasspath,
"org.jini.rio.cybernode.CybernodeImpl",
groupPersistenceDirectory,
cybernodeConfigArgs,
true) /* restart */
};
}

## Native Library Support

The Cybernode provides the capability to load native libraries. Loading native libraries can only be accomplished successfully if your library path is set up correctly.
The Cybernode uses a directory where native libraries can be placed so they can be loaded by ServiceBean, PlatformCapability and MeasurableCapability instances.
The default directory to load native libraries from is <user-home-directory>/.rio/native

### Setting Library Path

The Cybernode starter scripts in rio_home\bin include declarations for setting the library path. If you are starting an activatable Cybernode, the library path needs to be set when the RMI Activation System is started. Examples of setting the library path across operating systems follow:

- Unix

      $ export LD_LIBRARY_PATH=<rioHome>/native

- OS X 10.3.x

      $ export DYLD_LIBRARY_PATH=<rioHome>/native

- DOS shell (Windows NT/2000/XP)

      > set PATH=%PATH%;<rioHome>\native

### Possible Errors

If you see a java.lang.UnsatisfiedLinkError exception, then one of the following may be the cause:

1. You don't have your library path set up correctly
2. The directory you setup for the library path did not exist when the VM started. Make sure the directory exists and retry

``

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

Copyright © Project Rio.