ExecutableAgent Class Reference

This is a helper class that makes working with Executable plug-ins easier. More...

#include <ExecutableAgent.h>

Inheritance diagram for ExecutableAgent:

List of all members.

Public Member Functions
virtual void	instantiate (Progress *pProgress, bool batch)=0
virtual void	instantiate (const std::string &plugInName, const std::string &menuCommand, Progress *pProgress, bool batch)=0
virtual void	instantiate (PlugIn *pPlugIn, const std::string &menuCommand, Progress *pProgress, bool batch)=0
virtual void	setPlugIn (const std::string &plugInName)=0
virtual void	setPlugIn (PlugIn *pPlugIn)=0
virtual void	createProgressDialog (bool bCreate)=0
virtual bool	isProgressDialogCreated () const =0
virtual void	setAutoArg (bool bAutoArg)=0
virtual bool	getAutoArg () const =0
virtual Progress *	getProgress () const =0
virtual bool	execute ()=0
virtual bool	abort ()=0
virtual bool	runAllTests (Progress *pProgress, std::ostream &output)=0
virtual PlugInArgList &	getInArgList () const =0
virtual PlugInArgList &	getOutArgList () const =0
virtual const PlugIn *	getPlugIn () const =0
virtual PlugIn *	getPlugIn ()=0
virtual PlugIn *	releasePlugIn ()=0
Protected Member Functions
virtual	~ExecutableAgent ()

---

Detailed Description

This is a helper class that makes working with Executable plug-ins easier.

This class will manage the lifecycle of the Executable plug-in. When this object is destroyed, the plug-in will be destroyed if it is set to be destroyed after execution and it is not a background plug-in. You should not create an instance of this class using ObjectFactory, but you should use ExecutableResource.

Warning:

If you do not call an overload of instantiate() before calling any other methods, a std::logic_error will be thrown. You cannot call instantiate() twice on the same instance or a std::logic_error will be thrown.

See also:

ExecutableResource, Executable

Definition at line 35 of file ExecutableAgent.h.

---

Constructor & Destructor Documentation

virtual ExecutableAgent::~ExecutableAgent

(

)

[protected, virtual]

This should be destroyed by calling ObjectFactory::destroyObject.

Definition at line 387 of file ExecutableAgent.h.

---

Member Function Documentation

virtual void ExecutableAgent::instantiate	(	Progress *	pProgress,
		bool	batch
	)			[pure virtual]

Creates an invalid object for delayed initialization of a ExecutableAgent.

Creates an invalid object where no plug-in is initially created. The Executable can then be initialized later by calling setPlugIn().

Parameters:

	pProgress	The progress object to pass into the plug-in. If NULL is passed in, a progress object is obtained by calling PlugInManagerServices::getProgress().
	batch	Set this value to true to execute the plug-in in batch mode or to false to execute the plug-in in interactive mode. Background plug-ins executed in interactive mode are automatically added to the Background Plug-In Window.

Exceptions:

std::logic_error

Thrown if the instantiate() method is called more than once on a instance.

Implemented in ExportAgent, and ImportAgent.

virtual void ExecutableAgent::instantiate	(	const std::string &	plugInName,
		const std::string &	menuCommand,
		Progress *	pProgress,
		bool	batch
	)			[pure virtual]

Creates a Executable to execute.

Parameters:

	plugInName	The name of the Executable to create and execute.
	menuCommand	The menu command name from which the plug-in is executed. The menu command name is set into an arg with "Menu Command" as its name and "string" as its type. If this arg does not exist in the arg list of the given plug-in, this parameter is ignored. If an empty string is passed in, no arg value is set.
	pProgress	The progress object to pass into the plug-in. If NULL is passed in, a progress object is obtained by calling PlugInManagerServices::getProgress().
	batch	Set this value to true to execute the plug-in in batch mode or to false to execute the plug-in in interactive mode. Background plug-ins executed in interactive mode are automatically added to the Background Plug-In Window.

Exceptions:

std::logic_error

Thrown if the instantiate() method is called more than once on a instance.

Implemented in ImportAgent.

virtual void ExecutableAgent::instantiate	(	PlugIn *	pPlugIn,
		const std::string &	menuCommand,
		Progress *	pProgress,
		bool	batch
	)			[pure virtual]

