org.rhq.core.pluginapi.operation
Interface OperationFacet

public interface OperationFacet

This facet must be implemented by resource components that want to expose one or more operations.

Method Summary

OperationResult

invokeOperation(String name, Configuration parameters) Invoke the operation with the specified name and returns a result set consisting of configuration propeties.

Method Detail

invokeOperation

OperationResult invokeOperation(String name,
                                Configuration parameters)
                                throws InterruptedException,
                                       Exception

Invoke the operation with the specified name and returns a result set consisting of configuration propeties.

Plugin developers must write implementations of this method with the awareness that operations are cancelable and should prepare for such a possiblity in the code. For example, a user may request that an operation be canceled, or an operation may be taking to long and it should be canceled due to a timeout expiration. When an operation invocation is canceled, the thread that is invoking this method will be interrupted. The plugin writer has a choice to make - either write this method implementation such that it ignores cancelation requests (in effect continue doing what it is doing and return normally) or handle the cancelation request and stop doing what it is doing and throw an InterruptedException to indicate the operation was aborted. Note that if an implementation does not throw an InterruptedException, the plugin container will assume the operation did not cancel itself. If, even after an interrupt, the implementation returns normally, the plugin container will assume the operation was successful and will be marked as such.

Plugin writers are encouraged to check the current thread's Thread.isInterrupted() method periodically to catch cancellation requests, as well as catching and processing InterruptedException appropriately. Plugin writers must also ensure that they do not leave the managed resource in an inconsistent state after being canceled or timed out.

If a plugin determines that the operation invocation failed for whatever reason, this method must throw an Exception, which indicates a failure. If this method returns normally with any OperationResult (even if it is null), the operation invocation will assumed to have been a success. The only caveat is if the returned object has its error message set, in which case, the operation is also assumed to have failed.

Parameters:

name - the name of the operation

parameters - the parameters passed to the operation; even for operations with no parameters, an empty config will be passed in by the plugin container

Returns:

the result of the invocation

Throws:

InterruptedException - if this operation was canceled

Exception - if failed to invoke the operation on the resource