Rio Project 4.2 API Documentation

org.rioproject.system.capability
Class PlatformCapability

java.lang.Object
  org.rioproject.system.capability.PlatformCapability

All Implemented Interfaces:

Serializable, ResourceCostProducer, PlatformCapabilityMBean

Direct Known Subclasses:

ByteOrientedDevice, ConnectivityCapability, OperatingSystem, ProcessorArchitecture, SoftwareSupport

public class PlatformCapability
extends Object
implements PlatformCapabilityMBean, ResourceCostProducer, Serializable

A PlatformCapability defines a specific type of mechanism or quality associated with a compute resource, and is used to define base platform capabilities and resources. These capabilities allow better control over resources and better provisioning behaviour. In turn, this leads to optimal ServiceBean compute ability.

PlatformCapability attributes will be stored as (key, value) pairs in a HashMap and tested for supportability against SystemRequirements.SystemComponent attributes. Attributes obtained from the SystemRequirement class will be tested for supportability using regular expression matching.

If the SystemRequirement class contains a VERSION requirement, the required version value is processed as follows:

The VERSION determines which version of the PlatformCapability is required. Without this key set, your service may not launch with the desired version of the PlatformCapability. The "Version" value can use the asterisk (*) or plus (+) symbols to determine version requirements.

Requirement	Support Criteria
1.2.7	Specifies an exact version
2*	Supported for all minor versions of 2
3.4*	Supported for all minor versions of 3.4, including 3.4
1.2+	Supported for version 1.2 or above

Version requirements are expected to be a "." separated String of integers. Character values are ignored. For example; a version declaration of "2.0-M3" will be processed as "2.0.0.3"

Author:

Dennis Reedy

See Also:

Serialized Form

Field Summary

protected Hashtable<String,Object>	capabilities Map of platform capability key and values
protected String	description A description of the PlatformCapability
static String	DESCRIPTION Description information for the capability
protected static Logger	logger A suitable Logger
static String	MANUFACTURER Manufacturer information for the capability
static String	MODEL Model information for the capability
static String	NAME Name information for the capability
static String	NATIVE_LIBS Native Libraries Key.
static int	PROVISIONABLE Indicates that the PlatformCapability may be provisioned
static int	STATIC Indicates that the PlatformCapability must be installed
static String	VENDOR Vender information for the capability
static String	VERSION Version information for the capability

Constructor Summary

PlatformCapability()

Method Summary

void	addDownloadRecord(DownloadRecord record) Add a DownloadRecord instance for the PlatformCapability
void	addStagedSoftware(StagedSoftware... software) Add StagedSoftware for the PlatformCapability.
ResourceCost	calculateResourceCost(double units, long duration) Calculate the cost based on the units provided.
void	clearAll() Clear all platform capability mappings
void	decrementUsage()
void	define(String key, Object value) Define a platform capability mapping
void	defineAll(Map<String,Object> map) Define all platform capability mappings to the platform capability Map
boolean	equals(Object obj) A PlatformCapability is equal to another PlatformCapability if they are the same class and their capabilities maps are equal
Map<String,Object>	getCapabilities() The collection of key,value pairs this PlatformCapability has been created with
String[]	getClassPath() Get the classpath for the PlatformCapability
String	getConfigurationFile()
String	getDescription() Get the description associated with the PlatformCapability
DownloadRecord[]	getDownloadRecords() Get the DownloadRecord instances for the PlatformCapability
URL[]	getLoadableClassPath() Get the loadable classpath for the PlatformCapability.
String	getName() Get the name of this PlatformCapability
String	getPath() Get the path of the PlatformCapability, where it is located on the filesystem
String[]	getPlatformKeys() Get the keys for the platform capability
ResourceCostModel	getResourceCostModel() Get the ResourceCostModel for the PlatformCapability
StagedSoftware[]	getStagedSoftware() Get the StagedSoftware for the PlatformCapability
int	getType() Get the type of PlatformCapability
int	getUsageCount()
Object	getValue(String key) Get the value associated with the key in the platform capability mapping.
protected boolean	hasBasicSupport(String name, String className) Determine basic supportability
int	hashCode() Override hashCode to return the hashCode of the capabilities Map
void	incrementUsage()
void	loadResources() Allows the PlatformCapability to load any required native libraries as determined by values in the NativeLibsKey using the System.loadLibrary method.
protected boolean	matches(String input, String value) Matching semantics are accomplished using pattern matching with regular expressions
boolean	remove(String key) Remove a defined platform capability mapping
void	setClassPath(String[] classpath) Set the classpath of the PlatformCapability
void	setConfigurationFile(String configurationFile)
void	setDescription(String description) Set the description associated with the PlatformCapability
void	setPath(String path) Set the path of the PlatformCapability
void	setResourceCostModel(ResourceCostModel costModel) Set the ResourceCostModel for the PlatformCapability
protected void	setType(int type) Set the type of this record to be either STATIC or PROVISIONABLE
boolean	supports(PlatformCapability requirement) Deprecated.
boolean	supports(SystemRequirements.SystemComponent requirement) Determine if the provided SystemRequirements.SystemComponent can be supported.
String	toString() String representation of a PlatformCapability
protected boolean	versionSupported(String requiredVersion, String configuredVersion) Determine if versions are supported

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

