us.temerity.pipeline
Class BaseTool

java.lang.Object
  us.temerity.pipeline.Named
      us.temerity.pipeline.PluginID
          us.temerity.pipeline.BasePlugin
              us.temerity.pipeline.BaseTool

All Implemented Interfaces:

Serializable, Cloneable, Comparable<PluginID>, Glueable

Direct Known Subclasses:

CheckOutSourcesTool, CleanUpTool, CommonToolUtils, DeleteAllTool, DisableActionTool, DisableActionTool, DisableCompTool, EnableCompTool, ImportExternalTool, InsertNodeTool, MayaAddReferenceTool, MayaAddReferenceTool, MayaAddRefTool, MayaRemoveReferenceTool, MayaRemoveRefTool, MayaTextureSyncTool, MayaTextureSyncTool, MayaTextureSyncTool, MayaTextureSyncTool, MayaTextureSyncTool, MRayAddTexturesTool, MultipleLinkTool, MultipleRenumberTool, NodeNoteTool, NukeAddSourceTool, NukeSourceSyncTool, PatternCloneTool, RegisterMapTool, RegisterMapTool, RegisterMapTool, RenumberTool, RenumberTool, ToggleIntermediateTool

public class BaseTool
extends BasePlugin

The superclass of all Pipeline tool plugins.

Tool plugins provide a mechanism for extending the functionality of the plui(1) graphical user interface to Pipeline. The tool is triggered by a menu item displayed in the Node Viewer panel similar to the built-in operations such as Check-In or Edit.

Tools are responsible for creating any user interface components they require to collect user input by overriding the collectPhaseInput method. The UIFactory class contains a large number of static methods for creating UI component with a Pipeline look-and-feel. The JToolDialog class should be used as the container for presenting any created components to the user.

The functionality of tool subclasses is provided by overriding the executePhase method.

These two methods are alternatively executed until the tool signifies that execution is complete or an error occurs. In this way, the user interface components provided by the tool and the operations taken can be different during each phase of execution. This allows for very flexible tools which may adapt during their execution based on additional user input.

Single phase tools which collect no user input execept for the selected nodes at the time the tool is run can be created by only overriding the executePhase method and returning true on exit from this method.

While new plugin subclass versions are being modified and tested the underDevelopment method should be called in the subclasses constructor to enable the plugin to be dynamically reloaded.

See Also:

Serialized Form

Nested Class Summary

static class	BaseTool.NextPhase The action to take after the completion of the execute portion of the current execute phase of operation of the Tool plugin.
class	BaseTool.ToolPhase Base class for one phase of operation of the Tool plugin.

Field Summary

protected String	pPrefix The name of the parent directory of the primary selected node or the branch selected in the node browser.
protected String	pPrimary The name of the primary selected node or null if there is no primary node selection.
protected TreeSet<String>	pRoots The fully resolved names of the root nodes of the currently displayed node trees.
protected TreeMap<String,NodeStatus>	pSelected The last known status of the selected nodes indexed by fully resolved node name.

Fields inherited from class us.temerity.pipeline.BasePlugin

pDescription

Fields inherited from class us.temerity.pipeline.PluginID

pVendor, pVersionID

Fields inherited from class us.temerity.pipeline.Named

pName

Constructor Summary

protected	BaseTool() This constructor is required by the GlueDecoder to instantiate the class when encountered during the reading of GLUE format files and should not be called from user code.
protected	BaseTool(String name, VersionID vid, String vendor, String desc) Construct with the given name, version, vendor and description.

Method Summary

protected void	addPhase(BaseTool.ToolPhase phase) Add an execution phase to the tool.
String	authorOnExit() The name of the user owning the current working area on exit.
String	collectPhaseInput() Create and show graphical user interface components to collect information from the user to use as input in the next phase of execution for the tool.
boolean	executePhase(MasterMgrClient mclient, QueueMgrClient qclient) Perform one phase in the execution of the tool.
String	getAuthor() Get the name of the user which owns the working area where the tool is run.
PluginType	getPluginType() Get which general type of plugin this is.
String	getView() Get the name of the user's working area view where the tool is run.
void	initExecution(String author, String view, String primary, String prefix, TreeMap<String,NodeStatus> selected, TreeSet<String> roots) Initialize the execution phases with the currently node selection.
TreeSet<String>	rootsOnExit() The fully resolved names of the root nodes to display on exit.
boolean	showLogHistory() Whether to display the Log History dialog when running this tool.
boolean	updateOnExit() Whether to perform a node status update upon successfully executing the tool.
String	viewOnExit() The name of the user's working area view on exit.

Methods inherited from class us.temerity.pipeline.BasePlugin

addSupport, compareTo, equals, getDescription, getFullMessage, getPluginID, getResource, getResources, getResourceSize, getSupports, isUnderDevelopment, removeSupport, setSupports, supports, toString, underDevelopment

Methods inherited from class us.temerity.pipeline.PluginID

fromGlue, getVendor, getVersionID, toGlue

Methods inherited from class us.temerity.pipeline.Named

clone, getName

Methods inherited from class java.lang.Object

finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

pPrimary

protected String pPrimary

The name of the primary selected node or null if there is no primary node selection.

pPrefix

protected String pPrefix

The name of the parent directory of the primary selected node or the branch selected in the node browser. This can be null if there is no primary node selection or no branch selected in the Node Browser.

pSelected

protected TreeMap<String,NodeStatus> pSelected

The last known status of the selected nodes indexed by fully resolved node name.

pRoots

protected TreeSet<String> pRoots

The fully resolved names of the root nodes of the currently displayed node trees.

