ExportAgent Class Reference

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

#include <ExportAgent.h>

Inheritance diagram for ExportAgent:

List of all members.

Public Member Functions
virtual void	instantiate (Progress *pProgress, bool batch)=0
virtual void	instantiate (std::string exporterName, Progress *pProgress, bool batch)=0
virtual void	instantiate (PlugIn *pPlugIn, Progress *pProgress, bool batch)=0
virtual void	instantiate (std::string exporterName, SessionItem *pItem, FileDescriptor *pFileDescriptor, Progress *pProgress, bool batch)=0
virtual void	instantiate (PlugIn *pPlugIn, SessionItem *pItem, FileDescriptor *pFileDescriptor, Progress *pProgress, bool batch)=0
virtual Exporter *	getExporter ()=0
virtual const Exporter *	getExporter () const =0
virtual QWidget *	getExportOptionsWidget ()=0
virtual void	setItem (SessionItem *pItem)=0
virtual SessionItem *	getItem () const =0
virtual void	setFileDescriptor (FileDescriptor *pFileDescriptor)=0
virtual FileDescriptor *	getFileDescriptor ()=0
virtual const FileDescriptor *	getFileDescriptor () const =0
virtual std::string	getDefaultExtensions () const =0
virtual ValidationResultType	validate (std::string &errorMessage)=0
virtual bool	execute ()=0
Protected Member Functions
virtual	~ExportAgent ()

---

Detailed Description

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

This class will manage the lifecycle of the Exporter plug-in. This class can be used to export a SessionItem.

You should not create an instance of this class using ObjectFactory, but you should use ExporterResource.

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:

ExporterResource, Exporter

Definition at line 40 of file ExportAgent.h.

---

Constructor & Destructor Documentation

virtual ExportAgent::~ExportAgent

(

)

[protected, virtual]

This should be destroyed by calling ObjectFactory::destroyObject.

Definition at line 329 of file ExportAgent.h.

---

Member Function Documentation

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

Creates an invalid object for delayed initialization of an ExportAgent.

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

Parameters:

	pProgress	The progress object to pass into the exporter. If NULL is passed in, a progress object is obtained by calling PlugInManagerServices::getProgress().
	batch	Set this value to true to execute the exporter in batch mode or to false to execute the exporter in interactive mode.

Exceptions:

std::logic_error

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

Implements ExecutableAgent.

virtual void ExportAgent::instantiate	(	std::string	exporterName,
		Progress *	pProgress,
		bool	batch
	)			[pure virtual]

Creates an exporter to export data.

Creates the exporter but does not specify the data to export. This method can be used if the exporter does not need a specific data value, or one will be provided later through setItem().

Parameters:

	exporterName	The name of the exporter to create and execute.
	pProgress	The progress object to pass into the exporter. If NULL is passed in, a progress object is obtained by calling PlugInManagerServices::getProgress().
	batch	Set this value to true to execute the exporter in batch mode or to false to execute the exporter in interactive mode.

Exceptions:

std::logic_error

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

virtual void ExportAgent::instantiate	(	PlugIn *	pPlugIn,
		Progress *	pProgress,
		bool	batch
	)			[pure virtual]

Uses an existing exporter to export data.

Parameters:

	pPlugIn	The exporter to execute. The agent assumes ownership of the exporter and will destroy it as necessary upon agent destruction.
	pProgress	The progress object to pass into the exporter. If NULL is passed in, a progress object is obtained by calling PlugInManagerServices::getProgress().
	batch	Set this value to true to execute the exporter in batch mode or to false to execute the exporter in interactive mode.

Exceptions:

std::logic_error

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

virtual void ExportAgent::instantiate	(	std::string	exporterName,
		SessionItem *	pItem,
		FileDescriptor *	pFileDescriptor,
		Progress *	pProgress,
		bool	batch
	)			[pure virtual]

Creates an exporter to export a view.

Parameters:

	exporterName	The name of the exporter to create and execute.
	pItem	The item to pass into the exporter.
	pFileDescriptor	The file descriptor describing how the exporter should save the data to disk.
	pProgress	The progress object to pass into the exporter. If NULL is passed in, a progress object is obtained by calling PlugInManagerServices::getProgress().
	batch	Set this value to true to execute the exporter in batch mode or to false to execute the exporter in interactive mode.

Exceptions:

std::logic_error

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

virtual void ExportAgent::instantiate	(	PlugIn *	pPlugIn,
		SessionItem *	pItem,
		FileDescriptor *	pFileDescriptor,
		Progress *	pProgress,
		bool	batch
	)			[pure virtual]

Uses an existing exporter to export a session item.

