Rio Project 4.2 API Documentation

org.rioproject.core
Interface OperationalStringManager

All Superinterfaces:

Remote

All Known Subinterfaces:

OpStringManagerProxy.OpStringManager

All Known Implementing Classes:

ProvisionMonitorImpl.OpStringManager

public interface OperationalStringManager
extends Remote

The OperationalStringManager defines the semantics for a service that can manage OperationalString objects

Author:

Dennis Reedy

See Also:

OperationalString, ServiceElement

Method Summary

void	addServiceElement(ServiceElement sElem) This method will add a ServiceElement to an OperationalString.
void	addServiceElement(ServiceElement sElem, ServiceProvisionListener listener) This method will add a ServiceElement to an OperationalString.
void	decrement(ServiceBeanInstance instance, boolean mandate, boolean destroy) Decrement (decrease the number of) and remove a specific ServiceBean instance from the OperationalString.
Date[]	getDeploymentDates() Get the deployment Date history
DeploymentMap	getDeploymentMap() Get the DeploymentMap for services in this OperationalString
OperationalString	getOperationalString() Get the OperationalString the OperationalStringManager is managing
int	getPendingCount(ServiceElement sElem) Get the number of pending service provision requests.
ServiceBeanInstance[]	getServiceBeanInstances(ServiceElement sElem) Get the ServiceBeanInstance objects for a ServiceElement
ServiceElement	getServiceElement(Object proxy) This method returns the ServiceElement object for a requested service based on a service's proxy
ServiceElement	getServiceElement(String[] interfaces, String name) This method returns the ServiceElement object for a requested service based on the array of interface (or proxy) classes the service implements as an array of String objects and an optional service name.
ServiceStatement[]	getServiceStatements() Get the ServiceStatements for all ServiceElements in the OperationalString
void	increment(ServiceElement sElem, boolean permanent, ServiceProvisionListener listener) Increment (increase) the number of instances by one.
boolean	isManaging() Whether the OperationalStringManager is the active managing OperationalStringManager for the OperationalString.
void	redeploy(ServiceElement sElem, ServiceBeanInstance instance, boolean clean, boolean sticky, long delay, ServiceProvisionListener listener) Redeploy an OperationalString, ServiceElement or ServiceBeanInstance.
void	redeploy(ServiceElement sElem, ServiceBeanInstance instance, boolean clean, long delay, ServiceProvisionListener listener) Redeploy an OperationalString, ServiceElement or ServiceBeanInstance.
void	relocate(ServiceBeanInstance instance, ServiceProvisionListener listener, Uuid uuid) Relocate (move) a ServiceBean instance to another ServiceBeanInstantiator.
void	removeServiceElement(ServiceElement sElem, boolean destroy) This method will remove a ServiceElement from an OperationalString and optionally terminate all service instances that have been provisioned from the ServiceElement description
void	setManaging(boolean active) Set the OperationalStringManager managing status based on the active parameter
int	trim(ServiceElement sElem, int trimUp) Trim (remove) service provision requests which are pending allocation.
Map<String,Throwable>	update(OperationalString opstring) Update the OperationalString that the OperationalStringManager is managing.
void	update(ServiceBeanInstance instance) Update a ServiceBeanInstance
void	update(ServiceElement sElem) This method will modify the ServiceElement attributes of a ServiceElement in the OperationalStringManager.

Method Detail

getOperationalString

OperationalString getOperationalString()
                                       throws RemoteException

Get the OperationalString the OperationalStringManager is managing

Returns:

The OperationalString

Throws:

RemoteException - If communication errors occur

isManaging

boolean isManaging()
                   throws RemoteException

Whether the OperationalStringManager is the active managing OperationalStringManager for the OperationalString. The managing OperationalStringManager will actively respond to scenarios where service's contained within this OperationalString need to be allocated, updated, relocated, removed or added. If the OperationalStringManager is not the managing OperationalStringManager, it will observe and record OperationalString transitions but not act on them.

Returns:

True if managing, false otherwise

Throws:

RemoteException - If communication errors happen

setManaging

void setManaging(boolean active)
                 throws RemoteException

Set the OperationalStringManager managing status based on the active parameter

Parameters:

active - If true, the OperationalStringManager is the active managing OperationalStringManager for the OperationalString. The managing OperationalStringManager will actively respond to scenarios where service's contained within this OperationalString need to be allocated, updated, relocated, removed or added. If the OperationalStringManager is not the managing OperationalStringManager, it will observe and record OperationalString transitions but not act on them.

