com.opencloud.rhino.management.service

Interface ServiceManagementMBean

All Superinterfaces:

ServiceManagementMBean

public interface ServiceManagementMBean
extends ServiceManagementMBean

The ServiceManagementMBean interface defines Service-related management operations. This interface provides extensions to ServiceManagementMBean for additional Rhino-specific functionality.

Field Summary

Fields inherited from interface javax.slee.management.ServiceManagementMBean

OBJECT_NAME, SERVICE_STATE_CHANGE_NOTIFICATION_TYPE

Method Summary

Modifier and Type	Method and Description
void	activate(ServiceID id) Activate a Service on all currently live event routing nodes as determined by RhinoHousekeepingMBean.getEventRouterNodes().
void	activate(ServiceID[] ids) Activate a set of Services on all currently live event routing nodes as determined by RhinoHousekeepingMBean.getEventRouterNodes().
void	activate(ServiceID[] ids, int[] nodeIDs) Activate a set of Services on the specified nodes.
void	activate(ServiceID id, int[] nodeIDs) Activate a Service on the specified nodes.
BindingResult	addBinding(ServiceID id, BindingDescriptorID bindingDescriptor, Map<ComponentID,ComponentID> componentMappings, boolean dryrun) Add a binding to a Service.
BindingResult	addBindings(ServiceID id, BindingDescriptorID[] bindingDescriptors, Map<ComponentID,ComponentID> componentMappings, boolean dryrun) Add one or more bindings to a Service.
void	deactivate(ServiceID id) Deactivate a Service on all currently live event routing nodes as determined by RhinoHousekeepingMBean.getEventRouterNodes().
void	deactivate(ServiceID[] ids) Deactivate a set of Services on all currently live event routing nodes as determined by RhinoHousekeepingMBean.getEventRouterNodes().
void	deactivate(ServiceID[] ids, int[] nodeIDs) Deactivate a set of Services on the specified nodes.
void	deactivate(ServiceID id, int[] nodeIDs) Deactivate a Service on the specified nodes.
void	deactivateAndActivate(ServiceID[] deactivateIDs, ServiceID[] activateIDs) Deactivate one set of Services and activate another set of Services on all currently live event routing nodes as determined by RhinoHousekeepingMBean.getEventRouterNodes().
void	deactivateAndActivate(ServiceID[] deactivateIDs, ServiceID[] activateIDs, int[] nodeIDs) Deactivate one set of Services and activate another set of Services on the specified nodes.
void	deactivateAndActivate(ServiceID deactivateID, ServiceID activateID) Deactivate one Service and activate another Service on all currently live event routing nodes as determined by RhinoHousekeepingMBean.getEventRouterNodes().
void	deactivateAndActivate(ServiceID deactivateID, ServiceID activateID, int[] nodeIDs) Deactivate one Service and activate another Service on the specified nodes.
BindingDescriptorID[]	getBindings(ServiceID id) Get the set of binding descriptors currently associated with a Service.
int[]	getNodes(ServiceID id, ServiceState state) Get the set of event-router nodes in the primary component where the Service is in the specified state.
ReplicationSelector[]	getReplicationSelectors(ServiceID id) Get the current replication selectors for a service.
ReplicationSelector[][]	getReplicationSelectors(ServiceID[] services) Get an array of the replication selectors corresponding to an array of Service component identifiers.
boolean	getServiceMetricsRecordingEnabled(ServiceID service) Determine if the recording of metrics for a service is currently enabled or disabled.
ServiceID[]	getServices(ServiceState state) Get the set of Services that are in a particular state.
ServiceID[]	getServices(ServiceState state, int nodeID) Get the set of Services that are in a particular state on the specified node.
ObjectName	getServiceUsageMBean(ServiceID id)
Byte[]	getStartingPriorities(ServiceID[] services) Get an array of starting priorities corresponding to an array of Service component identifiers.
byte	getStartingPriority(ServiceID service) Get the starting priority for a Service.
ServiceState	getState(ServiceID id) Get the current state of a Service.
ServiceState[]	getState(ServiceID id, int[] nodeIDs) Get the current state of a Service on each of the specified nodes.
Byte[]	getStoppingPriorities(ServiceID[] services) Get an array of stopping priorities corresponding to an array of Service component identifiers.
byte	getStoppingPriority(ServiceID service) Get the stopping priority for a Service.
BindingResult	removeBinding(ServiceID id, BindingDescriptorID bindingDescriptor, boolean dryrun) Remove an existing binding from a Service.
BindingResult	removeBindings(ServiceID id, BindingDescriptorID[] bindingDescriptors, boolean dryrun) Remove one or more existing bindings from a Service.
void	setReplicationSelectors(ServiceID id, ReplicationSelector[] selectors) Set the replication selectors for a service.
void	setServiceMetricsRecordingEnabled(ServiceID service, boolean enabled) Enable or disable the recording of metrics for a service.
void	setStartingPriority(ServiceID service, byte priority) Set the starting priority for a Service.
void	setStoppingPriority(ServiceID service, byte priority) Set the stopping priority for a Service.

Method Detail

activate

void activate(ServiceID id)
       throws NullPointerException,
              UnrecognizedServiceException,
              InvalidStateException,
              InvalidLinkNameBindingStateException,
              UnconfiguredResourceException,
              ManagementException

Activate a Service on all currently live event routing nodes as determined by RhinoHousekeepingMBean.getEventRouterNodes(). The Service must currently be in the ServiceState.INACTIVE state on all these nodes and transitions to ServiceState.ACTIVE state on these nodes during this method invocation.

