com.microfocus.awm.internal.functionpackage.oscommand.tools

Class OSCommandToolExecutor

java.lang.Object

com.microfocus.awm.control.AbstractTaurusToolExecutor

com.microfocus.awm.control.OSCommandExecutor

com.microfocus.awm.internal.functionpackage.oscommand.tools.OSCommandToolExecutor

All Implemented Interfaces:

IToolExecutor

public class OSCommandToolExecutor
extends OSCommandExecutor

Class to execute OS Command tools.

Author:

NicolasP

Constructor Summary

Constructors

Constructor and Description
OSCommandToolExecutor()

Method Summary

Modifier and Type	Method and Description
ToolExecutionStatus	execTool(IExecutionContext pContext, ToolDescriptor pToolDescriptor, java.lang.String pAffectedResName, org.eclipse.core.runtime.IProgressMonitor pMon) Called by AWM as soon as the tool is executed within an action.

Methods inherited from class com.microfocus.awm.control.OSCommandExecutor

getOutputReader, readParmFile

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

OSCommandToolExecutor

public OSCommandToolExecutor()

Method Detail

execTool

public ToolExecutionStatus execTool(IExecutionContext pContext,
                                    ToolDescriptor pToolDescriptor,
                                    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 ResourceOperations 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 ResourceOperations.
• 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 TaurusToolExceptions 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

Overrides:

execTool in class OSCommandExecutor

Parameters:

pContext - The IExecutionContext. Can be handed over by a previous Tool or created manually.

pToolDescriptor - 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