MANUFACTURER

public static final String MANUFACTURER

Manufacturer information for the capability

See Also:

Constant Field Values

MODEL

public static final String MODEL

Model information for the capability

See Also:

Constant Field Values

NAME

public static final String NAME

Name information for the capability

See Also:

Constant Field Values

VENDOR

public static final String VENDOR

Vender information for the capability

See Also:

Constant Field Values

VERSION

public static final String VERSION

Version information for the capability

See Also:

Constant Field Values

DESCRIPTION

public static final String DESCRIPTION

Description information for the capability

See Also:

Constant Field Values

NATIVE_LIBS

public static final String NATIVE_LIBS

Native Libraries Key. If value(s) are provided for this key they will be loaded when the loadResources method is invoked. If this key is provided value(s) must be separated by a ":" delimeter. For example lib1:lib2:lib3

See Also:

Constant Field Values

STATIC

public static final int STATIC

Indicates that the PlatformCapability must be installed

See Also:

Constant Field Values

PROVISIONABLE

public static final int PROVISIONABLE

Indicates that the PlatformCapability may be provisioned

See Also:

Constant Field Values

capabilities

protected final Hashtable<String,Object> capabilities

Map of platform capability key and values

description

protected String description

A description of the PlatformCapability

logger

protected static final Logger logger

A suitable Logger

Constructor Detail

PlatformCapability

public PlatformCapability()

Method Detail

setPath

public void setPath(String path)

Set the path of the PlatformCapability

Parameters:

path - The path on an accessible filesystem where the PlatformCapability is installed

getPath

public String getPath()

Get the path of the PlatformCapability, where it is located on the filesystem

Specified by:

getPath in interface PlatformCapabilityMBean

Returns:

The path on an accessible filesystem where the PlatformCapability is installed

setClassPath

public void setClassPath(String[] classpath)

Set the classpath of the PlatformCapability

Parameters:

classpath - The classpath for the PlatformCapability

getClassPath

public String[] getClassPath()

Get the classpath for the PlatformCapability

Returns:

The classpath as a String array. If no classpath has been set, return null

getLoadableClassPath

public URL[] getLoadableClassPath()
                           throws MalformedURLException

Get the loadable classpath for the PlatformCapability.

Returns:

The classpath for loading the PlatformCapability. If the classpath for this PlatformCapability is already loaded by the common class loader, this method will return a zero-length array. Otherwise this method will return the resources required to load this platform capability

Throws:

MalformedURLException - if the classpath cannot be constructed

loadResources

public void loadResources()

Allows the PlatformCapability to load any required native libraries as determined by values in the NativeLibsKey using the System.loadLibrary method. Libraries are loaded from the location pointed to by the java.library.path

define

public void define(String key,
                   Object value)

Define a platform capability mapping

Parameters:

key - The key associated with the platform capability. Can be a name or another descriptive attribute used to uniquely identify the platform capability

value - The value associated with the platform capability key

defineAll

public void defineAll(Map<String,Object> map)

Define all platform capability mappings to the platform capability Map

Parameters:

map - The Map containing platform capability mappings

getValue

public Object getValue(String key)

Get the value associated with the key in the platform capability mapping. If there is no value then this method will return null

Parameters:

key - The platform capability key

Returns:

The value associated with the key in the platform capability mapping

remove

public boolean remove(String key)

Remove a defined platform capability mapping

Parameters:

key - The platform capability key to remove

Returns:

True if removed, false otherwise

clearAll

public void clearAll()

Clear all platform capability mappings

supports

public boolean supports(PlatformCapability requirement)

Deprecated.

Determine if the provided PlatformCapability be supported. A PlatformCapability can be supported if this PlatformCapability is the same classname as the input PlatformCapability and all key,value parameters provided in the input PlatformCapability are found and equal to mappings in this PlatformCapability

Parameters:

requirement - The PlatformCapability to requirement

Returns:

True if supported, false otherwise

supports

public boolean supports(SystemRequirements.SystemComponent requirement)

Determine if the provided SystemRequirements.SystemComponent can be supported. A SystemRequirement can be supported if this PlatformCapability is the same class name (sans the package name) as the input SystemRequirement.getClassName() or the same fully qualified classname as provided by the SystemRequirement.getClassName() property and all key,value parameters provided in the input SystemRequirement are found and equal to mappings in this PlatformCapability