Specified by:

activate in interface ServiceManagementMBean

Parameters:

id - the component identifier of the Service.

Throws:

NullPointerException - if id is null.

UnrecognizedServiceException - if id is not a recognizable ServiceID for the SLEE or it does not correspond with a Service installed in the SLEE.

InvalidStateException - if the current state of the Service on all nodes is not ServiceState.INACTIVE.

InvalidLinkNameBindingStateException - if a resource adaptor entity link name binding required by an SBB in the Service does not exist or is bound to a resource adaptor entity that does not implement the resource adaptor type expected by the SBB.

UnconfiguredResourceException - if a resource required by an SBB in the Service has not been configured.

ManagementException - if the state of the Service could not be changed due to a system-level failure.

activate

void activate(ServiceID id,
              int[] nodeIDs)
       throws NullPointerException,
              InvalidArgumentException,
              UnrecognizedServiceException,
              InvalidStateException,
              ManagementException

Activate a Service on the specified nodes. The Service must currently be in the ServiceState.INACTIVE state on these nodes and transitions to ServiceState.ACTIVE state on these nodes during this method invocation.

The specified nodes do not have to be current cluster members. For example this method can be used to set the activation state for a service on nodes yet to be started.

Parameters:

id - the component identifier of the Service.

nodeIDs - the node IDs of the nodes to activate the Service on.

Throws:

NullPointerException - if either argument is null.

InvalidArgumentException - if nodeIDs is zero-length or contains invalid node IDs.

UnrecognizedServiceException - if id is not a recognizable ServiceID for the SLEE or it does not correspond with a Service installed in the SLEE.

InvalidStateException - if the current state of the Service on all specified nodes is not ServiceState.INACTIVE.

InvalidLinkNameBindingStateException - if a resource adaptor entity link name binding required by an SBB in the Service does not exist or is bound to a resource adaptor entity that does not implement the resource adaptor type expected by the SBB.

UnconfiguredResourceException - if a resource required by an SBB in the Service has not been configured.

ManagementException - if the state of the Service could not be changed due to a system-level failure.

activate

void activate(ServiceID[] ids)
       throws NullPointerException,
              InvalidArgumentException,
              UnrecognizedServiceException,
              InvalidStateException,
              InvalidLinkNameBindingStateException,
              UnconfiguredResourceException,
              ManagementException

Activate a set of Services on all currently live event routing nodes as determined by RhinoHousekeepingMBean.getEventRouterNodes(). All Services in the set must currently be in the ServiceState.INACTIVE state on all these nodes and transition to ServiceState.ACTIVE state on these nodes during this method invocation.

Specified by:

activate in interface ServiceManagementMBean

Parameters:

ids - a set of component identifiers of the Services to be activated.

Throws:

NullPointerException - if ids is null.

InvalidArgumentException - if ids is zero-length, or contains null or duplicate elements.

UnrecognizedServiceException - if any member of ids is not a recognizable ServiceID for the SLEE or does not correspond with a Service installed in the SLEE.

InvalidStateException - if the current state of any of the Services identified by ids on all nodes is not ServiceState.INACTIVE.

InvalidLinkNameBindingStateException - if a resource adaptor entity link name binding required by an SBB in any of the Services does not exist or is bound to a resource adaptor entity that does not implement the resource adaptor type expected by the SBB.

UnconfiguredResourceException - if a resource required by an SBB in the Service has not been configured.

ManagementException - if the state of any Service could not be changed due to a system-level failure. In the case of such an error the state of all Services identified in ids remains unchanged.

activate

void activate(ServiceID[] ids,
              int[] nodeIDs)
       throws NullPointerException,
              InvalidArgumentException,
              UnrecognizedServiceException,
              InvalidStateException,
              ManagementException

Activate a set of Services on the specified nodes. All Services in the set must currently be in the ServiceState.INACTIVE state on all these nodes and transition to ServiceState.ACTIVE state on these nodes during this method invocation.

The specified nodes do not have to be current cluster members. For example this method can be used to set the activation state for the services on nodes yet to be started.

Parameters:

ids - a set of component identifiers of the Services to be activated.

nodeIDs - the node IDs of the nodes to activate the Service on.

Throws:

NullPointerException - if either argument is null.

InvalidArgumentException - if ids is zero-length, or contains null or duplicate elements, or if nodeIDs is zero-length or contains invalid node IDs.

UnrecognizedServiceException - if any member of ids is not a recognizable ServiceID for the SLEE or does not correspond with a Service installed in the SLEE.

InvalidStateException - if the current state of any of the Services identified by ids on the specified nodes is not ServiceState.INACTIVE.

InvalidLinkNameBindingStateException - if a resource adaptor entity link name binding required by an SBB in any of the Services does not exist or is bound to a resource adaptor entity that does not implement the resource adaptor type expected by the SBB.

UnconfiguredResourceException - if a resource required by an SBB in the Service has not been configured.

ManagementException - if the state of any Service could not be changed due to a system-level failure. In the case of such an error the state of all Services identified in ids remains unchanged.

deactivate

void deactivate(ServiceID id)
         throws NullPointerException,
                UnrecognizedServiceException,
                InvalidStateException,
                ManagementException

Deactivate a Service on all currently live event routing nodes as determined by RhinoHousekeepingMBean.getEventRouterNodes(). The Service must currently be in the ServiceState.ACTIVE state on all these nodes and transitions to ServiceState.STOPPING state on these nodes during this method invocation.

Specified by:

deactivate in interface ServiceManagementMBean

Parameters:

id - the component identifier of the Service.