Parameters:

	pPlugIn	The exporter to execute. The agent assumes ownership of the exporter and will destroy it as necessary upon agent destruction.
	pItem	The item to pass into the exporter.
	pFileDescriptor	The file descriptor describing how the exporter should save the data to disk.
	pProgress	The progress object to pass into the exporter. If NULL is passed in, a progress object is obtained by calling PlugInManagerServices::getProgress().
	batch	Set this value to true to execute the exporter in batch mode or to false to execute the exporter in interactive mode.

Exceptions:

std::logic_error

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

virtual Exporter* ExportAgent::getExporter

(

)

[pure virtual]

Gets a pointer to the underlying exporter plug-in.

This differs from getPlugIn() in that it performs a dynamic_cast to type Exporter. This is a convenience function and is equivalent to dynamic_cast<Exporter*>(getPlugIn())

Exceptions:

std::logic_error

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

Returns:

A pointer to the underlying exporter plug-in.

virtual const Exporter* ExportAgent::getExporter

(

)

const [pure virtual]

Gets a pointer to the underlying exporter plug-in.

This differs from getPlugIn() in that it performs a dynamic_cast to type Exporter. This is a convenience function and is equivalent to dynamic_cast<Exporter*>(getPlugIn())

Exceptions:

std::logic_error

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

Returns:

A pointer to the underlying exporter plug-in.

virtual QWidget* ExportAgent::getExportOptionsWidget

(

)

[pure virtual]

Gets the exporter plug-in's custom options page.

This gets a custom option widget using the existing agent's plug-in arguments.

Exceptions:

std::logic_error

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

Returns:

A custom option widget or NULL if the exporter does not have a custom option widget.

virtual void ExportAgent::setItem

(

SessionItem *

pItem

)

[pure virtual]

Sets the session item to pass into the exporter.

Parameters:

pItem

The session item to pass into the exporter.

Exceptions:

std::logic_error

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

virtual SessionItem* ExportAgent::getItem

(

)

const [pure virtual]

Returns the session item that will be passed into the exporter when it is executed.

Exceptions:

std::logic_error

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

Returns:

The session item that is passed into the exporter. This is either the session item passed in upon instantiation of the agent or the session item obtained by calling setItem().

virtual void ExportAgent::setFileDescriptor

(

FileDescriptor *

pFileDescriptor

)

[pure virtual]

Sets the file descriptor that the exporter uses to save the file.

Parameters:

pFileDescriptor

The file descriptor to pass into the exporter.

Exceptions:

std::logic_error

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

virtual FileDescriptor* ExportAgent::getFileDescriptor

(

)

[pure virtual]

Returns the file descriptor that will be passed into the exporter when it is executed.

Exceptions:

std::logic_error

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

Returns:

The file descriptor that is passed into the exporter. This is either the file descriptor passed in upon instantiation of the agent or the file descriptor obtained by calling setFileDescriptor().

virtual const FileDescriptor* ExportAgent::getFileDescriptor

(

)

const [pure virtual]

Returns the file descriptor that will be passed into the exporter when it is executed.

Exceptions:

std::logic_error

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

Returns:

The file descriptor that is passed into the exporter. This is either the file descriptor passed in upon instantiation of the agent or the file descriptor obtained by calling setFileDescriptor().

virtual std::string ExportAgent::getDefaultExtensions

(

)

const [pure virtual]

Gets the default file extensions from the exporter.

Exceptions:

std::logic_error

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

Returns:

The default extensions string returned by calling Exporter::getDefaultExtensions().

virtual ValidationResultType ExportAgent::validate

(

std::string &

errorMessage

)

[pure virtual]

Validate the input argument list.

This validates the input argument list as it will be passed to Executable::execute(). If the plug-in is interactive, information and choices may be presented to the user to decide how to proceed. If the plug-in is in batch mode, information may be logged to the message log but no user interaction is possible.

Parameters:

errorMessage

This is the error or informational message to display to the user.

Exceptions:

std::logic_error

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

Returns:

Validation result indicating if the exporter can save the data

See also:

ValidationResultType

virtual bool ExportAgent::execute

(

)

[pure virtual]

Executes the exporter to save the data.

This method first creates the input and output arg lists if necessary, populates the input arg list, and then executes the exporter.

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:

• All args documented in ExecutableAgent::execute().
• Exporter::ExportItemArg() is populated with the SessionItem that will be exported as returned by getItem().
• Exporter::ExportDescriptorArg() is populated with the FileDescriptor to use for export as returned by getFileDescriptor().

Exceptions:

std::logic_error

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

Returns:

The success value returned by the exporter.

Implements ExecutableAgent.