Throws:

RemoteException - If communication errors happen

getDeploymentDates

Date[] getDeploymentDates()
                          throws RemoteException

Get the deployment Date history

Returns:

An array of Date objects documenting the date & time the OperationalString has been deployed. If has never been deployed (has been scheduled) then a zero-length array will be returned.

Throws:

RemoteException - If communication errors happen

update

Map<String,Throwable> update(OperationalString opstring)
                             throws OperationalStringException,
                                    RemoteException

Update the OperationalString that the OperationalStringManager is managing. This involves updating ServiceElement instances, which may include the additon and or removal of ServiceElements in the OperationalString If the input OperationalString includes nested OperationalStrings, and the nested OperationalString is not deployed, the nested OperationalString will be deployed If the nested OperationalString has been deployed and is referenced by only the OperationalString being updated, the nested OperationalString will be updated as well

Parameters:

opstring - The OperationalString to update

Returns:

If there are errors updating the OperationalString a Map will be returned with name value pairs associating the service and corresponding exception attempting to update the OperationalString

Throws:

OperationalStringException - If there are problems updating the the OperationalString

RemoteException - If communication errors happen

getServiceElement

ServiceElement getServiceElement(Object proxy)
                                 throws RemoteException

This method returns the ServiceElement object for a requested service based on a service's proxy

Parameters:

proxy - The proxy for the Service

Returns:

The ServiceElement for the query. If there is no matching ServiceElement, a null is returned

Throws:

RemoteException - If communication errors occur

getServiceElement

ServiceElement getServiceElement(String[] interfaces,
                                 String name)
                                 throws RemoteException

This method returns the ServiceElement object for a requested service based on the array of interface (or proxy) classes the service implements as an array of String objects and an optional service name. The OperationalStringManager will locate the ServiceElement by matching the interface (or proxy) names provided and the name (if not null) of the supplied OperationalString.

Parameters:

interfaces - Array of interface (or proxy) classes the service implements as an array of String objects

name - The name of the Service

Returns:

The ServiceElement for the query. If there is no matching ServiceElement, a null is returned

Throws:

RemoteException - If communication errors occur

addServiceElement

void addServiceElement(ServiceElement sElem)
                       throws OperationalStringException,
                              RemoteException

This method will add a ServiceElement to an OperationalString. Based on the attributes of the ServiceElement, ServiceBean instances will be provisioned to available compute resources based on the capability of the compute resource to meet the operational criteria criteria of the ServiceElement

Parameters:

sElem - The ServiceElement to add

Throws:

OperationalStringException - If the service described by the ServiceElement already exists, or there are problems adding the ServiceElement

RemoteException - If communication errors occur

addServiceElement

void addServiceElement(ServiceElement sElem,
                       ServiceProvisionListener listener)
                       throws OperationalStringException,
                              RemoteException

This method will add a ServiceElement to an OperationalString. Based on the attributes of the ServiceElement, ServiceBean instances will be provisioned to available compute resources based on the capability of the compute resource to meet the operational criteria criteria of the ServiceElement

Parameters:

sElem - The ServiceElement to add

listener - If not null, the ServiceProvisionListener will be notified on the result of the attempt to instantiate each service instance.

Throws:

OperationalStringException - If the service described by the ServiceElement already exists, or there are problems adding the ServiceElement

RemoteException - If communication errors occur

update

void update(ServiceElement sElem)
            throws OperationalStringException,
                   RemoteException

This method will modify the ServiceElement attributes of a ServiceElement in the OperationalStringManager. The OperationalStringManager will locate deployed ServiceElement instances, and apply the attributes to those running instances. If the ServiceElement is not found it will be added and deployed.

Parameters:

sElem - The ServiceElement to update

Throws:

OperationalStringException - If there are problems updating the ServiceElement

RemoteException - If communication errors occur

removeServiceElement

void removeServiceElement(ServiceElement sElem,
                          boolean destroy)
                          throws OperationalStringException,
                                 RemoteException

This method will remove a ServiceElement from an OperationalString and optionally terminate all service instances that have been provisioned from the ServiceElement description

Parameters:

sElem - The ServiceElement to remove

destroy - If true, destroy all services upon removal, otherwise just remove

Throws:

OperationalStringException - If the ServiceElement is null or not being managed by the OperationalStringManager

RemoteException - If communication errors occur

getServiceBeanInstances

ServiceBeanInstance[] getServiceBeanInstances(ServiceElement sElem)
                                              throws OperationalStringException,
                                                     RemoteException