Throws:

NullPointerException - if id is null.

UnrecognizedServiceException - if id is not a recognizable ServiceID for the SLEE or it does not correspond with a Service installed in the SLEE.

InvalidStateException - if the current state of the Service of all nodes is not ServiceState.ACTIVE.

ManagementException - if the state of the Service could not be changed due to a system-level failure.

deactivate

void deactivate(ServiceID id,
                int[] nodeIDs)
         throws NullPointerException,
                InvalidArgumentException,
                UnrecognizedServiceException,
                InvalidStateException,
                ManagementException

Deactivate a Service on the specified nodes. The Service must currently be in the ServiceState.ACTIVE state on these nodes and transitions to ServiceState.STOPPING state on these nodes during this method invocation.

The specified nodes do not have to be current cluster members. For example this method can be used to set the activation state for a service on nodes yet to be started.

Parameters:

id - the component identifier of the Service.

nodeIDs - the node IDs of the nodes to deactivate the Service on.

Throws:

NullPointerException - if either argument is null.

InvalidArgumentException - if nodeIDs is zero-length or contains invalid node IDs.

UnrecognizedServiceException - if id is not a recognizable ServiceID for the SLEE or it does not correspond with a Service installed in the SLEE.

InvalidStateException - if the current state of the Service on all specified nodes is not ServiceState.ACTIVE.

ManagementException - if the state of the Service could not be changed due to a system-level failure.

deactivate

void deactivate(ServiceID[] ids)
         throws NullPointerException,
                InvalidArgumentException,
                UnrecognizedServiceException,
                InvalidStateException,
                ManagementException

Deactivate a set of Services on all currently live event routing nodes as determined by RhinoHousekeepingMBean.getEventRouterNodes(). All Services in the set must currently be in the ServiceState.ACTIVE state on all these nodes and transition to ServiceState.STOPPING state on these nodes during this method invocation.

Specified by:

deactivate in interface ServiceManagementMBean

Parameters:

ids - a set of component identifiers of Services to be deactivated.

Throws:

NullPointerException - if ids is null.

InvalidArgumentException - if ids is zero-length, or contains null or duplicate elements.

UnrecognizedServiceException - if any member of ids is not a recognizable ServiceID for the SLEE or does not correspond with a Service installed in the SLEE.

InvalidStateException - if the current state of any of the Services identified by ids on all nodes is not ServiceState.ACTIVE.

ManagementException - if the state of any Service could not be changed due to a system-level failure. In the case of such an error the state of all Services identified in ids remains unchanged.

deactivate

void deactivate(ServiceID[] ids,
                int[] nodeIDs)
         throws NullPointerException,
                InvalidArgumentException,
                UnrecognizedServiceException,
                InvalidStateException,
                ManagementException

Deactivate a set of Services on the specified nodes. All Services in the set must currently be in the ServiceState.ACTIVE state on all these nodes and transition to ServiceState.STOPPING state on these nodes during this method invocation.

The specified nodes do not have to be current cluster members. For example this method can be used to set the activation state for the services on nodes yet to be started.

Parameters:

ids - a set of component identifiers of Services to be deactivated.

nodeIDs - the node IDs of the nodes to deactivate the Service on.

Throws:

NullPointerException - if either argument is null.

InvalidArgumentException - if ids is zero-length, or contains null or duplicate elements, or if nodeIDs is zero-length or contains invalid node IDs.

UnrecognizedServiceException - if any member of ids is not a recognizable ServiceID for the SLEE or does not correspond with a Service installed in the SLEE.

InvalidStateException - if the current state of any of the Services identified by ids on the specified nodes is not ServiceState.ACTIVE.

ManagementException - if the state of any Service could not be changed due to a system-level failure. In the case of such an error the state of all Services identified in ids remains unchanged.

deactivateAndActivate

void deactivateAndActivate(ServiceID deactivateID,
                           ServiceID activateID)
                    throws NullPointerException,
                           InvalidArgumentException,
                           UnrecognizedServiceException,
                           InvalidStateException,
                           InvalidLinkNameBindingStateException,
                           ManagementException

Deactivate one Service and activate another Service on all currently live event routing nodes as determined by RhinoHousekeepingMBean.getEventRouterNodes(). The first Service must currently be in the ServiceState.ACTIVE state on all these nodes and transitions to ServiceState.STOPPING state on these nodes during this method invocation. The second Service must be in the ServiceState.INACTIVE state on all these nodes and transitions to the ServiceState.ACTIVE state on these nodes during this method invocation.

Specified by:

deactivateAndActivate in interface ServiceManagementMBean

Parameters:

deactivateID - the component identifier of the Service to be deactivated.

activateID - the component identifier of the Service to be activated.

Throws:

NullPointerException - if either argument is null.

InvalidArgumentException - if deactivateID and activateID identify the same Service.

UnrecognizedServiceException - if either argument is not a recognizable ServiceID for the SLEE or does not correspond with a Service installed in the SLEE.

InvalidStateException - if the current state of the Service identified by deactivateID on all nodes is not ServiceState.ACTIVE or the the current state of the Service identified by activateID on all nodes is not ServiceState.INACTIVE.

InvalidLinkNameBindingStateException - if a resource adaptor entity link name binding required by an SBB in the activating Service does not exist or is bound to a resource adaptor entity that does not implement the resource adaptor type expected by the SBB.

ManagementException - if the state of either Service could not be changed due to a system-level failure. In the case of such an error the state of both Services remains unchanged.

deactivateAndActivate