Uses an Executable to execute.

Parameters:

	pPlugIn	The plug-in to execute. The agent assumes ownership of the given plug-in and will destroy it as necessary upon destruction.
	menuCommand	The menu command name from which the plug-in is executed. The menu command name is set into an arg with "Menu Command" as its name and "string" as its type. If this arg does not exist in the arg list of the given plug-in, this parameter is ignored. If an empty string is passed in, no arg value is set.
	pProgress	The progress object to pass into the plug-in. If NULL is passed in, a progress object is obtained by calling PlugInManagerServices::getProgress().
	batch	Set this value to true to execute the plug-in in batch mode or to false to execute the plug-in in interactive mode. Background plug-ins executed in interactive mode are automatically added to the Background Plug-In Window.

Exceptions:

std::logic_error

Thrown if the instantiate() method is called more than once on a instance.

virtual void ExecutableAgent::setPlugIn

(

const std::string &

plugInName

)

[pure virtual]

Sets the plug-in to execute.

Parameters:

plugInName

The name of the plug-in to execute. If an empty string is passed in, the current plug-in is destroyed and no new plug-in is set, thereby creating an invalid object.

Exceptions:

std::logic_error

Thrown if the instantiate() method has not yet been called on this instance.

See also:

setPlugIn(PlugIn*)

virtual void ExecutableAgent::setPlugIn

(

PlugIn *

pPlugIn

)

[pure virtual]

Sets the plug-in to execute.

Parameters:

pPlugIn

The plug-in to execute. The agent assumes ownership of the given plug-in and will destroy it as necessary upon destruction. If NULL is passed in, the current plug-in is destroyed and no new plug-in is set, thereby creating an invalid object.

Exceptions:

std::logic_error

Thrown if the instantiate() method has not yet been called on this instance.

See also:

setPlugIn(const std::string&)

virtual void ExecutableAgent::createProgressDialog

(

bool

bCreate

)

[pure virtual]

Creates a progress dialog when the agent is executed.

By default, if this method is not called, a progress dialog is not created.

This method does nothing if ApplicationServices::isInteractive() returns false.

Parameters:

bCreate

Set this parameter to true to create a progress dialog when the agent is executed. A new progress dialog will then be created for each call to ExecutableAgent::execute() for this instance.

Exceptions:

std::logic_error

Thrown if ExecutableAgent::instantiate() method has not yet been called.

See also:

ExecutableAgent::instantiate()

virtual bool ExecutableAgent::isProgressDialogCreated

(

)

const [pure virtual]

Queries whether a progress dialog is created when the agent is executed.

Exceptions:

std::logic_error

Thrown if ExecutableAgent::instantiate() method has not yet been called.

Returns:

Returns true if a progress dialog is created when the agent is executed or false if the dialog is not created. This method also returns false if createProgressDialog() has not been called or if ApplicationServices::isInteractive() returns false.

virtual void ExecutableAgent::setAutoArg

(

bool

bAutoArg

)

[pure virtual]

Sets whether the input argument list will be automatically or manually populated.

If the input argument list is already populated, calling this function will not clear the list.

The Progress argument is always auto-populated with the current Progress object. This can be overridden by explicitly setting the Progress argument to NULL.

If this function is not called, the input argument list will be automatically populated.

Parameters:

bAutoArg

Set this parameter to true to automatically populate an input argument list or set it to false to populate the input argument list manually.

virtual bool ExecutableAgent::getAutoArg

(

)

const [pure virtual]

Gets whether the input argument list will be automatically or manually populated.

Returns:

Returns true if the input argument list is automatically populated or false if the input argument list is populated manually.

virtual Progress* ExecutableAgent::getProgress

(

)

const [pure virtual]

Returns the progress object used by the plug-in.

Exceptions:

std::logic_error

Thrown if the instantiate() method has not yet been called on this instance.

Returns:

The progress object used by the plug-in. This is either the progress object passed in upon instantiation of the agent or the progress object obtained by calling PlugInManagerServices::getProgress().

virtual bool ExecutableAgent::execute

(

)

[pure virtual]

Executes the underlying plug-in.

