com.microfocus.awm.control

## Class OSCommandExecutor

- java.lang.Object
- - com.microfocus.awm.control.AbstractTaurusToolExecutor
  - - com.microfocus.awm.control.OSCommandExecutor

- All Implemented Interfaces:
    IToolExecutor
  Direct Known Subclasses:
    OSCommandToolExecutor

      public class OSCommandExecutor
      extends AbstractTaurusToolExecutor

  Executes `OS Command` AWM tools by running commands on the operating system. The commands to run are defined by tool input parameters.

  Copyright (C) Micro Focus. All rights reserved.

  Author:
    Micro Focus

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `OSCommandExecutor()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `ToolExecutionStatus` | `execTool(IExecutionContext pContext, ToolDescriptor pTool, java.lang.String pAffectedResName, org.eclipse.core.runtime.IProgressMonitor pMon)` Called by AWM as soon as the tool is executed within an action.
    `IToolOutputReader` | `getOutputReader()` Returns the implementation of the IToolOutputReader which is used for reading the tool output of the implemented IToolExecutor.
    `java.util.List<java.lang.String>` | `readParmFile(ISystemImage pImg, java.lang.String pParmFilePath, org.eclipse.core.runtime.IProgressMonitor pMon)` Converts the contents of a parameter file into a list of strings (lines).

    - ### Methods inherited from class com.microfocus.awm.control.AbstractTaurusToolExecutor

      `createMassOutputParameters, createSingleOutputParameters`

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

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

- - ### Constructor Detail

    - #### OSCommandExecutor

          public OSCommandExecutor()

  - ### Method Detail

    - #### execTool

          public ToolExecutionStatus execTool(IExecutionContext pContext,
                                              ToolDescriptor pTool,
                                              java.lang.String pAffectedResName,
                                              org.eclipse.core.runtime.IProgressMonitor pMon)
                                       throws TaurusToolException

      Description copied from interface: `IToolExecutor`
      Called by AWM as soon as the tool is executed within an action.

      ## General

      - Use `IProgressMonitor.setCanceled(boolean)` to cancel the execution of an action. This is common for tools opening a dialog with a `Cancel` button.
      - Throwing a `TaurusToolException` will cancel the action and display the error message in an error dialog.
      - Returning a `ToolExecutionStatus` with a return code higher than the modeled `Max RC` (application option) will also cause the action to abort with an error dialog.
      - Returning a tool execution status with a return code lower than the `Max RC` and a message will display the message at the end of the action.
      - Tools can create `ResourceOperation`s by adding them to the returned `ToolExecutionStatus`.
      - Tools must add output and mass output parameters to the returned `ToolExecutionStatus` need by AWM to process the modeled `ResourceOperation`s.
      - See `TaurusModelUtilities` and `TaurusUtility` useful helper methods.

      ## Processing Input Parameters

      Tools which handle modeled input parameters should:
      - Read contents of referenced files by using `TaurusUtility.readFile(FileDescriptor, IExecutionContext)`.
      - Get modeled parameters with `ToolDescriptor.getInputParm()`.
      - Use `TaurusModelUtilities.getParameterValue(com.microfocus.awm.meta.interfaces.RToolInParameter, IExecutionContext)` to resolve a parameter value.
      - Use `TaurusModelUtilities.getFileDescriptorByInputParam(com.microfocus.awm.meta.interfaces.RToolInParameter, IExecutionContext)` to resolve file input parameters.
      - Ideally validate modeled parameters and throw descriptive `TaurusToolException`s if the tool has not been configured properly.

      ## Processing Output Parameters

      Output parameters are used to add properties and file descriptors into an execution context, so they can be passed to subsequent tools or be picked up by AWM (e.g. for element list creation).
      - Get modeled output parameters with `ToolDescriptor.getOutputParm()`.
      - Use `IExecutionContext.putParmIntoMemory(com.microfocus.awm.meta.interfaces.Property, IPropertyValue)` to add an output parameter into the memory.
      - Use `IExecutionContext.putFileParmIntoMemory(com.microfocus.awm.meta.interfaces.FileDescriptor)` to add a file output parameter into the memory.
      - Use `FileDescriptor.clone()` to create a copy of a modeled file descriptor, before e.g. setting a file descriptor path (physical name) or input stream. Otherwise the loaded model would be altered.
      - Use `IExecutionContext.addParmForOutputDialog(com.microfocus.awm.meta.interfaces.RToolOutParameter)` when `RToolOutParameter.isToOutputDialog()` has been set, to support the AWM modeled output dialog.

      ## Reading Tool Type Attributes

      If additional tool type attributes have been defined for the tool, modeled values can be retrieved by using `DynamicObject.getDynamicAttributes()` or `DynamicObject.getDynamicAttributes()`. Complex attributes can be read by `DynamicObject.getComplexAttributes()`.

      ## Creating an Element List

      To create an element list, the tool needs to have a file output parameter which points to a structured file descriptor. The list must contain records of separated property values as described in the file descriptor. If creating a physical file is not required, using a file descriptor of the type `EFileTypes.INPUT_STREAM_VALUE` is recommended. The stream can be set by using `FileDescriptor.setInputStream(java.io.InputStream)`. Please see Processing Output Parameters on how to add the output file to the memory, since this is required for AWM to find the file reference. AWM only picks up the last file output parameter of a tool to create an element list.

      ## Mass Processing

      To process more than one selected element at once (optional), number and contexts of selected elements can be retrieved using `IExecutionContext.getMassProcessingContexts()`. To find out whether the tool was modeled to process several elements at once, use `ActionExecutor.isMassProcessing(IExecutionContext, ToolDescriptor)` .

      Specified by:
        `execTool` in interface `IToolExecutor`
      Specified by:
        `execTool` in class `AbstractTaurusToolExecutor`
      Parameters:
        `pContext` - The IExecutionContext. Can be handed over by a previous Tool or created manually.
        `pTool` - The descriptor of the Tool to be executed.
        `pAffectedResName` - a logical resource name (or `null` if there is none, see `IExecutionContext.getResource(String)`)
        `pMon` - An IProgressMonitor. Setting the progress monitor cancelled using `IProgressMonitor.setCanceled(boolean)` will cause the action to be canceled after the tool.
      Returns:
        `ToolExecutionStatus`
      Throws:
        `TaurusToolException` - if the tool encounters an exception

    - #### getOutputReader

          public IToolOutputReader getOutputReader()

      Description copied from interface: `IToolExecutor`
      Returns the implementation of the IToolOutputReader which is used for reading the tool output of the implemented IToolExecutor.

      Only required for tools which are able to execute batch jobs.

      Specified by:
        `getOutputReader` in interface `IToolExecutor`
      Overrides:
        `getOutputReader` in class `AbstractTaurusToolExecutor`
      Returns:
        the output reader which has been set for the tool

    - #### readParmFile

          public java.util.List<java.lang.String> readParmFile(ISystemImage pImg,
                                                               java.lang.String pParmFilePath,
                                                               org.eclipse.core.runtime.IProgressMonitor pMon)
                                                        throws java.io.IOException

      Description copied from interface: `IToolExecutor`
      Converts the contents of a parameter file into a list of strings (lines).

      Only required for tools which are able to execute batch jobs.

      Specified by:
        `readParmFile` in interface `IToolExecutor`
      Overrides:
        `readParmFile` in class `AbstractTaurusToolExecutor`
      Parameters:
        `pImg` - the system image
        `pParmFilePath` - the parameter file path
        `pMon` - progress monitor
      Returns:
        a list of strings which represents lines of the parameter file
      Throws:
        `java.io.IOException` - if reading or interpreting the parameter file fails

Copyright © 2015 Micro Focus GmbH. All rights reserved.