void deactivateAndActivate(ServiceID deactivateID,
                           ServiceID activateID,
                           int[] nodeIDs)
                    throws NullPointerException,
                           InvalidArgumentException,
                           UnrecognizedServiceException,
                           InvalidStateException,
                           ManagementException

Deactivate one Service and activate another Service on the specified nodes. The first Service must currently be in the ServiceState.ACTIVE state on all these nodes and transitions to ServiceState.STOPPING state on these nodes during this method invocation. The second Service must be in the ServiceState.INACTIVE state on these nodes and transitions to the ServiceState.ACTIVE state on these nodes during this method invocation.

The specified nodes do not have to be current cluster members. For example this method can be used to set the activation state for a service on nodes yet to be started.

Parameters:

deactivateID - the component identifier of the Service to be deactivated.

activateID - the component identifier of the Service to be activated.

nodeIDs - the node IDs of the nodes to activate and deactivate the Services on.

Throws:

NullPointerException - if any argument is null.

InvalidArgumentException - if deactivateID and activateID identify the same Service, or if nodeIDs is zero-length or contains invalid node IDs.

UnrecognizedServiceException - if either argument is not a recognizable ServiceID for the SLEE or does not correspond with a Service installed in the SLEE.

InvalidStateException - if the current state of the Service identified by deactivateID on the specified nodes is not ServiceState.ACTIVE or the the current state of the Service identified by activateID on the specified nodes is not ServiceState.INACTIVE.

InvalidLinkNameBindingStateException - if a resource adaptor entity link name binding required by an SBB in the activating Service does not exist or is bound to a resource adaptor entity that does not implement the resource adaptor type expected by the SBB.

ManagementException - if the state of either Service could not be changed due to a system-level failure. In the case of such an error the state of both Services remains unchanged.

deactivateAndActivate

void deactivateAndActivate(ServiceID[] deactivateIDs,
                           ServiceID[] activateIDs)
                    throws NullPointerException,
                           InvalidArgumentException,
                           UnrecognizedServiceException,
                           InvalidStateException,
                           InvalidLinkNameBindingStateException,
                           ManagementException

Deactivate one set of Services and activate another set of Services on all currently live event routing nodes as determined by RhinoHousekeepingMBean.getEventRouterNodes(). All Services in the first set must currently be in the ServiceState.ACTIVE state on all these nodes, and transition to ServiceState.STOPPING state on these nodes during this method invocation. All Services in the second set must be in the ServiceState.INACTIVE state on all these nodes and transition to the ServiceState.ACTIVE state on these nodes during this method invocation.

Specified by:

deactivateAndActivate in interface ServiceManagementMBean

Parameters:

deactivateIDs - a set of component identifiers of Services to be deactivated.

activateIDs - a set of component identifiers of Services to be activated.

Throws:

NullPointerException - if either argument is null.

InvalidArgumentException - if either argument is zero-length, contains null or duplicate elements, or a Service identified by a a component identifier in deactivateIDs is the same as a Service identified by a component identifier in activateIDs.

UnrecognizedServiceException - if any member of deactivateIDs or activateIDs is not a recognizable ServiceID for the SLEE or does not correspond with a Service installed in the SLEE.

InvalidStateException - if the current state of any of the Services identified by deactivateIDs on all nodes is not ServiceState.ACTIVE or the the current state of any of the Services identified by activateIDs on all nodes is not ServiceState.INACTIVE.

InvalidLinkNameBindingStateException - if a resource adaptor entity link name binding required by an SBB in any of the activating Services does not exist or is bound to a resource adaptor entity that does not implement the resource adaptor type expected by the SBB.

ManagementException - if the state of any of the Services could not be changed due to a system-level failure. In the case of such an error the state of all Services identified in deactivateIDs and activateIDs remains unchanged.

deactivateAndActivate

void deactivateAndActivate(ServiceID[] deactivateIDs,
                           ServiceID[] activateIDs,
                           int[] nodeIDs)
                    throws NullPointerException,
                           InvalidArgumentException,
                           UnrecognizedServiceException,
                           InvalidStateException,
                           ManagementException

Deactivate one set of Services and activate another set of Services on the specified nodes. All Services in the first set must currently be in the ServiceState.ACTIVE state on all these nodes, and transition to ServiceState.STOPPING state on these nodes during this method invocation. All Services in the second set must be in the ServiceState.INACTIVE state on all these nodes and transition to the ServiceState.ACTIVE state on these nodes during this method invocation.

The specified nodes do not have to be current cluster members. For example this method can be used to set the activation state for the services on nodes yet to be started.

Parameters:

deactivateIDs - a set of component identifiers of Services to be deactivated.

activateIDs - a set of component identifiers of Services to be activated.

nodeIDs - the node IDs of the nodes to activate and deactivate the Services on.

Throws:

NullPointerException - if any argument is null.

InvalidArgumentException - if either the deactivateIDs or activateIDs argument is zero-length, contains null or duplicate elements, or a Service identified by a a component identifier in deactivateIDs is the same as a Service identified by a component identifier in activateIDs, or if nodeIDs is zero-length or contains invalid node IDs.

UnrecognizedServiceException - if any member of deactivateIDs or activateIDs is not a recognizable ServiceID for the SLEE or does not correspond with a Service installed in the SLEE.

InvalidStateException - if the current state of any of the Services identified by deactivateIDs on the specified nodes is not ServiceState.ACTIVE or the the current state of any of the Services identified by activateIDs on the specified nodes is not ServiceState.INACTIVE.

InvalidLinkNameBindingStateException - if a resource adaptor entity link name binding required by an SBB in any of the activating Services does not exist or is bound to a resource adaptor entity that does not implement the resource adaptor type expected by the SBB.