Parameters:

requirement - The SystemRequirement to test for supportability.

Returns:

True if supported, false otherwise

hasBasicSupport

protected boolean hasBasicSupport(String name,
                                  String className)

Determine basic supportability

Parameters:

name - The name of the class, sans the package name. If this parameter is not null, this will be checked

className - The fully qualified className to match if the name is null

Returns:

true if basic support is provided

matches

protected boolean matches(String input,
                          String value)

Matching semantics are accomplished using pattern matching with regular expressions

Parameters:

input - The regular expression, specified as a string. Must not be null

value - Match the given input against this pattern.

Returns:

true if, and only if, a subsequence of the regex matches this matcher's pattern

versionSupported

protected boolean versionSupported(String requiredVersion,
                                   String configuredVersion)

Determine if versions are supported

Parameters:

requiredVersion - The required version, specified as a string. Must not be null

configuredVersion - The configured version value

Returns:

true if, and only if, the request version can be supported

getPlatformKeys

public String[] getPlatformKeys()

Get the keys for the platform capability

Returns:

An array of the defined keys in the platform capability map

setDescription

public void setDescription(String description)

Set the description associated with the PlatformCapability

Parameters:

description - Description of the PlatformCapability

getDescription

public String getDescription()

Get the description associated with the PlatformCapability

Specified by:

getDescription in interface PlatformCapabilityMBean

Returns:

Description of the PlatformCapability

getName

public String getName()

Get the name of this PlatformCapability

Returns:

The name of the PlatformCapability

getCapabilities

public Map<String,Object> getCapabilities()

Description copied from interface: PlatformCapabilityMBean

The collection of key,value pairs this PlatformCapability has been created with

Specified by:

getCapabilities in interface PlatformCapabilityMBean

See Also:

PlatformCapabilityMBean.getCapabilities()

setResourceCostModel

public void setResourceCostModel(ResourceCostModel costModel)

Set the ResourceCostModel for the PlatformCapability

Parameters:

costModel - The ResourceCostModel that will determine the cost of using this PlatformCapability

getResourceCostModel

public ResourceCostModel getResourceCostModel()

Get the ResourceCostModel for the PlatformCapability

Returns:

The ResourceCostModel for the PlatformCapability

calculateResourceCost

public ResourceCost calculateResourceCost(double units,
                                          long duration)

Description copied from interface: ResourceCostProducer

Calculate the cost based on the units provided. The cost will be computed using the ResourceCostModel

Specified by:

calculateResourceCost in interface ResourceCostProducer

Parameters:

units - The units to be costed

duration - The amount of time in milliseconds the resource has been used for

Returns:

A ResourceCost object

See Also:

ResourceCostProducer.calculateResourceCost(double, long)

addStagedSoftware

public void addStagedSoftware(StagedSoftware... software)

Add StagedSoftware for the PlatformCapability. Adding StagedSoftware will also set the type of the PlatformCapability to be PROVISIONABLE

Parameters:

software - The StagedSoftware defining where the software for the PlatformCapability can be downloaded from

getStagedSoftware

public StagedSoftware[] getStagedSoftware()

Get the StagedSoftware for the PlatformCapability

Returns:

Array of StagedSoftware objects defining provisionable software for the PlatformCapability. If there is no StagedSoftware return a zero-length array

addDownloadRecord

public void addDownloadRecord(DownloadRecord record)

Add a DownloadRecord instance for the PlatformCapability

Parameters:

record - A DownloadRecord instance defining where software has been installed

getDownloadRecords

public DownloadRecord[] getDownloadRecords()

Get the DownloadRecord instances for the PlatformCapability

Returns:

Array of DownloadRecord instances recording where the software for the PlatformCapability has been downloaded to. If there are no DownloadRecord instances recorded, a zero-length array will be returned

getType

public int getType()

Get the type of PlatformCapability

Returns:

The type of the PlatformCapability

setType

protected void setType(int type)

Set the type of this record to be either STATIC or PROVISIONABLE

Parameters:

type - The type of the PlatformCapability

Throws:

IllegalArgumentException - if the supplied type is neither STATIC or PROVISIONABLE

incrementUsage

public void incrementUsage()

decrementUsage

public void decrementUsage()

getUsageCount

public int getUsageCount()

getConfigurationFile

public String getConfigurationFile()

setConfigurationFile

public void setConfigurationFile(String configurationFile)

hashCode

public int hashCode()

Override hashCode to return the hashCode of the capabilities Map

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

A PlatformCapability is equal to another PlatformCapability if they are the same class and their capabilities maps are equal

Overrides:

equals in class Object

toString

public String toString()

String representation of a PlatformCapability

Overrides:

toString in class Object