Package com.opencloud.rhino.management.service

Interface ServiceManagementMBean

    • Method Detail

      • activate

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

        Activate a set of Services on all nodes.

        This method has the same requirements and behaviour for each individual Service as specified for activate(ServiceID) except that the desired state of all specified Services is updated in a single transaction. If any Service fails to fulfil the necessary requirements for activation then none of the Services are activated.

        The sets of nodes where each Service has an effective desired state of ServiceDesiredState.inactive do not have to be the same. For example, if there are two event router nodes in a cluster: nodes 101 and 102, Service A has a desired state of inactive on node 101 and active on node 102, and Service B has a desired state of inactive on node 102 and active on node 101, it is still possible to successfully invoke this method specifying both Services and have Rhino activate each Service on the respective nodes where they are inactive.

        In difference to the methods that only set Service desired state and leave actual state transitions to the internal convergence subsystem, if this method returns by throwing an exception then the desired and actual states of the Services are left unchanged. For example, if an InvalidLinkNameBindingStateException is thrown, the corresponding Service actual state does not transition to ServiceActualState.failed on any node but remains as ServiceActualState.inactive.

        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 effective desired state of any of the Services identified by ids is not ServiceDesiredState.inactive on any current event router node.
        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.

        This method has the same requirements and behaviour for each individual Service as specified for activate(ServiceID, int[]) except that the desired state of all specified Services is updated in a single transaction. If any Service fails to fulfil the necessary requirements for activation then none of the Services are activated.

        The sets of nodes where each Service has an effective desired state of ServiceDesiredState.inactive do not have to be the same. For example, nodes 101 and 102 are specified, Service A has a desired state of inactive on node 101 and active on node 102, and Service B has a desired state of inactive on node 102 and active on node 101, it is still possible to successfully invoke this method specifying both Services and that set of node IDs and have Rhino activate each Service on the respective nodes where they are inactive.

        In difference to the methods that only set Service desired state and leave actual state transitions to the internal convergence subsystem, if this method returns by throwing an exception then the desired and actual states of the Services are left unchanged. For example, if an InvalidLinkNameBindingStateException is thrown, the corresponding Service actual state does not transition to ServiceActualState.failed on any node but remains as ServiceActualState.inactive.

        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 effective desired state of any of the Services identified by ids is not ServiceDesiredState.inactive on all specified nodes.
        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[] ids)
         throws NullPointerException,
                InvalidArgumentException,
                UnrecognizedServiceException,
                InvalidStateException,
                ManagementException

        Deactivate a set of Services on all nodes.

        This method has the same requirements and behaviour for each individual Service as specified for deactivate(ServiceID) except that the desired state of all specified Services is updated in a single transaction. If any Service fails to fulfil the necessary requirements for deactivation then none of the Services are deactivated.

        The sets of nodes where each Service has an effective desired state of ServiceDesiredState.active do not have to be the same. For example, if there are two event router nodes in a cluster: nodes 101 and 102, Service A has a desired state of inactive on node 101 and active on node 102, and Service B has a desired state of inactive on node 102 and active on node 101, it is still possible to successfully invoke this method specifying both Services and have Rhino deactivate each Service on the respective nodes where they are active.

        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 effective desired state of any of the Services identified by ids is not ServiceDesiredState.active on any current event router node.
        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.

        This method has the same requirements and behaviour for each individual Service as specified for deactivate(ServiceID, int[]) except that the desired state of all specified Services is updated in a single transaction. If any Service fails to fulfil the necessary requirements for deactivation then none of the Services are deactivated.

        The sets of nodes where each Service has an effective desired state of ServiceDesiredState.active do not have to be the same. For example, nodes 101 and 102 are specified, Service A has a desired state of inactive on node 101 and active on node 102, and Service B has a desired state of inactive on node 102 and active on node 101, it is still possible to successfully invoke this method specifying both Services and that set of node IDs and have Rhino deactivate each Service on the respective nodes where they are active.

        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 effective desired state of any of the Services identified by ids is not ServiceDesiredState.active on all specified nodes.
        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 a Service and activate another Service on all nodes.

        The deactivating Service must currently have an effective desired state of ServiceDesiredState.active on at least one live event routing node, as determined by RhinoHousekeepingMBean.getEventRouterNodes(). The activating Service must currently have an effective desired state of ServiceDesiredState.inactive on at least one live event routing node. The sets of event router nodes where the deactivating Service has a desired state of ServiceDesiredState.active and where the activating Service has a desired state of ServiceDesiredState.inactive do not have to be the same.

        All per-node desired state for both Services is removed by this method. The default desired state of the deactivating Service is set to ServiceDesiredState.inactive and the default desired state of the activating Service is set to ServiceDesiredState.active (if they are not already). Then, before this method returns, the deactivating Service transitions to an actual state of ServiceActualState.stopping on all event router nodes where the actual state is currently ServiceActualState.active, and an attempt is made to transition the activating Service to an actual state of ServiceActualState.active on all event router nodes where the actual state is currently ServiceActualState.inactive. Any node where the activating Service’s actual state is ServiceActualState.stopping will wait (asynchronously) until the Service reaches the ServiceActualState.inactive state and then attempt to transition the Service back to ServiceActualState.active.

        As a result of this method setting default desired states, any new event router nodes that boot into the cluster will assume the updated desired state for the Services unless per-node desired state is subsequently created to state otherwise.

        In difference to the methods that only set Service desired state and leave actual state transitions to the internal convergence subsystem, if this method returns by throwing an exception then the desired and actual states of the Services are left unchanged. For example, if an InvalidLinkNameBindingStateException is thrown, the corresponding Service actual state does not transition to ServiceActualState.failed on any node but remains as ServiceActualState.inactive.

        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 effective desired state of the Service identified by deactivateID on any current event router node is not ServiceDesiredState.active or the the effective desired state of the Service identified by activateID on any current event router node is not ServiceDesiredState.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 a Service and activate another Service on the specified nodes.

        The deactivating Service must currently have an effective desired state of ServiceDesiredState.active and the activating Service must currently have an effective desired state of ServiceDesiredState.inactive on all the specified nodes. Per-node desired state for both Services is created for each specified node if it does not already exist. The per-node desired state of the deactivating Service is set to ServiceDesiredState.inactive and the per-node desired state of the activating Service is set to ServiceDesiredState.active. Then, before this method returns, the deactivating Service transitions to an actual state of ServiceActualState.stopping on all specified nodes that are current live event router nodes where the actual state is currently ServiceActualState.active, and an attempt is made to transition the activating Service to an actual state of ServiceActualState.active on all specified nodes that are current live event router nodes where the actual state is currently ServiceActualState.inactive. Any relevant node where the activating Service’s actual state is ServiceActualState.stopping will wait (asynchronously) until the Service reaches the ServiceActualState.inactive state and then attempt to transition the Service back to ServiceActualState.active.

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

        This method does not affect the default desired state of either Service.

        In difference to the methods that only set Service desired state and leave actual state transitions to the internal convergence subsystem, if this method returns by throwing an exception then the desired and actual states of the Services are left unchanged. For example, if an InvalidLinkNameBindingStateException is thrown, the corresponding Service actual state does not transition to ServiceActualState.failed on any node but remains as ServiceActualState.inactive.

        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 effective desired state of the Service identified by deactivateID is not ServiceDesiredState.active on all specified nodes, or the the effective desired state of the Service identified by activateID is not ServiceDesiredState.inactive on all specified nodes.
        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 nodes.

        This method has the same requirements and behaviour for each individual Service as specified for deactivateAndActivate(ServiceID, ServiceID) except that the desired state of all specified Services is updated in a single transaction. If any Service fails to fulfil the necessary requirements for deactivation or activation then none of the Services are affected.

        The sets of nodes where each Service has the required effected desired state do not have to be the same.

        In difference to the methods that only set Service desired state and leave actual state transitions to the internal convergence subsystem, if this method returns by throwing an exception then the desired and actual states of the Services are left unchanged. For example, if an InvalidLinkNameBindingStateException is thrown, the corresponding Service actual state does not transition to ServiceActualState.failed on any node but remains as ServiceActualState.inactive.

        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 effective desired state of any of the Services identified by deactivateIDs on any current event router node is not ServiceDesiredState.active or the the effective desired state of any of the Services identified by activateIDs on any current event router node is not ServiceDesiredState.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.

        This method has the same requirements and behaviour for each individual Service as specified for deactivateAndActivate(ServiceID, ServiceID, int[]) except that the desired state of all specified Services is updated in a single transaction. If any Service fails to fulfil the necessary requirements for deactivation or activation then none of the Services are affected.

        The sets of nodes where each Service has the required effected desired state do not have to be the same.

        In difference to the methods that only set Service desired state and leave actual state transitions to the internal convergence subsystem, if this method returns by throwing an exception then the desired and actual states of the Services are left unchanged. For example, if an InvalidLinkNameBindingStateException is thrown, the corresponding Service actual state does not transition to ServiceActualState.failed on any node but remains as ServiceActualState.inactive.

        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 effective desired state of any of the Services identified by deactivateIDs is not ServiceDesiredState.active on all specified nodes, or the the effective desired state of any of the Services identified by activateIDs is not ServiceDesiredState.inactive on all specified nodes.
        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(). This method translates the actual state of each Service on the node to an equivalent JAIN SLEE-defined state for comparison purposes.

        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 Services on a node yet to be started.

        This method translates the desired or actual state of each Service to an equivalent JAIN SLEE-defined state for comparison purposes depending on the presence of the specified node. If the specified node is a current live event router node, then actual state is used. Otherwise, desired state is used.

        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,
                        int[] nodeIDs)
                 throws NullPointerException,
                        InvalidArgumentException,
                        UnrecognizedServiceException,
                        ManagementException

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

        This method translates the desired or actual state of the Service on each specified node to an equivalent JAIN SLEE-defined state depending on the presence of the node. For nodes that are current live event router nodes, actual state is used. For nodes that are not cluster members or are not event router nodes, desired state is used.

        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.

        This method translates the actual state of the Service on each node to an equivalent JAIN SLEE-defined state for comparison purposes.

        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.

      • 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

      • 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[] 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)

      • 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)

      • 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.

      • getDefaultInitialPersistenceEnabled

        boolean getDefaultInitialPersistenceEnabled​(ServiceID id)
                                     throws UnrecognizedServiceException,
                                            ManagementException

        Get the default initial persistence enabled status for a Service as specified in its descriptor.

        Parameters:
        id - the component identifier of the Service.
        Returns:
        the default initial persistence enabled status 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 initial persistence status could not be obtained due to a system-level failure.
        Since:
        Rhino 2.6.2

      • getPerNodeDesiredState

        ServiceDesiredState getPerNodeDesiredState​(ServiceID id,
                                           int nodeID)
                                    throws NullPointerException,
                                           InvalidArgumentException,
                                           UnrecognizedServiceException,
                                           ManagementException

        Get the current per-node desired state of a Service on the specified node.

        If per-node state exists for the Service on the target node then the state contained therein is returned, otherwise null is returned instead.

        Parameters:
        id - the component identifier of the Service.
        nodeID - the node ID of the node to return the Service’s per-node desired state for.
        Returns:
        the current per-node desired state of the Service on the specified node, or null if no per-node desired state exists.
        Throws:
        NullPointerException - if id is null.
        InvalidArgumentException - if nodeID is an invalid node ID, or if the Service exists but does not have an install level of DEPLOYED.
        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.
        Since:
        Rhino 3.0.0

      • getPerNodeDesiredState

        ServiceDesiredState[] getPerNodeDesiredState​(ServiceID id,
                                             int[] nodeIDs)
                                      throws NullPointerException,
                                             InvalidArgumentException,
                                             UnrecognizedServiceException,
                                             ManagementException

        Get the current per-node desired state of a Service for each of the specified nodes.

        Where per-node state exists for the Service on a specified node then the state contained therein is returned, otherwise a null array entry is returned instead for that node.

        Parameters:
        id - the component identifier of the Service.
        nodeIDs - the node IDs of the nodes to return the Service’s per-node desired state for.
        Returns:
        an array of service desired state objects. This array will be the same length as the supplied nodeIDs array, and if states = getPerNodeDesiredState(id, nodeIDs) then states[i] equals the per-node desired state of the Service on node nodeIDs[i]. If there is no state information for the Service on a particular node, then null is returned as the resulting state for the Service on that node.
        Throws:
        NullPointerException - if either argument is null.
        InvalidArgumentException - if nodeIDs contains invalid node IDs, or if the Service exists but does not have an install level of DEPLOYED.
        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.
        Since:
        Rhino 3.0.0

      • getActualState

        ServiceActualState[] getActualState​(ServiceID id,
                                    int[] nodeIDs)
                             throws NullPointerException,
                                    InvalidArgumentException,
                                    UnrecognizedServiceException,
                                    ManagementException

        Get the current actual state of a Service for each of the specified nodes.

        Where per-node state exists for the Service on a target node then the state contained therein is returned, otherwise a null array entry is returned instead for that node.

        Parameters:
        id - the component identifier of the Service.
        nodeIDs - the node IDs of the nodes to return the Service’s actual state for.
        Returns:
        an array of service actual state objects. This array will be the same length as the supplied nodeIDs array, and if states = getActualState(id, nodeIDs) then states[i] equals the actual state of the Service on node nodeIDs[i]. If there is no state information for the Service on a particular node, then null is returned as the resulting state for the Service on that node.
        Throws:
        NullPointerException - if either argument is null.
        InvalidArgumentException - if nodeIDs contains invalid node IDs, or if the Service exists but does not have an install level of DEPLOYED.
        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.
        Since:
        Rhino 3.0.0

      • removePerNodeDesiredState

        void removePerNodeDesiredState​(ServiceID id,
                               int[] nodeIDs)
                        throws NullPointerException,
                               InvalidArgumentException,
                               UnrecognizedServiceException,
                               ManagementException

        Remove the per-node desired state for a Service on each of the specified nodes. This will revert the desired state of the Service on each specified node to the current default desired state.

        This method does nothing for any specified node that does not currently contain any per-node desired state for the Service.

        Parameters:
        id - the component identifier of the Service.
        nodeIDs - the node IDs of the nodes to remove the Service’s per-node desired state for.
        Throws:
        NullPointerException - if any argument is null.
        InvalidArgumentException - if nodeIDs contains invalid node IDs, or if the Service exists but does not have an install level of DEPLOYED.
        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 per-node desired state of the Service could not be removed due to a system-level failure.
        Since:
        Rhino 3.0.0