ManagementException - if the state of any of the Services could not be changed due to a system-level failure. In the case of such an error the state of all Services identified in deactivateIDs and activateIDs remains unchanged.

getServices

ServiceID[] getServices(ServiceState state)
                 throws NullPointerException,
                        ManagementException

Get the set of Services that are in a particular state. This method returns the set of Services in the specified state on the node the management client directs this method call at, as determined by RhinoHousekeepingMBean.getNodeID().

Specified by:

getServices in interface ServiceManagementMBean

Parameters:

state - the required state.

Returns:

an array of ServiceID objects identifying the services that are in the specified state on the invoked node.

Throws:

NullPointerException - if state is null.

ManagementException - if the set of services could not be obtained due to a system-level failure.

getServices

ServiceID[] getServices(ServiceState state,
                        int nodeID)
                 throws NullPointerException,
                        InvalidArgumentException,
                        ManagementException

Get the set of Services that are in a particular state on the specified node.

The specified node does not have to be a current cluster member. For example this method can be used to query the activation state for a service on a node yet to be started.

Parameters:

state - the required state.

nodeID - the node ID of the node to obtain service state information from.

Returns:

an array of ServiceID objects identifying the services that are in the specified state on the specified node.

Throws:

NullPointerException - if state is null.

InvalidArgumentException - if nodeID is invalid.

ManagementException - if the set of services could not be obtained due to a system-level failure.

getState

ServiceState getState(ServiceID id)
               throws NullPointerException,
                      UnrecognizedServiceException,
                      ManagementException

Get the current state of a Service. This method returns the state of the Service on the node the management client directs the method call at, as determined by RhinoHousekeepingMBean.getNodeID().

Specified by:

getState in interface ServiceManagementMBean

Parameters:

id - the component identifier of the Service.

Returns:

the current state of the Service on the invoked node.

Throws:

NullPointerException - if id is null.

UnrecognizedServiceException - if id is not a recognizable ServiceID for the SLEE or it does not correspond with a Service installed in the SLEE.

ManagementException - if the state of the Service could not be obtained due to a system-level failure.

getState

ServiceState[] getState(ServiceID id,
                        int[] nodeIDs)
                 throws NullPointerException,
                        InvalidArgumentException,
                        UnrecognizedServiceException,
                        ManagementException

Get the current state of a Service on each of the specified nodes.

Parameters:

id - the component identifier of the Service.

nodeIDs - the node IDs of the nodes to return the Service’s state for.

Returns:

an array of service state objects. This array will be the same length as the supplied nodeIDs array, and if states = getState(id, nodeIDs) then states[i] equals the state of the service on node nodeIDs[i]. If there is no state information for the service on a particular node, ServiceState.INACTIVE is returned as the resulting state for the service on that node.

Throws:

NullPointerException - if either argument is null.

InvalidArgumentException - if nodeIDs is zero-length or contains invalid node IDs.

UnrecognizedServiceException - if id is not a recognizable ServiceID for the SLEE or it does not correspond with a Service installed in the SLEE.

ManagementException - if the state of the Service could not be obtained due to a system-level failure.

getNodes

int[] getNodes(ServiceID id,
               ServiceState state)
        throws NullPointerException,
               UnrecognizedServiceException,
               ManagementException

Get the set of event-router nodes in the primary component where the Service is in the specified state.

Parameters:

id - the component identifier of the Service.

state - the required state.

Returns:

an array of node IDs identifying the event-router nodes where the Service is in the specified state.

Throws:

NullPointerException - if either argument is null.

UnrecognizedServiceException - if id is not a recognizable ServiceID for the SLEE or it does not correspond with a Service installed in the SLEE.

ManagementException - if the set of nodes where the Service is in the required state could not be determined due to a system-level failure.

getServiceUsageMBean

ObjectName getServiceUsageMBean(ServiceID id)
                         throws NullPointerException,
                                UnrecognizedServiceException,
                                ManagementException

Specified by:

getServiceUsageMBean in interface ServiceManagementMBean

Throws:

NullPointerException

UnrecognizedServiceException

ManagementException

addBinding

BindingResult addBinding(ServiceID id,
                         BindingDescriptorID bindingDescriptor,
                         Map<ComponentID,ComponentID> componentMappings,
                         boolean dryrun)
                  throws NullPointerException,
                         UnrecognizedServiceException,
                         UnrecognizedBindingDescriptorException,
                         BindingAlreadyExistsException,
                         InvalidArgumentException,
                         InvalidStateException,
                         BindingVerificationException,
                         ManagementException

Add a binding to a Service. Components in the Service are modified with the addition of the deployment metadata contained by the specified binding descriptor.

Bindings can only be added to a Service that is in the INACTIVE state.

This method will implicitly create new components (as copies of original components) or remove copied components no longer required (due to component mapping changes) as a result of the binding operation. After the binding operation completes, affected components that remain will have an install level of InstallLevel.VERIFIED.

Parameters:

id - the component identifier of the Service.

bindingDescriptor - the component identifier of the binding descriptor.

componentMappings - component mappings for copied components. If an existing component needs to be copied as a result of the binding, and the component identifier of the component to be copied is a key in this map, then the copied component will have the identity given by the value of the mapping, rather than a default value generated by the SLEE. This parameter may be null if no specific mappings are required.

dryrun - if true, the SLEE will validate the binding operation and return the result as if the binding operation completed, but will not actually commit any changes to the SLEE.

Returns:

the result of the binding operation.

