com.microfocus.awm.control.toolexecution

## Class ToolUtility

- java.lang.Object
- - com.microfocus.awm.control.toolexecution.ToolUtility

-     public class ToolUtility
      extends java.lang.Object

  Contains helper methods related to executing tool descriptors.
  Author:
    Micro Focus

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ToolUtility()`

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static IPropertyData` | `createPropertyData(IObjectTable<java.lang.String> pValues, FileDescriptor pFileDescriptor)` Same as `createPropertyData(String[][], FileDescriptor)` but with the strings provided by an `IObjectTable`.
    `static IPropertyData` | `createPropertyData(java.lang.String[][] pValues, FileDescriptor pFileDescriptor)` Creates `IPropertyData` from the `IStructure` of the given `FileDescriptor` by creating one `IPropertyElement` for each line (first dimension) and one property value for each String (second dimension).
    `static <T> T` | `getAttributeValue(IToolContext pContext, IDynamicObject pDynamicObject, java.lang.String pAttributeId, java.lang.Class<T> pAttributeType)` Returns an attribute value of a given model extension object (`IDynamicObject`).
    `static IComplexAttribute` | `getComplexAttribute(IDynamicObject pDynamicObject, java.lang.String pComplexAttributeId)` Returns the first found `IComplexAttribute` for a given (`IDynamicObject`) based on the provided complex attribute ID.
    `static java.util.Collection<IComplexAttribute>` | `getComplexAttributes(IDynamicObject pDynamicObject, java.lang.String pComplexAttributeId)` Returns a collection of `IComplexAttribute`s for a given (`IDynamicObject`) based on the provided complex attribute ID.
    `static <T extends IToolInputParameter> T` | `getInputParameter(IToolContext pToolContext, java.lang.String pExtensionID, java.lang.Class<T> pType)` This method retrieves the first found `IToolInputParameter` which extension ID matches the provided extension ID.
    `static <T extends IToolInputParameter> java.util.Collection<T>` | `getInputParameters(IToolContext pToolContext, java.lang.String pExtensionID, java.lang.Class<T> pType)` This method retrieves a `Collection` of `IToolInputParameter` which extension ID matches the provided extension ID.
    `static <T extends IToolInputParameter> java.util.Collection<T>` | `getInputParametersByType(IToolContext pToolContext, java.lang.Class<T> pType)` Retrieves all `IToolInputParameter` of a specific parameter type.
    `static <T extends IModeledToolOutputParameter> T` | `getOutputParameter(IToolContext pToolContext, java.lang.String pExtensionID, java.lang.Class<T> pType)` This method retrieves the first found `IModeledToolOutputParameter` which extension ID matches the provided extension ID.
    `static <T extends IModeledToolOutputParameter> java.util.Collection<T>` | `getOutputParameters(IToolContext pToolContext, java.lang.String pExtensionID, java.lang.Class<T> pType)` This method retrieves a `Collection` of `IModeledToolOutputParameter` which extension ID matches the provided extension ID.
    `static <T extends IModeledToolOutputParameter> java.util.Collection<T>` | `getOutputParametersByType(IToolContext pToolContext, java.lang.Class<T> pType)` Retrieves all `IModeledPropertyOutputParameter` of a specific parameter type.
    `static java.lang.String` | `getParameterLabel(IToolParameter pParm)` Generates a user friendly label for a parameter.
    `static java.util.Collection<Property>` | `getPropertiesFromStructure(IStructure pStructure)` Returns a collection of all `Property`s which are referenced in an `IStructure` by parsing all subcomponents (`IStructure.getComponents()` / `IStructureComponent.getChildren()`).

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

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