Get the ServiceBeanInstance objects for a ServiceElement

Parameters:

sElem - The ServiceElement

Returns:

An array of ServiceBeanInstance objects found for the ServiceElement. If there are no ServiceBeanInstances, a zero-length array is returned. A new array is allocated each time.

Throws:

OperationalStringException - If the ServiceElement is unknown to the OperationalStringManager

RemoteException - If communication errors occur

relocate

void relocate(ServiceBeanInstance instance,
              ServiceProvisionListener listener,
              Uuid uuid)
              throws OperationalStringException,
                     RemoteException

Relocate (move) a ServiceBean instance to another ServiceBeanInstantiator. If the relocating request cannot be carried out, the request will not be submitted for future processing.

Parameters:

instance - The ServiceBeanInstance to relocate

listener - If not null, the ServiceProvisionListener will be notified on the result of the attempt to relocate the service instance.

uuid - The Uuid of the ServiceBeanInstantiator (Cybernode) to relocate to. If this parameter is null, the OperationalStringManager will determine a suitable compute resource

Throws:

OperationalStringException - If the ServiceElement is not being managed by the OperationalStringManager, or the service requesting relocation is not a ServiceElement.ProvisionType.DYNAMIC service

NullPointerException - if the instance is null

RemoteException - If communication errors occur

increment

void increment(ServiceElement sElem,
               boolean permanent,
               ServiceProvisionListener listener)
               throws OperationalStringException,
                      RemoteException

Increment (increase) the number of instances by one. This will cause the provisioning of a ServiceBean to an available compute resource which meets the operational criteria specified by the ServiceElement. If the increment request cannot be accomplished (no available compute resources that meet operational requirements of the service), and the ServiceProvisionListener parameter is not null, the ServiceProvisionListener will be notified of the result. Additionally if the increment request cannot be carried out, the request will be submitted for future processing

Parameters:

sElem - The ServiceElement instance to increment. This parameter is used to match a ServiceElement being managed by the OperationalStringManager

permanent - If the increment request should be considered permanent. If set to false, the number of service instances may vary over time

listener - If not null, the ServiceProvisionListener will be notified on the result of the attempt to increment the amount of service instances.

Throws:

OperationalStringException - If the ServiceElement is not being managed by the OperationalStringManager (or the OperationalStringManager is not the managing OperationalStringManager for the OperationalString)

RemoteException - If communication errors occur

decrement

void decrement(ServiceBeanInstance instance,
               boolean mandate,
               boolean destroy)
               throws OperationalStringException,
                      RemoteException

Decrement (decrease the number of) and remove a specific ServiceBean instance from the OperationalString.

Parameters:

instance - The ServiceBeanInstance

mandate - The mandate parameter is processed as follows:

If set to true, and the number of running services is equal to the number of services to maintain, the number of services to maintain will be decremented by 1.
• If set to false, and the number of service instances running is greater then the number of services to maintain, the number of services to maintain will be decremented by 1.
• If set to false, and the number of running service is equal to the number of services to maintain, the decrement will not be allowed.

destroy - If true, destroy the ServiceBean upon decrementing, otherwise just remove the service instance from being a managed service.

Throws:

OperationalStringException - If the ServiceElement is not being managed by the OperationalStringManager

RemoteException - If communication errors occur

getPendingCount

int getPendingCount(ServiceElement sElem)
                    throws RemoteException

Get the number of pending service provision requests. This method will only take action if the ServiceElement provision type is ServiceElement.ProvisionType.DYNAMIC. Any other provisiontype will be ignored

Parameters:

sElem - The ServiceElement instance to query. This parameter is used to match a ServiceElement being managed by the OperationalStringManager

Returns:

The number of pending requests. If the ServiceElement provision type is not ServiceElement.ProvisionType.DYNAMIC OperationalStringManager is not the managing OperationalStringManager, -1 will be returned

Throws:

RemoteException - If communication errors occur

trim

int trim(ServiceElement sElem,
         int trimUp)
         throws OperationalStringException,
                RemoteException

Trim (remove) service provision requests which are pending allocation. This method will only take action if the ServiceElement provision type is ServiceElement.ProvisionType.DYNAMIC. Any other provision type will be ignored

Parameters:

sElem - The ServiceElement instance to trim. This parameter is used to match a ServiceElement being managed by the OperationalStringManager

trimUp - The number of pending requests to trim. The number of pending requests to trim will be determined as follows :