Throws:

NullPointerException - if id or bindingDescriptor is null.

UnrecognizedServiceException - if id is not a recognizable ServiceID for the SLEE or it does not correspond with a Service installed in the SLEE.

UnrecognizedBindingDescriptorException - if bindingDescriptor is not a recognizable BindingDescriptorID for the SLEE or it does not correspond with a binding descriptor installed in the SLEE.

BindingAlreadyExistsException - if the binding descriptor has already been added to the Service.

InvalidArgumentException - if componentMappings contains a mapping that cannot be used, for example the source and target identifiers represent different component types, or a component with the target identity already exists and cannot be reused for this service.

InvalidStateException - if the current state of the Service on all nodes is not ServiceState.INACTIVE

BindingVerificationException - if adding the binding to the Service would cause the Service to have an invalid configuration. For example, the binding descriptor may reference a component that is not installed in the SLEE, or reference an SBB that is not part of the Service.

ManagementException - if the binding could not be added to the Service due to a system-level failure.

Since:

Rhino 2.4.0

addBindings

BindingResult addBindings(ServiceID id,
                          BindingDescriptorID[] bindingDescriptors,
                          Map<ComponentID,ComponentID> componentMappings,
                          boolean dryrun)
                   throws NullPointerException,
                          InvalidArgumentException,
                          UnrecognizedServiceException,
                          UnrecognizedBindingDescriptorException,
                          BindingAlreadyExistsException,
                          InvalidStateException,
                          BindingVerificationException,
                          ManagementException

Add one or more bindings to a Service. Components in the Service are modified with the addition of the deployment metadata contained by the specified binding descriptors.

Bindings can only be added to a Service that is in the INACTIVE state.

This method will implicitly create new components (as copies of original components) or remove copied components no longer required (due to component mapping changes) as a result of the binding operation. After the binding operation completes, affected components that remain will have an install level of InstallLevel.VERIFIED.

Parameters:

id - the component identifier of the Service.

bindingDescriptors - the component identifiers of the binding descriptors.

componentMappings - component mappings for copied components. If an existing component needs to be copied as a result of the binding, and the component identifier of the component to be copied is a key in this map, then the copied component will have the identity given by the value of the mapping, rather than a default value generated by the SLEE. This parameter may be null if no specific mappings are required.

dryrun - if true, the SLEE will validate the binding operation and return the result as if the binding operation completed, but will not actually commit any changes to the SLEE.

Returns:

the result of the binding operation.

Throws:

NullPointerException - if id or bindingDescriptors is null.

InvalidArgumentException - if bindingDescriptors is zero-length, or contains null or duplicate elements, or if componentMappings contains a mapping that cannot be used, for example the source and target identifiers represent different component types, or a component with the target identity already exists and cannot be reused for this service.

UnrecognizedServiceException - if id is not a recognizable ServiceID for the SLEE or it does not correspond with a Service installed in the SLEE.

UnrecognizedBindingDescriptorException - if any member of bindingDescriptors is not a recognizable BindingDescriptorID for the SLEE or does not correspond with a binding descriptor installed in the SLEE.

BindingAlreadyExistsException - if any member of bindingDescriptors has already been added to the Service.

InvalidStateException - if the current state of the Service on all nodes is not ServiceState.INACTIVE

BindingVerificationException - if adding the bindings to the Service would cause the Service to have an invalid configuration. For example, a binding descriptor may reference a component that is not installed in the SLEE, or reference an SBB that is not part of the Service.

ManagementException - if the bindings could not be added to the Service due to a system-level failure.

Since:

Rhino 2.4.0

removeBinding

BindingResult removeBinding(ServiceID id,
                            BindingDescriptorID bindingDescriptor,
                            boolean dryrun)
                     throws NullPointerException,
                            UnrecognizedServiceException,
                            UnrecognizedBindingDescriptorException,
                            NoSuchBindingException,
                            InvalidStateException,
                            BindingVerificationException,
                            ManagementException

Remove an existing binding from a Service. Components in the Service may revert to their original deployed state as the deployment metadata contained by the specified binding descriptor is removed.

Bindings can only be removed from a Service that is in the INACTIVE state.

This method will implicitly remove copied dependent components no longer required due to the removal of the binding. A copied Service component however will not be removed - this must be removed separately if no longer required.

After the binding operation completes, affected components that remain will have an install level of InstallLevel.VERIFIED.

Parameters:

id - the component identifier of the Service.

bindingDescriptor - the component identifier of the binding descriptor.

dryrun - if true, the SLEE will validate the binding operation and return the result as if the binding operation completed, but will not actually commit any changes to the SLEE.

Returns:

the result of the binding operation.

Throws:

NullPointerException - if id or bindingDescriptor is null.

UnrecognizedServiceException - if id is not a recognizable ServiceID for the SLEE or it does not correspond with a Service installed in the SLEE.

UnrecognizedBindingDescriptorException - if bindingDescriptor is not a recognizable BindingDescriptorID for the SLEE or it does not correspond with a binding descriptor installed in the SLEE.

NoSuchBindingException - if the binding descriptor has not been added to the Service.

InvalidStateException - if the current state of the Service on all nodes is not ServiceState.INACTIVE

BindingVerificationException - if removing the binding from the Service would cause the Service to have an invalid configuration. For example, remaining bindings may reference a component that is no longer part of the Service.

ManagementException - if the bindings could not be removed from the Service due to a system-level failure.

Since:

Rhino 2.4.0

removeBindings