You can modify the contents of this set to change which nodes are displayed once the tool exits. See the updateOnExit() and rootsOnExit() methods for details.

Constructor Detail

BaseTool

protected BaseTool()

This constructor is required by the GlueDecoder to instantiate the class when encountered during the reading of GLUE format files and should not be called from user code.

BaseTool

protected BaseTool(String name,
                   VersionID vid,
                   String vendor,
                   String desc)

Construct with the given name, version, vendor and description.

Parameters:

name - The short name of the tool.

vid - The tool plugin revision number.

vendor - The name of the plugin vendor.

desc - A short description of the tool.

Method Detail

getPluginType

public final PluginType getPluginType()

Get which general type of plugin this is.

Overrides:

getPluginType in class BasePlugin

initExecution

public final void initExecution(String author,
                                String view,
                                String primary,
                                String prefix,
                                TreeMap<String,NodeStatus> selected,
                                TreeSet<String> roots)

Initialize the execution phases with the currently node selection.

The primary selected node is the node under the mouse when the tool menu was shown (highlighted cyan). The selected nodes include the primary selected node as well as any previously selected nodes (highlighted yellow).

It is possible that the same node may be selected more than once, however the status of any particular node will only be reported once. In choosing among more then one selected copy of a node, nodes with heavyweight status details will be favored over those with lightweight details or downstream nodes with no details.

Parameters:

author - The name of the user which owns the working area where the tool is run.

view - The name of the user's working area view where the tool is run.

primary - The name of the primary selected node or null.

prefix - The name of the parent directory of the primary selected node or a branch selected in the Node Browser or null.

selected - The last known status of the selected nodes indexed by fully resolved node name.

roots - The fully resolved names of the root nodes of the currently displayed node trees.

getAuthor

public String getAuthor()

Get the name of the user which owns the working area where the tool is run.

getView

public String getView()

Get the name of the user's working area view where the tool is run.

addPhase

protected final void addPhase(BaseTool.ToolPhase phase)

Add an execution phase to the tool.

Tool plugin subclasses should call this method in their constructor to register instances of BaseTool.ToolPhase created by the tool which represent each phase of tool execution.

The default implementation of the collectPhaseInput and executePhase methods will iterate through these ToolPhase instances automatically.

collectPhaseInput

public String collectPhaseInput()
                         throws PipelineException

Create and show graphical user interface components to collect information from the user to use as input in the next phase of execution for the tool.

This method is executed by the Swing event thread. Modal dialogs can be created and shown to collect user input. The collected input should be validated and stored in fields of the tool subclass by this method before returning.

If this method return null, the execution of the tool will be immediately aborted without any notification to the user. Otherwise, the executePhase method will be run in a seperate thread to perform action based on the input collected in this method. The returned String will be used as the progress message shown in the operation status field at the bottom of the main Pipeline window.

The default implementation of this method simply iterates through the ToolPhase instances previously registered using addPhase calling the ToolPhase.collectInput method of each phase.

Note that older tool plugins created before the existance of BaseTool.ToolPhase override this method and manually handle interating through tool execution phases. This is no longer necessary or recommended. New tools should create ToolPhase internal classes and register them with addPhase instead of overriding this method.

Returns:

The phase progress message or null to abort early.

Throws:

PipelineException - If unable to validate the given user input.

executePhase

public boolean executePhase(MasterMgrClient mclient,
                            QueueMgrClient qclient)
                     throws PipelineException

Perform one phase in the execution of the tool.

This method is executed in a seperate thread from the Swing event thread. No user interface components should be created or queried by this method. All information used to control the behaviour of this method should be stored in fields of the tool previously in the collectPhaseInput method.

If this method returns true, another phase of execution will be initiated and user input will again be collected by the collectPhaseInput method. Otherwise, execution of the tool will end successfully.

The default implementation of this method simply iterates through the ToolPhase instances previously registered using addPhase calling the ToolPhase.execute method of each phase.

Note that older tool plugins created before the existance of BaseTool.ToolPhase override this method and manually handle interating through tool execution phases. This is no longer necessary or recommended. New tools should create ToolPhase internal classes and register them with addPhase instead of overriding this method.

Parameters:

mclient - The network connection to the plmaster(1) daemon.

qclient - The network connection to the plqueuemgr(1) daemon.

Returns:

Whether to continue and collect user input for the next phase of the tool.

Throws:

PipelineException - If unable to sucessfully execute this phase of the tool.

updateOnExit

public boolean updateOnExit()

Whether to perform a node status update upon successfully executing the tool.

By default this method returns true. Subclasses which wish to skip node status update should override this method to return false.

rootsOnExit

public TreeSet<String> rootsOnExit()

The fully resolved names of the root nodes to display on exit. By default this method returns pRoots. Subclasses which wish to modify the set of nodes updated when the tool exits should modify the contents of pRoots or override this method to return the specific root nodes they wish to be displayed.

Note that a status update is required for this to take effect, so updateOnExit() must also return true.

authorOnExit

public String authorOnExit()

The name of the user owning the current working area on exit. By default this method returns getAuthor(). Subclasses which wish to modify the current working area when the tool exits should override this method to return an alternative owning user.

Note that a status update is required for this to take effect, so updateOnExit() must also return true.

viewOnExit

public String viewOnExit()

The name of the user's working area view on exit. By default this method returns getView(). Subclasses which wish to modify the current working area when the tool exits should override this method to return an alternative working area view name.

Note that a status update is required for this to take effect, so updateOnExit() must also return true.

showLogHistory

public boolean showLogHistory()

Whether to display the Log History dialog when running this tool. By default this method returns false. Subclasses which wish to display verbose progress messages in the log should override this method to return true.