- - ### Constructor Detail

    - #### ToolUtility

          public ToolUtility()

  - ### Method Detail

    - #### createPropertyData

          public static IPropertyData createPropertyData(java.lang.String[][] pValues,
                                                         FileDescriptor pFileDescriptor)
                                                  throws TaurusToolException

      Creates `IPropertyData` from the `IStructure` of the given `FileDescriptor` by creating one `IPropertyElement` for each line (first dimension) and one property value for each String (second dimension).

      The properties are obtained from the structure components in the same order.

      Currently only IStructures of type `EFileStructures.TABLE` are supported. Structure components which do not reference a property will be ignored.
      The provided table lines don't need to have the same length, as long as the indexes of the values are consistent. This effectively means that trailing values are optional and will not be added as property values to the resulting `IPropertyElement`s (see example below).

      Example:
      A matrix of two lines and three rows is given. Note that the second line is missing the last value.
      `Ele1, jpg, Stephen`
      `Ele2, txt`

      And a table structure with three components, each referencing a property:
      `PROP_ElementName
      PROP_Type
      PROP_Username`

      This will result in an `IPropertyData` with two `IPropertyElement`s. The second property element does not have a property value for PROP_Username, since no value was provided in the matrix.
      `PropertyElement [PROP_ElementName="Ele1", PROP_Type="jpg", PROP_Username="Stephen"]`
      `PropertyElement [PROP_ElementName="Ele2", PROP_Type="txt"]`

      Parameters:
        `pValues` - the values to convert
        `pFileDescriptor` - the structured file descriptor to obtain properties from
      Returns:
        the created IPropertyData
      Throws:
        `TaurusToolException` - if the structure is not compatible for generating `IPropertyData` or contains less properties than Strings in a given line

    - #### createPropertyData

          public static IPropertyData createPropertyData(IObjectTable<java.lang.String> pValues,
                                                         FileDescriptor pFileDescriptor)
                                                  throws TaurusToolException

      Same as `createPropertyData(String[][], FileDescriptor)` but with the strings provided by an `IObjectTable`.
      Parameters:
        `pValues` - the values to convert
        `pFileDescriptor` - the structured file descriptor to obtain properties from
      Returns:
        the created IPropertyData
      Throws:
        `TaurusToolException` - if the structure is not compatible for generating `IPropertyData` or contains less properties than Strings in a given line

    - #### getParameterLabel

          public static java.lang.String getParameterLabel(IToolParameter pParm)

      Generates a user friendly label for a parameter. Depending on whether a label attribute is available or not, the method will return one of the following Strings:

      | `Returned Value (Syntax)` | `Example`
      Modeled label set | `#[seqNo] "[modeled label]"` | `#3 "File Path"`
      Label set in extension | `#[seqNo] "[extension label]"` | `#3 "File Path"`
      No label available | `#[seqNo]` | `#3`

      Parameters:
        `pParm` - the parameter to create a label from
      Returns:
        the created label

    - #### getInputParameters

          public static <T extends IToolInputParameter> java.util.Collection<T> getInputParameters(IToolContext pToolContext,
                                                                                                   java.lang.String pExtensionID,
                                                                                                   java.lang.Class<T> pType)
                                                                                            throws TaurusToolException

      This method retrieves a `Collection` of `IToolInputParameter` which extension ID matches the provided extension ID.

      By using the type parameter the output type of this method can be defined. If the type is e.g. set to `IStringInputParameter`, a `Collection` of `IStringInputParameter`s is returned. An exception is thrown, if an input parameter is found with a matching ID but a mismatching parameter type.

      This method checks if the parameters are defined as optional or required and throws an exception if a parameter could not be retrieved for a required and enabled parameter.

      Parameters:
        `pToolContext` - the tool context
        `pExtensionID` - the extension ID of the desired parameter.
        `pType` - `IStringInputParameter`, `IFileInputParameter` or, if both are supported by the tool, `IToolInputParameter`
      Returns:
        a collection of the desired modeled input parameters or an empty collection, if they are optional and no matches were found
      Throws:
        `TaurusToolException` - if the desired parameter is mandatory and visible (not disabled by a visible when condition) but none can be found or their modeled types are mismatching

    - #### getOutputParameters

          public static <T extends IModeledToolOutputParameter> java.util.Collection<T> getOutputParameters(IToolContext pToolContext,
                                                                                                            java.lang.String pExtensionID,
                                                                                                            java.lang.Class<T> pType)
                                                                                                     throws TaurusToolException

      This method retrieves a `Collection` of `IModeledToolOutputParameter` which extension ID matches the provided extension ID.

      By using the type parameter the output type of this method can be defined. If the type is e.g. set to `IModeledToolOutputParameter`, a `Collection` of `IModeledToolOutputParameter`s is returned. An exception is thrown, if an output parameter is found with a matching ID but a mismatching parameter type.

      This method checks if the parameters are defined as optional or required and throws an exception if a parameter could not be retrieved for a required and enabled parameter.

      Parameters:
        `pToolContext` - the tool context
        `pExtensionID` - the extension ID of the desired parameter.
        `pType` - `IModeledPropertyOutputParameter`, `IModeledFileOutputParameter` or, if both are supported by the tool, `IModeledToolOutputParameter`
      Returns:
        a collection of the desired modeled output parameters or an empty collection, if they are optional and no matches were found
      Throws:
        `TaurusToolException` - if the desired parameter is mandatory and visible (not disabled by a visible when condition) but none can be found or their modeled types are mismatching

    - #### getInputParametersByType

          public static <T extends IToolInputParameter> java.util.Collection<T> getInputParametersByType(IToolContext pToolContext,
                                                                                                         java.lang.Class<T> pType)

      Retrieves all `IToolInputParameter` of a specific parameter type.

      If for example the type `IStringInputParameter` is used, all `IStringInputParameter`s modeled in the tool descriptor are going to be returned.

      Parameters:
        `pToolContext` - the tool context
        `pType` - `IStringInputParameter`, `IFileInputParameter` or, if both are supported by the tool, `IToolInputParameter`
      Returns:
        a `Collection` of `IToolInputParameter` which are matching the provided parameter type.

    - #### getOutputParametersByType

          public static <T extends IModeledToolOutputParameter> java.util.Collection<T> getOutputParametersByType(IToolContext pToolContext,
                                                                                                                  java.lang.Class<T> pType)

      Retrieves all `IModeledPropertyOutputParameter` of a specific parameter type.

      If for example the type `IModeledPropertyOutputParameter` is used, all `IModeledPropertyOutputParameter`s modeled in the tool descriptor are going to be returned.

      Parameters:
        `pToolContext` - the tool context
        `pType` - `IModeledPropertyOutputParameter`, `IModeledFileOutputParameter` or, if both are supported by the tool, `IModeledToolOutputParameter`
      Returns:
        a `Collection` of `IModeledPropertyOutputParameter` which are matching the provided parameter type.

    - #### getInputParameter

          public static <T extends IToolInputParameter> T getInputParameter(IToolContext pToolContext,
                                                                            java.lang.String pExtensionID,
                                                                            java.lang.Class<T> pType)
                                                                     throws TaurusToolException

      This method retrieves the first found `IToolInputParameter` which extension ID matches the provided extension ID.

      This method calls `getInputParameters(IToolContext, String, Class)` and returns the first `IToolInputParameter` for the returned collection.

      Parameters:
        `pToolContext` - the tool context
        `pExtensionID` - the extension ID of the desired parameter.
        `pType` - `IStringInputParameter`, `IFileInputParameter` or, if both are supported by the tool, `IToolInputParameter`
      Returns:
        the first found `IToolInputParameter` of the desired modeled input parameter or `null`, if the desired is optional parameter and no matches were found
      Throws:
        `TaurusToolException` - if the desired parameter is mandatory and visible (not disabled by a visible when condition) but none can be found or their modeled types are mismatching

    - #### getOutputParameter

          public static <T extends IModeledToolOutputParameter> T getOutputParameter(IToolContext pToolContext,
                                                                                     java.lang.String pExtensionID,
                                                                                     java.lang.Class<T> pType)
                                                                              throws TaurusToolException

      This method retrieves the first found `IModeledToolOutputParameter` which extension ID matches the provided extension ID.

      This method calls `getOutputParameters(IToolContext, String, Class)` and returns the first `IModeledToolOutputParameter` for the returned collection.

      Parameters:
        `pToolContext` - the tool context
        `pExtensionID` - the extension ID of the desired parameter.
        `pType` - `IModeledPropertyOutputParameter`, `IModeledFileOutputParameter` or, if both are supported by the tool, `IModeledToolOutputParameter`
      Returns:
        the first found `IModeledToolOutputParameter` of the desired modeled output parameter or `null`, if the desired parameter is optional and no matches were found
      Throws:
        `TaurusToolException` - if the desired parameter is mandatory and visible (not disabled by a visible when condition) but none can be found or their modeled types are mismatching

    - #### getPropertiesFromStructure

          public static java.util.Collection<Property> getPropertiesFromStructure(IStructure pStructure)

      Returns a collection of all `Property`s which are referenced in an `IStructure` by parsing all subcomponents (`IStructure.getComponents()` / `IStructureComponent.getChildren()`).
      Parameters:
        `pStructure` - the `IStructure` which should be parsed for the `Property`s
      Returns:
        a `Collection` containing all `Property`s referenced in the subcomponents of the `IStructure`.
      See Also:
        `TaurusMetaModelUtilities.getPropertiesFromStructure(IStructure)`

    - #### getAttributeValue

          public static <T> T getAttributeValue(IToolContext pContext,
                                                IDynamicObject pDynamicObject,
                                                java.lang.String pAttributeId,
                                                java.lang.Class<T> pAttributeType)
                                         throws TaurusToolException

      Returns an attribute value of a given model extension object (`IDynamicObject`).

      If the attribute is of the type `String`, property references within the `String` will be resolved based on the given `IToolContext`.

      Parameters:
        `pContext` - the `IToolContext` which will be used to resolve property references within the attribute value. Can be `null`, if the resolving of property references of attribute value is not required.
        `pDynamicObject` - the model extension object which contains the attribute
        `pAttributeId` - the ID of the attribute
        `pAttributeType` - the type of the attribute. Typically this should be either (`Object.getClass()`, `Object.getClass()`, `Object.getClass()` or `Object.getClass()`.
      Returns:
        the resolved value of the attribute. Returns `null`, if the value of the attribute could not be retrieved.
      Throws:
        `TaurusToolException` - if the type of the attribute is not equal the provided attribute type (Class)

    - #### getComplexAttribute

          public static IComplexAttribute getComplexAttribute(IDynamicObject pDynamicObject,
                                                              java.lang.String pComplexAttributeId)
                                                       throws TaurusToolException

      Returns the first found `IComplexAttribute` for a given (`IDynamicObject`) based on the provided complex attribute ID.

      This method calls `getComplexAttributes(IDynamicObject, String)` and just returns the first object from the collection.

      Parameters:
        `pDynamicObject` - the parent `IDynamicObject` of the searched `IComplexAttribute`s.
        `pComplexAttributeId` - the ID of the `IComplexAttribute`.
      Returns:
        the first `IComplexAttribute` which ID is matching the provided complex attribute ID.

        Returns `null`, if no `IComplexAttribute`s could be retrieved for optional complex attributes.

      Throws:
        `TaurusToolException` - if a required `IComplexAttribute` could not be retrieved or if no extension could be found at all for the given complex attribute ID.

    - #### getComplexAttributes

          public static java.util.Collection<IComplexAttribute> getComplexAttributes(IDynamicObject pDynamicObject,
                                                                                     java.lang.String pComplexAttributeId)
                                                                              throws TaurusToolException

      Returns a collection of `IComplexAttribute`s for a given (`IDynamicObject`) based on the provided complex attribute ID.

      This method calls `IDynamicObject.getComplexAttributes()` and filters the collection based on the given complex attribute ID.

      Parameters:
        `pDynamicObject` - the parent `IDynamicObject` of the searched `IComplexAttribute`s.
        `pComplexAttributeId` - the ID of the `IComplexAttribute`.
      Returns:
        a collection of `IComplexAttribute`s which IDs are matching the provided complex attribute ID.

        Returns an empty collection, if no `IComplexAttribute`s could be retrieved for optional complex attributes.

      Throws:
        `TaurusToolException` - if required `IComplexAttribute`s could not be retrieved or if no extension could be found at all for the given complex attribute ID.

Copyright © 2015 Micro Focus GmbH. All rights reserved.