BindingResult removeBindings(ServiceID id,
                             BindingDescriptorID[] bindingDescriptors,
                             boolean dryrun)
                      throws NullPointerException,
                             InvalidArgumentException,
                             UnrecognizedServiceException,
                             UnrecognizedBindingDescriptorException,
                             NoSuchBindingException,
                             InvalidStateException,
                             BindingVerificationException,
                             ManagementException

Remove one or more existing bindings from a Service. Components in the Service may revert to their original deployed state as the deployment metadata contained by the specified binding descriptor is removed.

Bindings can only be removed from a Service that is in the INACTIVE state.

This method will implicitly remove copied dependent components no longer required due to the removal of the binding. A copied Service component however will not be removed - this must be removed separately if no longer required.

After the binding operation completes, affected components that remain will have an install level of InstallLevel.VERIFIED.

Parameters:

id - the component identifier of the Service.

bindingDescriptors - the component identifiers of the binding descriptors.

dryrun - if true, the SLEE will validate the binding operation and return the result as if the binding operation completed, but will not actually commit any changes to the SLEE.

Returns:

the result of the binding operation.

Throws:

NullPointerException - if id or bindingDescriptors is null.

InvalidArgumentException - if bindingDescriptors is zero-length, or contains null or duplicate elements.

UnrecognizedServiceException - if id is not a recognizable ServiceID for the SLEE or it does not correspond with a Service installed in the SLEE.

UnrecognizedBindingDescriptorException - if any member of bindingDescriptors is not a recognizable BindingDescriptorID for the SLEE or does not correspond with a binding descriptor installed in the SLEE.

NoSuchBindingException - if any member of bindingDescriptors is not currently associated with the Service.

InvalidStateException - if the current state of the Service on all nodes is not ServiceState.INACTIVE

BindingVerificationException - if removing the binding descriptor associations would cause the service to have an invalid configuration. For example, a binding descriptor association that remains may reference an SBB that is no longer part of the service.

ManagementException - if the binding descriptors could not be associated with the Service due to a system-level failure.

Since:

Rhino 2.4.0

getBindings

BindingDescriptorID[] getBindings(ServiceID id)
                           throws NullPointerException,
                                  UnrecognizedServiceException,
                                  ManagementException

Get the set of binding descriptors currently associated with a Service.

Parameters:

id - the component identifier of the Service.

Returns:

an array of binding descriptor identifiers.

Throws:

NullPointerException - if id is null.

UnrecognizedServiceException - if id is not a recognizable ServiceID for the SLEE or it does not correspond with a Service installed in the SLEE.

ManagementException - if the identifiers could not be obtained due to a system-level failure.

Since:

Rhino 2.4.0

setReplicationSelectors

void setReplicationSelectors(ServiceID id,
                             ReplicationSelector[] selectors)
                      throws NullPointerException,
                             UnrecognizedServiceException,
                             InvalidStateException,
                             ManagementException

Set the replication selectors for a service. The replication selectors determine the conditions under which replication will be enabled for the service. If no condition matches at deployment time then the service will not be replicated.

The default replication selectors for a service can be specified in its deployment descriptor. This method allows those selectors to be changed after the service has been installed.

The replication selectors for a service can only be changed if the service is not yet deployed. That is, the install level of the service component must be either InstallLevel.INSTALLED or InstallLevel.VERIFIED.

If a service has no replication selectors, it will never be replicated.

Parameters:

id - the component identifier of the Service.

selectors - the replication selectors. May be null as a substitute for an empty list to denote no selectors.

Throws:

NullPointerException - if id is null.

UnrecognizedServiceException - if id is not a recognisable ServiceID for the SLEE or it does not correspond with a Service installed in the SLEE.

InvalidStateException - if the install level of the service indicates that it is already deployed.

ManagementException - if the replication selectors could not be changed due to a system-level failure.

Since:

Rhino 2.6.1

getReplicationSelectors

ReplicationSelector[] getReplicationSelectors(ServiceID id)
                                       throws NullPointerException,
                                              UnrecognizedServiceException,
                                              ManagementException

Get the current replication selectors for a service.

Parameters:

id - the component identifier of the Service.

Returns:

the replication selectors, or an empty array if no selectors are present.

Throws:

NullPointerException - if id is null.

UnrecognizedServiceException - if id is not a recognisable ServiceID for the SLEE or it does not correspond with a Service installed in the SLEE.

ManagementException - if the replication selectors could not be obtained due to a system-level failure.

Since:

Rhino 2.6.1

getReplicationSelectors

ReplicationSelector[][] getReplicationSelectors(ServiceID[] services)
                                         throws NullPointerException,
                                                ManagementException

Get an array of the replication selectors corresponding to an array of Service component identifiers.

Parameters:

services - the array of Service component identifiers.

Returns:

an array of replication selectors. This array will be the same length as the supplied array, and if replicationSelectors = getReplicationSelectors(services) then replicationSelectors[i] == getReplicationSelector(services[i]). Any unrecognised component identifier present in services results in a null value at the corresponding array index in this array.

Throws:

NullPointerException - if services is null.

ManagementException - if the replication selectors could not be obtained due to a system-level failure.

Since:

Rhino 2.6.1

setStartingPriority

void setStartingPriority(ServiceID service,
                         byte priority)
                  throws NullPointerException,
                         UnrecognizedServiceException,
                         ManagementException

Set the starting priority for a Service. The starting priority determines the order in which services and resource adaptor entities together are started when the SLEE transitions from the STOPPED state to the RUNNING state.

Priorities are values between -128 and 127. If a component (service or resource adaptor entity), X, has a numerically higher priority value than another component, Y, then X will be started before Y. Components with the same priority may be started in an arbitrary order, or may be started concurrently.

