com.microfocus.awm.control

## Class ActionExecutor

- java.lang.Object
- - com.microfocus.awm.control.ActionExecutor

-     public class ActionExecutor
      extends java.lang.Object

  Executes modeled `ActionDescriptor`s.

  Executing an Action will create an `IExecutionContext`, which uniquely saves every available Property in its context (which will be an `IResource` most of the times). This context can be filled with additional Properties programmatically. Furthermore the IExecutionContext stores every single output parameter from any executed tool during the action execution.

  The ActionExecutor also creates an element list, if the following conditions are met:

  - At least one tool descriptor of the action properly returns a structured file descriptor.
  - The action has been executed as a `Get Children` or `Get Root Containers` action, or:
  - The action descriptor contains a `Has Elementlist` reference to an element list structure.

  The ActionExecutor also checks for the tool's return codes, processes exceptions, return codes and `ResourceOperation`s returned by tools.

  Not intended to be sub-classed by clients.

  Author:
    Micro Focus
  See Also:
    `IToolExecutor2`, `ToolDescriptor`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `class` | `ActionExecutor.ActionExecutorJob` Implementation of `Job` to execute an `ActionDescriptor` in the background.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `TOOL_EXECUTOR_EXT_POINT_ID`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ActionExecutor(ActionDescriptor pActDescr, IExecutionContext pContext)` Basic constructor.
    `ActionExecutor(ActionDescriptor pActDescr, ISystemImage pImg, IResource pRes)` Creates an ActionExecutor instance with a single `IResource` as context.
    `ActionExecutor(ActionDescriptor pActDescr, ISystemImage pImg, java.util.List<IResource> pResources)` Creates an ActionExecutor instance with multiple `IResource`s as context.
    `ActionExecutor(ITaurusJob pJob, IExecutionContext pContext)` Constructor for creating an action descriptor for a "run as job after action".

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `addActionListener(TaurusActionListener pListener)` Adds a `TaurusActionListener` to the executor.
    `static java.lang.String` | `createActionExecutionExceptionMessage(ActionDescriptor pActDescr)` Creates a general error message when the execution of an action descriptor fails with an exception.
    `static java.lang.String` | `createActionExecutionExceptionMessage(ActionDescriptor pActDescr, java.lang.Throwable pE)` Creates a general error message when the execution of an action descriptor fails with an exception.
    `static java.util.Map<java.lang.String,ToolTypeExtension>` | `createToolTypeMap()` Creates and returns a map of all available tool types and their corresponding tool executors.
    `ActionExecutorResult` | `execute(org.eclipse.core.runtime.IProgressMonitor pMon)` Executes the action.
    `static IAction` | `executeAction(IExecutionContext pActionContext, ActionDescriptor pActDesc, org.eclipse.core.runtime.IProgressMonitor pMon)` Deprecated. Not thread safe and doesn't throw exceptions. Use any of the create(...) methods to create an action executor instance and then `execute(IProgressMonitor)` instead.
    `static IAction` | `executeAction(ISystemImage pImg, IResource pRes, ActionDescriptor pTauAction, org.eclipse.core.runtime.IProgressMonitor pMon)` Deprecated. Not thread safe and doesn't throw exceptions. Use any of the create(...) methods to create an action executor instance and then `execute(IProgressMonitor)` instead.
    `static IAction` | `executeAction(ISystemImage pImg, java.util.List<IResource> pResources, ActionDescriptor pActDescr, org.eclipse.core.runtime.IProgressMonitor pMon)` Deprecated. Not thread safe and doesn't throw exceptions. Use any of the create(...) methods to create an action executor instance and then `execute(IProgressMonitor)` instead.
    `IAction` | `executeWithWait(org.eclipse.core.runtime.IProgressMonitor pMon)` Executes the action and waits for it to finish if its execution mode was `EActionExecutionMode.MODELESS`.
    `ActionDescriptor` | `getActionDescriptor()` Gets the the `ActionDescriptor` of the action executor instance.
    `static java.util.List<TaurusActionListener>` | `getActionListeners()` Returns the list of registered action listeners.
    `static java.util.List<IValidationMessage>` | `getAllValidationMessages(IAction pValActionResult)` Gets all validation messages returned by all tools of an executed action.
    `IExecutionContext` | `getContext()` Gets the the `IExecutionContext` of the action executor instance.
    `static int` | `getModelessRunningCount()` Gets the the number of ActionExecutorJobs currently running.
    `static java.lang.String` | `getParameterValue(RToolInParameter pInparm, IExecutionContext pContext)` Calls `TaurusModelUtilities.getParameterValue(RToolInParameter, IExecutionContext)` .
    `static void` | `handleActionExcecutionException(TaurusException pExpception, ActionDescriptor pActDescr, IExecutionContext pContext)` Handles how the given exception occurred during execution of the given action descriptor should be processed.
    `static void` | `handleFileOutput(IToolContext pToolContext, IExecutionContext pExecutionContext, FileDescriptor targetIDFile, java.lang.Object pOutparmValue)` Handles a returned file output parameter by "describing" the referenced file descriptor and adding it to the parameter memory.
    `static boolean` | `isMassProcessing(IExecutionContext pContext, ToolDescriptor pTool)` Returns whether the action descriptor of the given context was modelled with `"Mass Processing = true`.
    `boolean` | `isParallelExecutionAllowed()` Returns whether executed MODELESS actions of this instance can run simunltaniously with other actions.
    `static ResourceOperation` | `parseResourceOperation(ToolDescriptor pTool, java.lang.String pLine, IExecutionContext pContext)` Deprecated. this method uses deprecated tool descriptor attributes. Use `AbstractCommandBasedToolExecutor.parseResourceOperation(ToolDescriptor, String, String, List, IExecutionContext)` instead.
    `static ValidateMessage` | `parseValidateMessage(java.lang.String pLine)` Tries to parse a validate message from the given line.
    `static boolean` | `removeActionListener(TaurusActionListener pListener)` Removes a `TaurusActionEvent` from the list of listeners.
    `void` | `setParallelExecutionAllowed(boolean pParallelExecution)` Sets whether executed MODELESS actions of this instance can run simunltaniously to other actions.
    `static void` | `setParmFilePath(java.lang.String pParmFilePath)` Deprecated. used by deprecated methods `executeAction(IExecutionContext, ActionDescriptor, IProgressMonitor)` , `executeAction(ISystemImage, IResource, ActionDescriptor, IProgressMonitor)` and `executeAction(ISystemImage, List, ActionDescriptor, IProgressMonitor)`
    `void` | `setSkipModelUpdateCheck(boolean pSkipModelUpdateCheck)` Set whether the model update check should be skipped.
    `static void` | `setTool(ToolDescriptor pTool)` Deprecated. used by deprecated methods `executeAction(IExecutionContext, ActionDescriptor, IProgressMonitor)` , `executeAction(ISystemImage, IResource, ActionDescriptor, IProgressMonitor)` and `executeAction(ISystemImage, List, ActionDescriptor, IProgressMonitor)`

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### TOOL_EXECUTOR_EXT_POINT_ID

          public static final java.lang.String TOOL_EXECUTOR_EXT_POINT_ID

      See Also:
        `TaurusExtensionPointUtility.TOOL_EXECUTOR_EXT_POINT_ID`, Constant Field Values

  - ### Constructor Detail

    - #### ActionExecutor

          public ActionExecutor(ActionDescriptor pActDescr,
                                IExecutionContext pContext)

      Basic constructor.
      Parameters:
        `pActDescr` - the action descriptor.
        `pContext` - the context.

    - #### ActionExecutor

          public ActionExecutor(ActionDescriptor pActDescr,
                                ISystemImage pImg,
                                IResource pRes)

      Creates an ActionExecutor instance with a single `IResource` as context.
      Parameters:
        `pActDescr` - the action descriptor.
        `pImg` - the system image.
        `pRes` - the resource to create the context from.
      See Also:
        `ActionExecutor(ActionDescriptor, IExecutionContext)`

    - #### ActionExecutor

          public ActionExecutor(ActionDescriptor pActDescr,
                                ISystemImage pImg,
                                java.util.List<IResource> pResources)

      Creates an ActionExecutor instance with multiple `IResource`s as context.
      Parameters:
        `pActDescr` - the action descriptor.
        `pImg` - the system image.
        `pResources` - the list of resources (can be empty or `null`).
      See Also:
        `IExecutionContext.initContext(List)`

    - #### ActionExecutor

          public ActionExecutor(ITaurusJob pJob,
                                IExecutionContext pContext)

      Constructor for creating an action descriptor for a "run as job after action".
      Parameters:
        `pJob` - an `ITaurusJob`.
        `pContext` - the context.
      See Also:
        `ToolDescriptor.getRunAsJob()`, `ToolDescriptor.getAfterJobAction()`

  - ### Method Detail

    - #### executeAction

          @Deprecated
          public static IAction executeAction(ISystemImage pImg,
                                                           IResource pRes,
                                                           ActionDescriptor pTauAction,
                                                           org.eclipse.core.runtime.IProgressMonitor pMon)

      Deprecated. Not thread safe and doesn't throw exceptions. Use any of the create(...) methods to create an action executor instance and then `execute(IProgressMonitor)` instead.
      Executes any `ActionDescriptor` which was defined in the TAURUS configuration file.
      Parameters:
        `pImg` - the `ISystemImage` of the remote (or local) system.
        `pRes` - the corresponding `IResource`
        `pTauAction` - the ActionDescriptor
        `pMon` - an `IProgressMonitor`
      Returns:
        an `IAction` which contains information about the executed action (even if the action was interrupted by an exception)

    - #### executeAction

          @Deprecated
          public static IAction executeAction(IExecutionContext pActionContext,
                                                           ActionDescriptor pActDesc,
                                                           org.eclipse.core.runtime.IProgressMonitor pMon)

      Deprecated. Not thread safe and doesn't throw exceptions. Use any of the create(...) methods to create an action executor instance and then `execute(IProgressMonitor)` instead.
      Executes any `ActionDescriptor` which was defined in the TAURUS configuration file.
      Parameters:
        `pActionContext` - the execution context to be used in this action.
        `pActDesc` - the ActionDescriptor
        `pMon` - an `IProgressMonitor`
      Returns:
        an `IAction` which contains information about the executed action (even if the action was interrupted by an exception)

    - #### execute

          public ActionExecutorResult execute(org.eclipse.core.runtime.IProgressMonitor pMon)
                                       throws TaurusException

      Executes the action. Returns either an `IAction` or an `ActionExecutor.ActionExecutorJob`, depending on whether the action execution mode was `EActionExecutionMode.MODAL` or `EActionExecutionMode.MODELESS`. If the action was modeless and a job is returned, the caller can wait for the job to finish and obtain the IAction from it afterwards.
      Parameters:
        `pMon` - a progress monitor.
      Returns:
        either an IAction (MODAL) or a ActionExecutorJob (MODELESS).
      Throws:
        `TaurusException` - if an exception occurs during executing the action or one of its tools.
      See Also:
        `executeWithWait(IProgressMonitor)`, `ActionExecutor.ActionExecutorJob.getAction()`

    - #### executeWithWait

          public IAction executeWithWait(org.eclipse.core.runtime.IProgressMonitor pMon)
                                  throws TaurusException

      Executes the action and waits for it to finish if its execution mode was `EActionExecutionMode.MODELESS`.

      This method should not be called in a separate thread to not block the main thread and preserve the idea behind modeless actions.

      Parameters:
        `pMon` - a progress monitor. Must not be `null`.
      Returns:
        an `IAction`.
      Throws:
        `TaurusException` - if an exception occurs during executing the action or one of its tools.
      See Also:
        `execute(IProgressMonitor)`

    - #### getModelessRunningCount

          public static int getModelessRunningCount()

      Gets the the number of ActionExecutorJobs currently running.
      Returns:
        the number of executing jobs

    - #### executeAction

          @Deprecated
          public static IAction executeAction(ISystemImage pImg,
                                                           java.util.List<IResource> pResources,
                                                           ActionDescriptor pActDescr,
                                                           org.eclipse.core.runtime.IProgressMonitor pMon)

      Deprecated. Not thread safe and doesn't throw exceptions. Use any of the create(...) methods to create an action executor instance and then `execute(IProgressMonitor)` instead.
      Executes any `ActionDescriptor` which was defined in the TAURUS configuration file. Supports mass processing execution.
      Parameters:
        `pImg` - the `ISystemImage` of the remote (or local) system.
        `pResources` - a list of selected `IResource`s. Can be empty or `null`.
        `pActDescr` - the ActionDescriptor
        `pMon` - an `IProgressMonitor`
      Returns:
        an `IAction` which contains information about the executed action (even if the action was interrupted by an exception)
      See Also:
        `ActionDescriptor.isMassProcessing()`

    - #### handleFileOutput

          public static void handleFileOutput(IToolContext pToolContext,
                                              IExecutionContext pExecutionContext,
                                              FileDescriptor targetIDFile,
                                              java.lang.Object pOutparmValue)
                                       throws TaurusToolException

      Handles a returned file output parameter by "describing" the referenced file descriptor and adding it to the parameter memory.
      Parameters:
        `pToolContext` - the tool context
        `pExecutionContext` - execution context
        `targetIDFile` - referenced target file descriptor
        `pOutparmValue` - returned parameter value
      Throws:
        `TaurusToolException` - if the returned value type is not compatible with the referenced file descriptor

    - #### isParallelExecutionAllowed

          public boolean isParallelExecutionAllowed()

      Returns whether executed MODELESS actions of this instance can run simunltaniously with other actions.
      Returns:
        whether actions executed by this instance can run simultaneously.
      See Also:
        `setParallelExecutionAllowed(boolean)`

    - #### setParallelExecutionAllowed

          public void setParallelExecutionAllowed(boolean pParallelExecution)

      Sets whether executed MODELESS actions of this instance can run simunltaniously to other actions.
      Parameters:
        `pParallelExecution` - whether actions executed by this instance should be able to run simultaneously.

    - #### createToolTypeMap

          public static java.util.Map<java.lang.String,ToolTypeExtension> createToolTypeMap()

      Creates and returns a map of all available tool types and their corresponding tool executors. These are defined by extensions of the extension point "com.microfocus.awm.toolexecutor".
      Returns:
        a map of all available tool types and their tool executors.

    - #### setParmFilePath

          @Deprecated
          public static void setParmFilePath(java.lang.String pParmFilePath)

      Deprecated. used by deprecated methods `executeAction(IExecutionContext, ActionDescriptor, IProgressMonitor)` , `executeAction(ISystemImage, IResource, ActionDescriptor, IProgressMonitor)` and `executeAction(ISystemImage, List, ActionDescriptor, IProgressMonitor)`
      Sets the parameter file path for the execution of an after job action.
      Parameters:
        `pParmFilePath` - the parameter file path to set

    - #### setTool

          @Deprecated
          public static void setTool(ToolDescriptor pTool)

      Deprecated. used by deprecated methods `executeAction(IExecutionContext, ActionDescriptor, IProgressMonitor)` , `executeAction(ISystemImage, IResource, ActionDescriptor, IProgressMonitor)` and `executeAction(ISystemImage, List, ActionDescriptor, IProgressMonitor)`
      Sets the tool descriptor for the execution of an after job action.
      Parameters:
        `pTool` - the tool descriptor to set.

    - #### getParameterValue

          public static java.lang.String getParameterValue(RToolInParameter pInparm,
                                                           IExecutionContext pContext)
                                                    throws TaurusToolException

      Calls `TaurusModelUtilities.getParameterValue(RToolInParameter, IExecutionContext)` .
      Parameters:
        `pInparm` - the input parameter to be resolved.
        `pContext` - the execution context which should contain the value.
      Returns:
        the resolved value or `null` if the value was neither static, found in the context and no default value exists.
      Throws:
        `TaurusToolException` - if the property value could not be found in the execution context and neither a static- nor a default value is set.
      See Also:
        `TaurusModelUtilities.getParameterValue(RToolInParameter, IExecutionContext)`

    - #### parseValidateMessage

          public static ValidateMessage parseValidateMessage(java.lang.String pLine)
                                                      throws TaurusToolException

      Tries to parse a validate message from the given line. Does nothing (returns `null`) if the line does not start with `VALMSG`.
      Parameters:
        `pLine` - the line
      Returns:
        a `ValidateMessage` or `null`
      Throws:
        `TaurusToolException` - if the validate message line is invalid

    - #### parseResourceOperation

          @Deprecated
          public static ResourceOperation parseResourceOperation(ToolDescriptor pTool,
                                                                              java.lang.String pLine,
                                                                              IExecutionContext pContext)
                                                                       throws TaurusToolException

      Deprecated. this method uses deprecated tool descriptor attributes. Use `AbstractCommandBasedToolExecutor.parseResourceOperation(ToolDescriptor, String, String, List, IExecutionContext)` instead.
      Parses a resource operation if the given line starts with one of the resource operation keywords (see `EResourceProcessingTypes`). Returns `null` if the line is not a valid resource operation or does not contain a resource operation at all.
      Parameters:
        `pTool` - the tool which returned the line as outout.
        `pLine` - the line which might contain a resource operation.
        `pContext` - the context.
      Returns:
        a resource operation or `null`.
      Throws:
        `TaurusToolException` - if an error occurs during parsing of resource operation parameters.

    - #### addActionListener

          public static void addActionListener(TaurusActionListener pListener)

      Adds a `TaurusActionListener` to the executor.
      Parameters:
        `pListener` - an implementation of the `TaurusActionListener`.
      See Also:
        `getActionListeners()`, `removeActionListener(TaurusActionListener)`

    - #### removeActionListener

          public static boolean removeActionListener(TaurusActionListener pListener)

      Removes a `TaurusActionEvent` from the list of listeners. Does nothing if the handed listener was not found. #see `addActionListener(TaurusActionListener)`
      Parameters:
        `pListener` - an implementation of the `TaurusActionListener`.
      Returns:
        `true` if the listener has been removed. `false` if it wasn't contained in the list of active listeners.

    - #### getActionListeners

          public static java.util.List<TaurusActionListener> getActionListeners()

      Returns the list of registered action listeners. The list can be manipulated.
      Returns:
        the list of added action listeners.
      See Also:
        `addActionListener(TaurusActionListener)`

    - #### isMassProcessing

          public static boolean isMassProcessing(IExecutionContext pContext,
                                                 ToolDescriptor pTool)

      Returns whether the action descriptor of the given context was modelled with `"Mass Processing = true`. This method can be used by tool executors which do not want to check whether the given context contains an action descriptor. Creates a trace message and returns `false` if the action descriptor of the given context is `null`.
      Parameters:
        `pContext` - an `IExecutionContext`.
        `pTool` - the tool descriptor being executed.
      Returns:
        `true` if the context has an action descriptor with mass processing set to `true`. Otherwise returns `false`.
      See Also:
        `ActionDescriptor.isMassProcessing()`

    - #### createActionExecutionExceptionMessage

          public static java.lang.String createActionExecutionExceptionMessage(ActionDescriptor pActDescr)

      Creates a general error message when the execution of an action descriptor fails with an exception.

      Example result:
      `"An error occurred while executing the action 'My Action'."`

      Parameters:
        `pActDescr` - the action descriptor which failed executing.
      Returns:
        a human readable message.
      See Also:
        `createActionExecutionExceptionMessage(ActionDescriptor, Throwable)`

    - #### handleActionExcecutionException

          public static void handleActionExcecutionException(TaurusException pExpception,
                                                             ActionDescriptor pActDescr,
                                                             IExecutionContext pContext)

      Handles how the given exception occurred during execution of the given action descriptor should be processed.
      Parameters:
        `pExpception` - the exception
        `pActDescr` - the action descriptor
        `pContext` - the execution context

    - #### createActionExecutionExceptionMessage

          public static java.lang.String createActionExecutionExceptionMessage(ActionDescriptor pActDescr,
                                                                               java.lang.Throwable pE)

      Creates a general error message when the execution of an action descriptor fails with an exception.

      If the optional Throwable parameter is not `null`, the method will return the first occurred detail message. This is not recommended for error dialogs which already show the reason right away, since the same massage will be visible several times. A good example for using this method with the Throwable parameter is creating an `IStatus` with an error message.

      Example (no detail message found):
      `"An error occurred while executing the action 'My Action'."`

      Example (detail message found in Throwable):
      `"The parameter 'xyz' was invalid."`

      Parameters:
        `pActDescr` - the action descriptor which failed executing.
        `pE` - (optional) the exception to get a more accurate message from. Can be `null`
      Returns:
        a human readable message.
      See Also:
        `createActionExecutionExceptionMessage(ActionDescriptor)`

    - #### getActionDescriptor

          public ActionDescriptor getActionDescriptor()

      Gets the the `ActionDescriptor` of the action executor instance.
      Returns:
        the action descriptor.

    - #### getContext

          public IExecutionContext getContext()

      Gets the the `IExecutionContext` of the action executor instance.
      Returns:
        the execution context.

    - #### setSkipModelUpdateCheck

          public void setSkipModelUpdateCheck(boolean pSkipModelUpdateCheck)

      Set whether the model update check should be skipped. Please note that only the first executed action of a model will run the update check.

      This is useful for actions being executed as "OnLoad" actions.

      Parameters:
        `pSkipModelUpdateCheck` - whether to skip the model update check
      See Also:
        `RApplicationAction.getExecutionType()`, `EApplicationActionExecutionType.ON_LOAD`

    - #### getAllValidationMessages

          public static java.util.List<IValidationMessage> getAllValidationMessages(IAction pValActionResult)

      Gets all validation messages returned by all tools of an executed action.
      Parameters:
        `pValActionResult` - the action result
      Returns:
        a list of all validation messages. Can be empty.

Copyright © 2015 Micro Focus GmbH. All rights reserved.