com.microfocus.awm.model

## Interface IExecutionContext

- All Known Implementing Classes:
    ExecutionContext

      public interface IExecutionContext

  Main data store for executing AWM actions.

  Execution contexts are mostly created by AWM when:

  - One or more IResources are selected (e.g. to show properties in the Properties View).
  - An element context menu is shown to check modeled enabled conditions and disable/hide actions.
  - An AWM action is executed.
  While an AWM action is being executed, the execution context is shared between all executed tools. Tools usually update the context's `memory map`, which contains returned output parameters. These parameters can then be used by subsequent tools.

  An execution context instance is only used once for most executed actions. The only exceptions are edit scenarios with related save- and close actions. If an editor is opened by an AWM tool, the execution context is mapped to the editor using a TaurusEditorPart. Executed save- and close- actions will be able to reuse the context from the action that opened he editor.

  `Mass processing` actions create a single main execution context and one sub-context for each selected element. The sub-contexts can be acquired by `getMassProcessingContexts()`.

  It's possible to instantiate a new execution context using `TaurusFactory.createExecutionContext(ISystemImage)`. It's recommended to initialize the context using `initContext(IResource)` or `initContext(List)`.

  Not intended to be implemented by clients.

  Author:
    Micro Focus
  See Also:
    `ActionExecutor`, `IToolExecutor`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addParmForOutputDialog(RToolOutParameter pOutParm)` Parameters added to the ExecutionContext by this Method will be shown in an output dialog at the end of an Action.
    `void` | `addResource(IResource pRes, java.lang.String pName)` Adds an `IResource` with the given name.
    `void` | `addResourceToMemory(IResource pResource)` Deprecated. use `getMassProcessingContexts()` instead to add sub contexts.
    `void` | `addToolExecStatus(ToolExecutionStatus pToolStatus)` Adds a tool execution status to the list of statuses.
    `IExecutionContext` | `duplicate()` Duplicates this execution context, including the following information: Context parameters Memory (previous tool) parameters Context Resource TAURUS System
    `java.util.Map<Property,IPropertyValue>` | `getActionContextMap()` Receives a map with all Properties which have been created based on a resource and/or manually added Properties.
    `ActionDescriptor` | `getActionDescriptor()` Gets the `ActionDescriptor` of the context.
    `java.util.List<IResource>` | `getContextResources()` Returns a list of context resources.
    `FileDescriptor` | `getFileFromContext(FileDescriptor pFileDescr)` Retrieves a FileDescriptor from the context map.
    `FileDescriptor` | `getFileFromMemory(java.lang.String fileDescrID)` Retrieves a FileDescriptor from the context memory Map.
    `java.util.Map<java.lang.String,FileDescriptor>` | `getFileMemory()` Gets the file memory which contains file descriptors with resolved physical names which were returned by previous tools of an action.
    `java.util.ArrayList<IExecutionContext>` | `getMassProcessingContexts()` Returns a list of execution contexts for every resource that is being processed by a mass processing action.
    `java.util.List<IResource>` | `getMemoryResources()` Deprecated. Use `getMassProcessingContexts()` instead
    `java.util.Map<Property,IPropertyValue>` | `getParameterMemoryMap()` Receives a map with all Properties which have been saved in the context.
    `IPropertyValue` | `getParmFromContext(Property pKey)` Receives a Property from the ExecutionContext.
    `IPropertyValue` | `getParmFromMemory(Property pKey)` Retrieves a parameter Property from a map where previous tools might have stored their output parameter Properties.
    `java.util.List<RToolOutParameter>` | `getParmsForOutputDialog()` Returns a List of `RToolOutParameter`s, which have the attribute `To_OutputDialog` set to `true`.
    `IResource` | `getResource()` Receives the resource which is assigned to this context.
    `IResource` | `getResource(java.lang.String pName)` Returns the `IResource` with the given name, which has been added to the context by a resource operation (tool defined resource processing).
    `IExecutionContext` | `getResourceContext(java.lang.String pResourceName)` Returns the `IExecutionContext` of a resource with a logical name.
    `ISystemImage` | `getSystemImage()` Gets the `ISystemImage` the context is connected with.
    `java.util.List<ToolExecutionStatus>` | `getToolExecStatusList()` Gets a list of tool execution statuses.
    `IExecutionContext` | `initContext(IResource pRes)` Initializes the IExecutionContext from the given resource.
    `IExecutionContext` | `initContext(java.util.List<IResource> pResources)` Initializes the IExecutionContext from the list of resources.
    `void` | `populateContext(IResource pRes)` Deprecated. use `getActionContextMap()` and `IResource.getAllPropertyValues()` to add the properties directly to the context or `initContext(IResource)` to add a the whole resource context (including parent properties) to this execution context.
    `void` | `putFileParmIntoMemory(FileDescriptor pFileDescriptor)` Puts a File Descriptor in the execution memory.
    `void` | `putParmIntoContext(Property pProp, IPropertyValue pPropValue)` Manually puts a Property into the context Map.
    `void` | `putParmIntoMemory(Property pProp, IPropertyValue pPropValue)` Puts a parameter Property into a map, providing them to following tools during the execution.
    `void` | `setActionContext(java.util.Map<Property,IPropertyValue> pActionContext)` Set the action context of the execution context.
    `void` | `setContextResources(java.util.List<IResource> pContextResources)` Sets the context resources for mass processing.
    `void` | `setFileMemory(java.util.Map<java.lang.String,FileDescriptor> pFileMemory)` Completely sets the file memory of this context.
    `void` | `setParmMemory(java.util.Map<Property,IPropertyValue> pParmMemory)` Set the parameter memory of the execution context.
    `void` | `setResource(IResource pResource)` Sets the resource of this context.

- - ### Method Detail

    - #### addParmForOutputDialog

          void addParmForOutputDialog(RToolOutParameter pOutParm)

      Parameters added to the ExecutionContext by this Method will be shown in an output dialog at the end of an Action.
      Parameters:
        `pOutParm` - The `RToolOutParameter` or `RToolFileOutput` to be shown in an output dialog.

    - #### getActionContextMap

          java.util.Map<Property,IPropertyValue> getActionContextMap()

      Receives a map with all Properties which have been created based on a resource and/or manually added Properties.

      Returns:
        a map which contains every Property stored in the ExecutionContext except output parameters from previous tools

    - #### getFileFromMemory

          FileDescriptor getFileFromMemory(java.lang.String fileDescrID)
                                    throws TaurusToolException

      Retrieves a FileDescriptor from the context memory Map. FileDescriptors within this Map were set by previous tools during the execution of an Action.

      Usually this will be used when the `NamePhysical` or the `Type` attributes of a FileDescriptor were changed by a previous tool.

      Parameters:
        `fileDescrID` - The ID of the desired FileDescriptor
      Returns:
        The desired FileDescriptor
      Throws:
        `TaurusToolException` - if the FileDescriptor does not exist within the parameter memory.

    - #### getFileFromContext

          FileDescriptor getFileFromContext(FileDescriptor pFileDescr)
                                     throws TaurusToolException

      Retrieves a FileDescriptor from the context map. FileDescriptors within this map were set at the beginning of the Action.

      Parameters:
        `pFileDescr` - The ID of the desired FileDescriptor
      Returns:
        The desired FileDescriptor
      Throws:
        `TaurusToolException` - if the FileDescriptor does not exist within the context.

    - #### getParameterMemoryMap

          java.util.Map<Property,IPropertyValue> getParameterMemoryMap()

      Receives a map with all Properties which have been saved in the context. In TAURUS every outgoing parameter will be saved in the context, meaning that the ParameterMemoryMap grows during the execution of several tools in a row.
      Returns:
        a map which contains every output parameter which was stored there by previous tools

    - #### getParmFromContext

          IPropertyValue getParmFromContext(Property pKey)
                                     throws TaurusToolException

      Receives a Property from the ExecutionContext. Usually the context was initialized by the `initContext(IResource)` method.

      Properties could have also been added by the `putParmIntoContext(Property, IPropertyValue)` method.

      Parameters:
        `pKey` - The desired Property
      Returns:
        the corresponding IPropertyValue
      Throws:
        `TaurusToolException` - if no value for the property was found in the context.

    - #### getParmFromMemory

          IPropertyValue getParmFromMemory(Property pKey)
                                    throws TaurusToolException

      Retrieves a parameter Property from a map where previous tools might have stored their output parameter Properties. This map does not contain Properties from the context of the execution.
      Parameters:
        `pKey` - The Property which should be retrieved
      Returns:
        The corresponding IPropertyValue
      Throws:
        `TaurusToolException` - if no value for the property was found in the memory.

    - #### getParmsForOutputDialog

          java.util.List<RToolOutParameter> getParmsForOutputDialog()

      Returns a List of `RToolOutParameter`s, which have the attribute `To_OutputDialog` set to `true`.
      Returns:
        the List of RToolOutParameters which shall be shown in an output dialog

    - #### getResource

          IResource getResource()

      Receives the resource which is assigned to this context.
      Returns:
        the resource which is assigned to this context.

    - #### initContext

          IExecutionContext initContext(IResource pRes)

      Initializes the IExecutionContext from the given resource. This stores every containing Property with its value in the ExecutionContext.
      Parameters:
        `pRes` - The resource which shall be used to initialize the ExecutionContext
      Returns:
        The IExecutionContext containing the resource its Properties

    - #### initContext

          IExecutionContext initContext(java.util.List<IResource> pResources)

      Initializes the IExecutionContext from the list of resources. This creates a sub context for every given resource which can then be obtained by `getMassProcessingContexts()`. Internally calls `initContext(IResource)` for every given resource. The first resource of the given list will be the context's main resource.
      Parameters:
        `pResources` - A list of IResources.
      Returns:
        The IExecutionContext containing the resource its Properties

    - #### putParmIntoContext

          void putParmIntoContext(Property pProp,
                                  IPropertyValue pPropValue)

      Manually puts a Property into the context Map. In most cases, the `initContext(IResource)` method should provide all necessary Properties from the given resource.
      Parameters:
        `pProp` - The Property which shall be stored in the context
        `pPropValue` - The corresponding IPropertyValue

    - #### putParmIntoMemory

          void putParmIntoMemory(Property pProp,
                                 IPropertyValue pPropValue)

      Puts a parameter Property into a map, providing them to following tools during the execution.
      Parameters:
        `pProp` - The Property which an output parameter was pointing to
        `pPropValue` - The corresponding IPropertyValue

    - #### setResource

          void setResource(IResource pResource)

      Sets the resource of this context.
      Parameters:
        `pResource` - The IResource which shall be assigned to the context

    - #### setActionContext

          void setActionContext(java.util.Map<Property,IPropertyValue> pActionContext)

      Set the action context of the execution context.
      Parameters:
        `pActionContext` - action context to be set in the execution context

    - #### setParmMemory

          void setParmMemory(java.util.Map<Property,IPropertyValue> pParmMemory)

      Set the parameter memory of the execution context.
      Parameters:
        `pParmMemory` - parameter memory to be set in the execution context

    - #### getResource

          IResource getResource(java.lang.String pName)

      Returns the `IResource` with the given name, which has been added to the context by a resource operation (tool defined resource processing).
      Parameters:
        `pName` - The logical name of the desired resource
      Returns:
        the IResource with the given name.
      See Also:
        `ToolDescriptor.getResourceProcessing()`

    - #### addResource

          void addResource(IResource pRes,
                           java.lang.String pName)

      Adds an `IResource` with the given name. This should be done if a tool defined resource operation was executed.
      Parameters:
        `pRes` - The resource to be added
        `pName` - The logical name of the resource

    - #### populateContext

          @Deprecated
          void populateContext(IResource pRes)

      Deprecated. use `getActionContextMap()` and `IResource.getAllPropertyValues()` to add the properties directly to the context or `initContext(IResource)` to add a the whole resource context (including parent properties) to this execution context.
      Populates the context with the property values of the given resource.
      Parameters:
        `pRes` - the `IResource` which should be use to populate the context.

    - #### getActionDescriptor

          ActionDescriptor getActionDescriptor()

      Gets the `ActionDescriptor` of the context. Note that a context can be created without an action descriptor so this method can return `null`.
      Returns:
        an action descriptor or `null`.

    - #### getToolExecStatusList

          java.util.List<ToolExecutionStatus> getToolExecStatusList()

      Gets a list of tool execution statuses. Tool execution statuses can be created and added to the list by executed tools. The list can be empty but never `null`.
      Returns:
        a list of tool execution statuses.

    - #### addToolExecStatus

          void addToolExecStatus(ToolExecutionStatus pToolStatus)

      Adds a tool execution status to the list of statuses.
      Parameters:
        `pToolStatus` - the new tool execution status to be added.

    - #### getSystemImage

          ISystemImage getSystemImage()

      Gets the `ISystemImage` the context is connected with. Note that the context does not need to use the system image, but it is recommended to always add an image for other callers to be used.
      Returns:
        an `ISystemImage`. Can be `null`.

    - #### getFileMemory

          java.util.Map<java.lang.String,FileDescriptor> getFileMemory()

      Gets the file memory which contains file descriptors with resolved physical names which were returned by previous tools of an action.
      Returns:
        the file memory of this context.

    - #### setFileMemory

          void setFileMemory(java.util.Map<java.lang.String,FileDescriptor> pFileMemory)

      Completely sets the file memory of this context. Replaces the existing one (if there is one).
      Parameters:
        `pFileMemory` - the new file memory map.
      See Also:
        `getFileMemory()`, `getFileFromMemory(String)`

    - #### putFileParmIntoMemory

          void putFileParmIntoMemory(FileDescriptor pFileDescriptor)

      Puts a File Descriptor in the execution memory.
      Parameters:
        `pFileDescriptor` - The FileDescriptor which shall be stored in the parameter memory

    - #### duplicate

          IExecutionContext duplicate()

      Duplicates this execution context, including the following information:
    - Context parameters
    - Memory (previous tool) parameters
    - Context Resource
    - TAURUS System

Returns:
  a duplication of the execution context.

- #### getResourceContext

      IExecutionContext getResourceContext(java.lang.String pResourceName)

  Returns the `IExecutionContext` of a resource with a logical name. The logical name comes from TOOL-DEFINED resource operations.
  Parameters:
    `pResourceName` - the logical name of a resource
  Returns:
    the `IExecutionContext` of the resource or `null` if no resource with that name was found

- #### setContextResources

      void setContextResources(java.util.List<IResource> pContextResources)

  Sets the context resources for mass processing.
  Parameters:
    `pContextResources` - a list of resources, typically all elements which are selected for a multi selection action. Must not be `null`.
  See Also:
    `ActionDescriptor.isMassProcessing()`

- #### getContextResources

      java.util.List<IResource> getContextResources()

  Returns a list of context resources. If the context was created by a standard AWM action, it always contains all selected resources (e.g. Elements). Does not return `null` unless `setContextResources(List)` was called with `null` as parameter.
  Returns:
    the list of context resources.

- #### getMemoryResources

      @Deprecated
      java.util.List<IResource> getMemoryResources()

  Deprecated. Use `getMassProcessingContexts()` instead
  Gets resources that have been added to the context by tools. E.g. this is done by a table input dialog with multiple selection enabled.
  Returns:
    a list of resources added to the context by tools.
  See Also:
    `addResourceToMemory(IResource)`

- #### addResourceToMemory

      @Deprecated
      void addResourceToMemory(IResource pResource)

  Deprecated. use `getMassProcessingContexts()` instead to add sub contexts.
  Adds a resource to the context memory. Intended to be used by tools within an action.
  Parameters:
    `pResource` - the resource to be added in the memory
  See Also:
    `getMemoryResources()`

- #### getMassProcessingContexts

      java.util.ArrayList<IExecutionContext> getMassProcessingContexts()

  Returns a list of execution contexts for every resource that is being processed by a mass processing action. Mass output parameter records are written into individual execution contexts in this list. Calling `getMassProcessingContexts()` on any of the contained contexts will always return an empty list.
  Returns:
    a list of mass processing sub contexts. Can be empty.

Copyright © 2015 Micro Focus GmbH. All rights reserved.