Parameters:

service - the component identifier of the Service.

priority - the starting priority for the Service.

Throws:

NullPointerException - if id is null.

UnrecognizedServiceException - if id is not a recognizable ServiceID for the SLEE or it does not correspond with a Service installed in the SLEE.

ManagementException - if the starting priority of the service could not be updated due to a system-level failure.

Since:

Rhino 2.4.0

See Also:

setStoppingPriority(ServiceID, byte)

getStartingPriority

byte getStartingPriority(ServiceID service)
                  throws NullPointerException,
                         UnrecognizedServiceException,
                         ManagementException

Get the starting priority for a Service.

Parameters:

service - the component identifier of the Service.

Returns:

the starting priority of the Service.

Throws:

NullPointerException - if id is null.

UnrecognizedServiceException - if id is not a recognizable ServiceID for the SLEE or it does not correspond with a Service installed in the SLEE.

ManagementException - if the starting priority of the service could not be obtained due to a system-level failure.

Since:

Rhino 2.4.0

See Also:

setStartingPriority(ServiceID, byte)

getStartingPriorities

Byte[] getStartingPriorities(ServiceID[] services)
                      throws NullPointerException,
                             ManagementException

Get an array of starting priorities corresponding to an array of Service component identifiers.

Parameters:

services - the array of Service component identifiers.

Returns:

an array of starting priorities. This array will be the same length as the supplied array, and if priorities = getStartingPriorities(services) then priorities[i] == getStartingPriority(services[i]). Any unrecognised component identifier present in services results in a null value at the corresponding array index in this array.

Throws:

NullPointerException - if services is null.

ManagementException - if the starting priorities could not be obtained due to a system-level failure.

Since:

Rhino 2.4.0

setStoppingPriority

void setStoppingPriority(ServiceID service,
                         byte priority)
                  throws NullPointerException,
                         UnrecognizedServiceException,
                         ManagementException

Set the stopping priority for a Service. The stopping priority determines the order in which services and resource adaptor entities together are stopped when the SLEE transitions from the RUNNING state to the STOPPING state.

Priorities are values between -128 and 127. If a component (service or resource adaptor entity), X, has a numerically higher priority value than another component, Y, then X will be stopped before Y. Components with the same priority may be stopped in an arbitrary order, or may be stopped concurrently.

Parameters:

service - the component identifier of the Service.

priority - the stopping priority for the Service.

Throws:

NullPointerException - if id is null.

UnrecognizedServiceException - if id is not a recognizable ServiceID for the SLEE or it does not correspond with a Service installed in the SLEE.

ManagementException - if the stopping priority of the service could not be updated due to a system-level failure.

Since:

Rhino 2.4.0

See Also:

setStartingPriority(ServiceID, byte)

getStoppingPriority

byte getStoppingPriority(ServiceID service)
                  throws NullPointerException,
                         UnrecognizedServiceException,
                         ManagementException

Get the stopping priority for a Service.

Parameters:

service - the component identifier of the Service.

Returns:

the stopping priority of the Service.

Throws:

NullPointerException - if id is null.

UnrecognizedServiceException - if id is not a recognizable ServiceID for the SLEE or it does not correspond with a Service installed in the SLEE.

ManagementException - if the stopping priority of the service could not be obtained due to a system-level failure.

Since:

Rhino 2.4.0

See Also:

setStoppingPriority(ServiceID, byte)

getStoppingPriorities

Byte[] getStoppingPriorities(ServiceID[] services)
                      throws NullPointerException,
                             ManagementException

Get an array of stopping priorities corresponding to an array of Service component identifiers.

Parameters:

services - the array of Service component identifiers.

Returns:

an array of stopping priorities. This array will be the same length as the supplied array, and if priorities = getStoppingPriorities(services) then priorities[i] == getStoppingPriority(services[i]). Any unrecognised component identifier present in services results in a null value at the corresponding array index in this array.

Throws:

NullPointerException - if services is null.

ManagementException - if the stopping priorities could not be obtained due to a system-level failure.

Since:

Rhino 2.4.0

setServiceMetricsRecordingEnabled

void setServiceMetricsRecordingEnabled(ServiceID service,
                                       boolean enabled)
                                throws NullPointerException,
                                       UnrecognizedServiceException,
                                       ManagementException

Enable or disable the recording of metrics for a service. Metrics are recorded using Rhino’s statistics subsystem and may be viewed using any statistics client.

A small performance overhead may be noted when metrics recording is enabled.

Parameters:

service - the component identifier of the Service.

enabled - boolean flag indicating if metrics should be enabled (true or disabled (false).

Throws:

NullPointerException - if id is null.

UnrecognizedServiceException - if id is not a recognizable ServiceID for the SLEE or it does not correspond with a Service installed in the SLEE.

ManagementException - if the metrics recording status could not be updated due to a system-level failure.

getServiceMetricsRecordingEnabled

boolean getServiceMetricsRecordingEnabled(ServiceID service)
                                   throws NullPointerException,
                                          UnrecognizedServiceException,
                                          ManagementException

Determine if the recording of metrics for a service is currently enabled or disabled.

Parameters:

service - the component identifier of the Service.

Returns:

true if metrics recording is currently enabled for the service, false otherwise.

Throws:

NullPointerException - if id is null.

UnrecognizedServiceException - if id is not a recognizable ServiceID for the SLEE or it does not correspond with a Service installed in the SLEE.

ManagementException - if the metrics recording status could not be obtained due to a system-level failure.