• If the trimUp value is -1, then trim the all pending requests
• If the trimUp value is not -1, the number of pending requests to trim will be calaculated as follows:
  Math.min((planned-actual), trimUp)
  Where planned is the property obtained from the managed ServiceElement, actual is the number of active (deployed) services, and trimUp is the input value.

Returns:

The number of pending requests that were trimmed. The value will be the new managed ServiceElement planned property. If the ServiceElement provision type is not ServiceElement.ProvisionType.DYNAMIC, -1 will be returned

Throws:

OperationalStringException - If the ServiceElement is not being managed by the OperationalStringManager

RemoteException - If communication errors occur

update

void update(ServiceBeanInstance instance)
            throws OperationalStringException,
                   RemoteException

Update a ServiceBeanInstance

Parameters:

instance - The ServiceBeanInstance to update. The configuration and properties of the instance are updated, ensuring if the instance is (re-)allocated or relocated, the settings are applied to the new i nstance.

Throws:

OperationalStringException - If the ServiceElement is not being managed by the OperationalStringManager

RemoteException - If communication errors occur

redeploy

void redeploy(ServiceElement sElem,
              ServiceBeanInstance instance,
              boolean clean,
              long delay,
              ServiceProvisionListener listener)
              throws OperationalStringException,
                     RemoteException

Redeploy an OperationalString, ServiceElement or ServiceBeanInstance. This method will terminate then reallocate services based on the following criteria:

• If both the ServiceElement and ServiceBeanInstance parameters are null, the OperationalString will be redeployed. All services in the OperationalString will be terminated then redeployed
• If the ServiceElement parameter is not null, this method will terminate then reallocate all deployed services identified by the ServiceElement
• If the ServiceBeanInstance is not null and the ServiceElement is not null, this method will terminate and then reallocate the service identified by the ServiceBeanInstance

Parameters:

sElem - If not null, the ServiceElement to redeploy

instance - If not null, and the sElem param is not null, the ServiceBeanInstance to redeploy

clean - If set to true, the service will be allocated using the ServiceElement configuration, not the ServiceBeanInstance configuration

delay - The amount of time (in milliseconds) to wait until the redeployment is performed. A value > 0 will result in scheduling the redeployment

listener - If not null, the ServiceProvisionListener will be notified as each service is redeployed

Throws:

OperationalStringException - If there are errors redeploying

RemoteException - If communication errors occur

redeploy

void redeploy(ServiceElement sElem,
              ServiceBeanInstance instance,
              boolean clean,
              boolean sticky,
              long delay,
              ServiceProvisionListener listener)
              throws OperationalStringException,
                     RemoteException

Redeploy an OperationalString, ServiceElement or ServiceBeanInstance. This method will terminate then reallocate services based on the following criteria:

• If both the ServiceElement and ServiceBeanInstance parameters are null, the OperationalString will be redeployed. All services in the OperationalString will be terminated then redeployed
• If the ServiceElement parameter is not null, this method will terminate then reallocate all deployed services identified by the ServiceElement
• If the ServiceBeanInstance is not null and the ServiceElement is not null, this method will terminate and then reallocate the service identified by the ServiceBeanInstance

Parameters:

sElem - If not null, the ServiceElement to redeploy

instance - If not null, and the sElem param is not null, the ServiceBeanInstance to redeploy

clean - If set to true, the service will be allocated using the ServiceElement configuration, not the ServiceBeanInstance configuration

sticky - If set to true, the service(s) will be re-allocated to the same ServiceBeanInstantiator that had instantiated the service. If the service has requirements that cannot be met by the compute resource hosting the ServiceBeanInstantiator, the service will be allocated on the next available compute resource that meets the requirements of the service.

delay - The amount of time (in milliseconds) to wait until the redeployment is performed. A value > 0 will result in scheduling the redeployment

listener - If not null, the ServiceProvisionListener will be notified as each service is redeployed

Throws:

OperationalStringException - If there are errors redeploying

RemoteException - If communication errors occur

getServiceStatements

ServiceStatement[] getServiceStatements()
                                        throws RemoteException

Get the ServiceStatements for all ServiceElements in the OperationalString

Returns:

An array of ServiceStatement instances.

Throws:

RemoteException - If communication errors occur

getDeploymentMap

DeploymentMap getDeploymentMap()
                               throws RemoteException

Get the DeploymentMap for services in this OperationalString

Returns:

A DeploymentMap for services in this OperationalString

Throws:

RemoteException - If communication errors occur