Rio Project 4.2 API Documentation

Package org.rioproject.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
ServiceBeanContainer	The ServiceBeanContainer defines the semantics required to instantiate service instances described by a ServiceElement
ServiceBeanContainerListener	Client interface allowing notification of service instantiations and discard lifecycle events
ServiceBeanDelegate	Defines the semantics of a class that the Cybernode delegates management of created service instances

Class Summary

CybernodeAdapter	Use as an interchange between the Cybernode and it's ServiceConsumer
CybernodeAdminImpl	The CybernodeAdminImpl class implements the ServiceAdmin interface providing administrative support for ServiceProducer implementations.
CybernodeAdminProxy	A CybernodeAdminProxy is a proxy for the CybernodeAdmin server.
CybernodeImpl	Implementation of a Cybernode
CybernodePermission	Permission that can be used to express the access control policy for an instance of an Cybernode server exported with a BasicJeriExporter.
Environment	The Environment class provides methods to query and setup the operational environment required by the Cybernode
JSBContainer	The JSBContainer implements support for a ServiceBeanContainer
JSBContextFactory	A ServiceBeanContextFactory which creates a JSBContext
JSBDelegate	The JSBDelegate provides loading and management services for a service which has been instantiated by a ServiceBeanContainer
MemoryCounter	Utility for getting memory footprint of objects.
PersistentServiceStatementManager	The PersistentServiceStatementManager provides an implementation of the ServiceStatementManager, reading and writing ServiceStatement instances to the file system
ServiceBeanLoader	The ServiceBeanLoader will load and create a ServiceBean.
ServiceBeanLoader.Result	Trivial class used as the return value by the load method.
ServiceConsumer	The ServiceConsumer manages the discovery, registration and update of the ResourceCapability component to discovered ProvisionManager instances
ServiceCostCalculator	Used to calculate resource costs for a service.
StagedDataManager	A utility to assist in downloading and installing data for a service.
StaticCybernode	A simple container for instantiating service beans.
TransientServiceStatementManager	The TransientServiceStatementManager provides an implementation of the ServiceStatementManager, setting and accessing ServiceStatement instances in a List

Package org.rioproject.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 provisioning agents, and provides a dynamic lightweight container to instantiate dynamic services.

This document provides the following information about Cybernode

• Configuring Cybernode
• Native Library Support
  

Configuring Cybernode

Cybernode supports the following configuration entries; where each configuration entry name is associated with the component name service.load and org.rioproject.cybernode

• Configuration entries specific to service.load
• Configuration entries specific to org.rioproject.cybernode

Configuration entries specific to service.load
The Cybernode supports the following configuration entries; where each configuration entry name is associated with the component name service.load. The following configuration entries provide the opportunity to declaratively modify the operational behavior of the Cybernode, for the creation of dynamic service beans

• forkedServiceWaitTime
  

  Type:	int
  Default:	60
  Description:	The amount of time to wait for a forked service (a service bean started in it's own JVM) to be created. The value is in seconds, where 60 seconds is the default. The minimum value for this property is 5 seconds, the maximum allowed 5 minutes. This value represents the maximum amount of time to wait. If the service is created prior to the timeout value the instantiation process returns immediately.

• serviceBeanContextFactory
  

  Type:	ServiceBeanContextFactory
  Default:	org.rioproject.cybernode.JSBContext
  Description:	The org.rioproject.core.jsb.ServiceBeanContextFactory defines the semantics to a class to produce a ServiceBeanContext

• serviceBeanFactory
  

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

  
  
• servicePreparer
  

  Type:	ProxyPreparer
  Default:	net.jini.security.BasicProxyPreparer
  Description:	The servicePreparer is used to prepare the newly created service proxy for use. The service proxy is created by the newly created service, and the servicePreparer is used to perform operations including trust verification and dynamic permission grants. By default the servicePreparer does nothing.

  
  

Configuration entries specific to org.rioproject.cybernode
The Cybernode supports the following configuration entries; where each configuration entry name is associated with the component name org.rioproject.cybernode. The following configuration entries provide the opportunity to declaratively modify the operational behavior of the Cybernode at startup

• activationIdPreparer

  Type:	ProxyPreparer
  Default:	new BasicProxyPreparer()
  Description:	Specifies the proxy preparer to use for the ActivationIDfor this service, if this service is run as activatable

• activationSystemPreparer

  Type:	ProxyPreparer
  Default:	new BasicProxyPreparer()
  Description:	Specifies the proxy preparer to use for the ActivationSystemproxy. 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.rioproject.cybernode { ... eightHours = 28800000; sixteenHours = 57600000; availablitySchedule = new Schedule(9, /* hour */ 0, /* minute */ eightHours, /* duration */ Schedule.INDEFINITE, /* repeats */ sixteenHours); }

• faultDetectionHandler

  Type:	org.rioproject.core.FaultDetectionHandler
  Default:	A new org.rioproject.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.rioproject.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:	"System-Core"
  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>/system/native. The Rio home directory is determined by the system property org.rioproject.home. If the org.rioproject.home property does not exist, the default location is <user-home-directory>/.rio/system/native
  Description:	A space or path delimiter string of directory names, used to create NativeLibrarySupport objects from. At startup this value is used to create NativeLibrarySupportobjects that represent native libraries found in these locations. Typically this value is sourced from the $RIO_NATIVE_DIR system property. If values are provided for the nativeLibDirectory property, they will be added to the values found in the $RIO_NATIVE_DIR system property.

• 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 specify 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 Cybernode 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 Cybernode 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 as follows: If the environment variable org.rioproject.home is set this is used as the Rio home directory, and the provision root is set as ${org.rioproject.home}/system/external, otherwise the Rio home directory will default to the home directory of the user, followed by the .rio subdirectory. For example: /user/home/rio/.rio/system/external
  Description:	The directory to provision external software to. This is the root directory where software may be installed by ServiceBean instances that 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.

• serviceComment
  

  Type:	String
  Default:	"Dynamic Agent"
  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

  
  
• serviceLogRootDirectory
  

  Type:	String
  Default:	System.getProperty("java.io.tmpdir")
  Description:	The root directory to create service logs for services that are forked. This directory will be used as follows: /<serviceLogRootDirectory>/service_logs/<normalized-opstring-name>/service-name-<instance-id> If the serviceLogRootDirectory directory does not exist it will be created. If the service_logs directory does not exist it will be created. The normalized-opstring-name is the name of the service's OperationalString, with all " " converted to "_". If the normalized-opstring-namedirectory does not exist it will be created. The service-name-<instance-id> is a file with the redirected output and error streams for the service. If the service name contains " ", they will be converted to "_" This property is read each time a service is forked.



• 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

• threadDeadlockCheck

  Type:	long
  Default:	5000
  Description:	The amount of time in milliseconds the SamplingWatch will periodically check the ThreadDeadlockMonitor for deadlocked threads. This value is obtained at startup. Setting this value to < 1000 will disable thread deadlock detection.

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 <rio-home-directory>/lib/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