This method first creates the input and output arg lists if necessary, populates the input arg list, and then executes the plug-in. If a background plug-in was executed successfully, an item is automatically added to the Background Plug-In Window.

Arg Values:

The following input arg values are automatically populated unless the actual value in the arg has already been set and PlugInArg::isActualSet() returns true:

• Executable::WindowArg() is populated with the current workspace window as returned by DesktopServices::getCurrentWorkspaceWindow().
• Executable::ViewArg() is populated with the view contained in the current workspace window as returned by WorkspaceWindow::getView(). If this view is not a kind of View as the arg type, the arg is populated with the active view contained in the current workspace window as returned by WorkspaceWindow::getActiveView().
• Executable::LayerArg() is populated with the active layer in the view of the current workspace window as returned by SpatialDataView::getActiveLayer() or ProductView::getActiveLayer().
• Executable::DataElementArg() is populated with the first DataElement found in the following search order:
  1. The element displayed by the primary raster layer in the view of the current workspace window as returned by LayerList::getPrimaryRasterElement().
  2. The element displayed by the active layer in the view of the current workspace window as returned by Layer::getDataElement().
  3. The first child element of the primary raster layer element in the view of the current workspace window.

If more than one of the args listed above exist and the actual value is set in the input arg list, one arg value will be used to get the value for another arg where appropriate instead of getting the value according to the above descriptions.

Exceptions:

std::logic_error

Thrown if the instantiate() method has not yet been called on this instance.

Returns:

The success value returned by Executable::execute(). If the plug-in does not support the batch/interactive mode requested false will be returned and the plug-in will not be executed.

Implemented in ExportAgent, and ImportAgent.

virtual bool ExecutableAgent::abort

(

)

[pure virtual]

Aborts the underlying plug-in.

Exceptions:

std::logic_error

Thrown if the instantiate() method has not yet been called on this instance.

Returns:

The success value returned by the plug-in's abort function.

virtual bool ExecutableAgent::runAllTests	(	Progress *	pProgress,
		std::ostream &	output
	)			[pure virtual]

Runs the tests specified in the Testable interface of the plug-in.

Parameters:

	pProgress	The progress object to pass through the Testable interface.
	output	The output stream for the plug-in's test suite to use for reporting errors.

Exceptions:

std::logic_error

Thrown if the instantiate() method has not yet been called on this instance.

Returns:

The success value returned by Testable::runAllTests(). If the plug-in does not have a Testable interface, false is returned.

virtual PlugInArgList& ExecutableAgent::getInArgList

(

)

const [pure virtual]

Access the input argument list.

This will ensure that the returned arg list has been built and has default values set. It may or may not have actual values set, depending on when this function is called.

Warning:

The agent does not override actual values set into the input args. Therefore, setting actual arg values on the returned PlugInArgList for objects that are explicitly set in the agent will cause the agent's values to not be passed into the plug-in.

Exceptions:

std::logic_error

Thrown if the instantiate() method has not yet been called on this instance.

Returns:

A reference to the input argument list.

virtual PlugInArgList& ExecutableAgent::getOutArgList

(

)

const [pure virtual]

Access the output argument list.

This will ensure that the returned arg list has been built and has default values set. It may or may not have actual values set, depending on when this function is called.

Exceptions:

std::logic_error

Thrown if the instantiate() method has not yet been called on this instance.

Returns:

A reference to the input argument list.

virtual const PlugIn* ExecutableAgent::getPlugIn

(

)

const [pure virtual]

Returns the plug-in instance being executed.

Exceptions:

std::logic_error

Thrown if the instantiate() method has not yet been called on this instance.

Returns:

plug-in instance or NULL if not available.

virtual PlugIn* ExecutableAgent::getPlugIn

(

)

[pure virtual]

Returns the plug-in instance being executed.

Exceptions:

std::logic_error

Thrown if the instantiate() method has not yet been called on this instance.

Returns:

plug-in instance or NULL if not available.

virtual PlugIn* ExecutableAgent::releasePlugIn

(

)

[pure virtual]

Releases the plug-in instance being executed.

The plug-in instance will no longer be destroyed when this ExecutableAgent is destroyed.

Exceptions:

std::logic_error

Thrown if the instantiate() method has not yet been called on this instance.

Returns:

plug-in instance or NULL if not available.