ImportAgent Class Reference

A convenience class that makes working with Importer plug-ins easier. More...

#include <ImportAgent.h>

Inheritance diagram for ImportAgent:

Inheritance graph

List of all members.

Public Types

enum  EditTypeEnum { NEVER_EDIT, AS_NEEDED_EDIT, ALWAYS_EDIT }
typedef EnumWrapper< EditTypeEnum > EditType

Public Member Functions

virtual void instantiate (Progress *pProgress, bool batch)=0
virtual void instantiate (const std::string &importerName, Progress *pProgress, bool batch)=0
virtual void instantiate (const std::string &importerName, const std::string &filename, Progress *pProgress, bool batch)=0
virtual void instantiate (const std::string &importerName, const std::vector< std::string > &filenames, Progress *pProgress, bool batch)=0
virtual void instantiate (const std::string &importerName, const std::map< std::string, std::vector< ImportDescriptor * > > &datasets, Progress *pProgress, bool batch)=0
virtual void instantiate (PlugIn *pPlugIn, const std::map< std::string, std::vector< ImportDescriptor * > > &descriptors, Progress *pProgress, bool batch)=0
virtual void setFilename (const std::string &filename)=0
virtual void setFilenames (const std::vector< std::string > &filenames)=0
virtual void setImporterSubtype (const std::string &subtype)=0
virtual std::string getImporterSubtype () const =0
virtual void setEditType (EditType editType)=0
virtual EditType getEditType () const =0
virtual void updateMruFileList (bool updateList)=0
virtual bool isMruFileListUpdated () const =0
virtual void setDatasets (const std::map< std::string, std::vector< ImportDescriptor * > > &datasets)=0
virtual std::vector
< ImportDescriptor * > 		getImportDescriptors ()=0
virtual std::vector
< ImportDescriptor * > 		getImportDescriptors (const std::string &filename)=0
virtual std::map< std::string,
std::vector< ImportDescriptor * > > 		getDatasets ()=0
virtual std::string getDefaultExtensions () const =0
virtual bool execute ()=0
virtual std::vector
< DataElement * > 		getImportedElements () const =0

Protected Member Functions

virtual ~ImportAgent ()

Detailed Description

A convenience class that makes working with Importer plug-ins easier.

This class manages the lifecycle of an Importer plug-in. This class can be used to import one or more files or just individual data sets within one or more files.

After executing the importer, the imported data sets can be retrieved by calling getImportedElements(). You should not create an instance of this class using ObjectFactory, but you should use ImporterResource instead.

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:
ImporterResource, Importer

Definition at line 41 of file ImportAgent.h.

Member Typedef Documentation

typedef EnumWrapper<EditTypeEnum> ImportAgent::EditType

The EnumWrapper contains a given enum value and provides a isValid() method which returns true if the contained enum value is valid.

Please see How To Use EnumWrapper for more information. The wrapped enum values are EditTypeEnum

Definition at line 67 of file ImportAgent.h.

Member Enumeration Documentation

enum ImportAgent::EditTypeEnum

Specifies the conditions in which the user can edit the import data parameters via the import options dialog.

See also:
setEditType()
Enumerator:
NEVER_EDIT  The user can never edit the import parameters before the import is performed.

AS_NEEDED_EDIT  The user can only edit the import parameters if the importer cannot import the data with the current parameters.

ALWAYS_EDIT  The user is always given the chance to edit the import parameters before the import is performed.

Definition at line 52 of file ImportAgent.h.

Constructor & Destructor Documentation

virtual ImportAgent::~ImportAgent (  )  [protected, virtual]

Destroys the agent.

This object should not be destroyed directly. It is most commonly destroyed by ImporterResource.

Definition at line 547 of file ImportAgent.h.

Member Function Documentation

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

Creates an invalid object for delayed initialization of an ImportAgent.

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

Parameters:
pProgress The progress object to pass into the importer. If NULL is passed in, a progress object is obtained by calling PlugInManagerServices::getProgress().
batch Set this value to true to execute the importer in batch mode or to false to execute the importer in interactive mode.
Exceptions:
std::logic_error Thrown if the instantiate() method is called more than once on this instance.

Implements ExecutableAgent.

virtual void ImportAgent::instantiate ( const std::string &  importerName,
Progress *  pProgress,
bool  batch 
) [pure virtual]

Creates an importer to import data.

Creates the importer but does not specify the files or data sets to import. The setFilename(), setFilenames(), or setDatasets() method must therefore be called before calling execute().

Parameters:
importerName The name of the importer to create and execute.
pProgress The progress object to pass into the importer. If NULL is passed in, a progress object is obtained by calling PlugInManagerServices::getProgress().
batch Set this value to true to execute the importer in batch mode or to false to execute the importer in interactive mode.
Exceptions:
std::logic_error Thrown if the instantiate() method is called more than once on this instance.

virtual void ImportAgent::instantiate ( const std::string &  importerName,
const std::string &  filename,
Progress *  pProgress,
bool  batch 
) [pure virtual]

Creates an importer to import data from a single file.

When importing data from a file, all data sets returned by Importer::getImportDescriptors() are imported.

Parameters:
importerName The name of the importer to create and execute.
filename The file from which to load the data.
pProgress The progress object to pass into the importer. If NULL is passed in, a progress object is obtained by calling PlugInManagerServices::getProgress().
batch Set this value to true to execute the importer in batch mode or to false to execute the importer in interactive mode.
Exceptions:
std::logic_error Thrown if the instantiate() method is called more than once on this instance.

Implements ExecutableAgent.

virtual void ImportAgent::instantiate ( const std::string &  importerName,
const std::vector< std::string > &  filenames,
Progress *  pProgress,
bool  batch 
) [pure virtual]

Creates an importer to import data from multiple files.

When importing data from multiple files, all data sets returned by Importer::getImportDescriptors() are imported.

Parameters:
importerName The name of the importer to create and execute.
filenames The files from which to load the data.
pProgress The progress object to pass into the importer. If NULL is passed in, a progress object is obtained by calling PlugInManagerServices::getProgress().
batch Set this value to true to execute the importer in batch mode or to false to execute the importer in interactive mode.
Exceptions:
std::logic_error Thrown if the instantiate() method is called more than once on this instance.

virtual void ImportAgent::instantiate ( const std::string &  importerName,
const std::map< std::string, std::vector< ImportDescriptor * > > &  datasets,
Progress *  pProgress,
bool  batch 
) [pure virtual]

Creates an importer to import individual data sets from one or more files.

Parameters:
importerName The name of the importer to create and execute.
datasets The files and data sets to import. The descriptor values should have been obtained by calling Importer::getImportDescriptors(). The provided import descriptors will be owned by the agent.
pProgress The progress object to pass into the importer. If NULL is passed in, a progress object is obtained by calling PlugInManagerServices::getProgress().
batch Set this value to true to execute the importer in batch mode or to false to execute the importer in interactive mode.
Exceptions:
std::logic_error Thrown if the instantiate() method is called more than once on this instance.

virtual void ImportAgent::instantiate ( PlugIn *  pPlugIn,
const std::map< std::string, std::vector< ImportDescriptor * > > &  descriptors,
Progress *  pProgress,
bool  batch 
) [pure virtual]

Uses an existing importer to import individual data sets from one or more files.

Parameters:
pPlugIn The importer to execute. The agent assumes ownership of the importer and will destroy it as necessary upon agent destruction.
descriptors The files and data sets to import. The descriptor values should have been obtained by calling Importer::getImportDescriptors(). The provided import descriptors will be owned by the agent.
pProgress The progress object to pass into the importer. If NULL is passed in, a progress object is obtained by calling PlugInManagerServices::getProgress().
batch Set this value to true to execute the importer in batch mode or to false to execute the importer in interactive mode.
Exceptions:
std::logic_error Thrown if the instantiate() method is called more than once on this instance.

virtual void ImportAgent::setFilename ( const std::string &  filename  )  [pure virtual]

Sets the agent to import all data from a single file.

This method sets one file from which to import data. Any existing data descriptors are removed and deleted. After calling this method, the next call to execute() will call Importer::getImportDescriptors() to determine the data sets to import.

Parameters:
filename The name of the file to import.
Exceptions:
std::logic_error Thrown if the instantiate() method has not yet been called on this instance.
See also:
setFilenames(), setDatasets()

virtual void ImportAgent::setFilenames ( const std::vector< std::string > &  filenames  )  [pure virtual]

Sets the agent to import data from multiple files.

This method sets multiple files from which to import data. Any existing data descriptors are removed and deleted. After calling this method, the next call to execute() will call Importer::getImportDescriptors() to determine the data sets to import.

Parameters:
filenames The names of the files to import.
Exceptions:
std::logic_error Thrown if the instantiate() method has not yet been called on this instance.
See also:
setFilename(), setDatasets()

virtual void ImportAgent::setImporterSubtype ( const std::string &  subtype  )  [pure virtual]

Filters importers displayed in the import dialog based on subtype.

If the agent executes in interactive mode and no filenames have been set, the import dialog is displayed for the user to choose the importer and one or more files to import. This method filters the available importers in the dialog based on the given subtype. Only importers that have a subtype equal to the given subtype will be displayed in the dialog.

By default, if this method is not called, all importers are displayed in the import dialog.

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

Parameters:
subtype The subtype for importers that should be displayed in the import dialog. Passing in an empty string will display all importers in the import dialog.
Exceptions:
std::logic_error Thrown if the instantiate() method has not yet been called on this instance.
See also:
getImporterSubtype()

virtual std::string ImportAgent::getImporterSubtype (  )  const [pure virtual]

Returns the subtype of the importers displayed in the import dialog.

Exceptions:
std::logic_error Thrown if the instantiate() method has not yet been called on this instance.
Returns:
Returns the subtype of the importers displayed in the import dialog. Returns an empty string if all importers are displayed or if ApplicationServices::isInteractive() returns false.
See also:
setImporterSubtype()

virtual void ImportAgent::setEditType ( EditType  editType  )  [pure virtual]

Allows the user to edit the import data parameters before importing the data.

This method sets when the user should be able to edit the data to be imported. If editing is enabled, the import options dialog is displayed for the user to make any desired changes.

The default state of the agent is to never allow the user to edit the data before import.

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

Parameters:
editType The conditions in which the user can edit the import data parameters.
Exceptions:
std::logic_error Thrown if the instantiate() method has not yet been called on this instance.
See also:
getEditType()

virtual EditType ImportAgent::getEditType (  )  const [pure virtual]

Returns the conditions in which the user can edit the import data parameters before importing the data.

Exceptions:
std::logic_error Thrown if the instantiate() method has not yet been called on this instance.
Returns:
Returns the conditions in which the user can edit the import data parameters. Returns EditType::NEVER_EDIT if ApplicationServices::isInteractive() returns false.
See also:
setEditType()

virtual void ImportAgent::updateMruFileList ( bool  updateList  )  [pure virtual]

Adds the imported files to the most recently used (MRU) file list.

This method allows for imported files to be added to the MRU file list so that users can quickly reimport the data at a later time. Typically files should only be added to the MRU list if the user initiated the import. Otherwise, it may confuse the user to see a file in the list that was not directly imported.

The filename that is added to the MRU file list is the filename that is passed into the instantiate(), setFilename(), setFilenames() or setDatasets() method. If a filename is not set in the agent and the import dialog is displayed, the files that the user selects in the dialog are added to the MRU file list. Otherwise, no files are added to the MRU list.

By default, if this method is not called, imported files are not added to the MRU file list.

Parameters:
updateList Set this parameter to true to add imported files to the MRU file list.
Exceptions:
std::logic_error Thrown if the instantiate() method has not yet been called on this instance.

virtual bool ImportAgent::isMruFileListUpdated (  )  const [pure virtual]

Queries whether an imported file is added to the most recently used (MRU) file list.

Exceptions:
std::logic_error Thrown if the instantiate() method has not yet been called on this instance.
Returns:
Returns true if an imported file is added to the MRU file list, otherwise returns false.
See also:
updateMruFileList()

virtual void ImportAgent::setDatasets ( const std::map< std::string, std::vector< ImportDescriptor * > > &  datasets  )  [pure virtual]

Sets the files and data sets to import.

This method sets the files and their data sets that will be imported. The agent will take ownership over the provided import descriptors. After calling this method, the next call to execute() will import these data sets and will not call Importer::getImportDescriptors() to obtain the data sets to import.

Parameters:
datasets The files and the import descriptors to import.
Exceptions:
std::logic_error Thrown if the instantiate() method has not yet been called on this instance.
See also:
setFilename(), setFilenames()

virtual std::vector<ImportDescriptor*> ImportAgent::getImportDescriptors (  )  [pure virtual]

Returns the data sets for all files that will be used on import.

This method returns all data sets in all files specified in instantiate() or setDatasets(). If the import descriptors have not been set, Importer::getImportDescriptors() is called using the filenames set in instantiate(), setFilename(), or setFilenames().

Regardless of how they are obtained, all import descriptors stored and returned by this method are owned by the agent.

Exceptions:
std::logic_error Thrown if the instantiate() method has not yet been called on this instance.
Returns:
The import descriptors that will be used on import.
See also:
getImportDescriptors(const std::string&)

virtual std::vector<ImportDescriptor*> ImportAgent::getImportDescriptors ( const std::string &  filename  )  [pure virtual]

Returns the data sets for a given file that will be used on import.

This method returns all data sets in the given file that have been specified in instantiate() or setDatasets(). If the import descriptors have not been set, Importer::getImportDescriptors() is called using the filenames set in instantiate(), setFilename(), or setFilenames().

Regardless of how they are obtained, all import descriptors stored and returned by this method are owned by the agent.

Parameters:
filename The file for which to get its data sets to import.
Exceptions:
std::logic_error Thrown if the instantiate() method has not yet been called on this instance.
Returns:
The import descriptors for the given file that will be used on import. An empty vector is returned if the file has not previously been by calling instantiate(), setFilename(), setFilenames(), or setDatasets().
See also:
getImportDescriptors(), getDatasets()

virtual std::map<std::string, std::vector<ImportDescriptor*> > ImportAgent::getDatasets (  )  [pure virtual]

Returns the files and data sets that will be used on import.

This method returns the files and data sets specified in instantiate() or setDatasets(). If the import descriptors have not been set, Importer::getImportDescriptors() is called using the filenames set in instantiate(), setFilename(), or setFilenames().

Regardless of how they are obtained, all import descriptors stored and returned by this method are owned by the agent.

Exceptions:
std::logic_error Thrown if the instantiate() method has not yet been called on this instance.
Returns:
The filenames and import descriptors that will be used on import.
See also:
getImportDescriptors(), getImportDescriptors(const std::string&)

virtual std::string ImportAgent::getDefaultExtensions (  )  const [pure virtual]

Returns the default file extensions from the importer.

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 Importer::getDefaultExtensions(). An empty string is returned if no importer has been set.

virtual bool ImportAgent::execute (  )  [pure virtual]

Executes the importer to load the data from the files.

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

If the import descriptors of the files to import have not been set, getImportDescriptors() is called. A model element is created for each data set using the data descriptor contained in each import descriptor, and the ExecutableAgent::execute() base class method is called to execute the importer. All successfully imported data elements can be retrieved by calling getImportedElements().

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:
Exceptions:
std::logic_error Thrown if the instantiate() method has not yet been called on this instance.
Returns:
Returns true if at least one data set is imported successfully. Returns false for any of the following conditions:
  • The options dialog is displayed and the user cancels it.
  • None of the data descriptors selected for import validate.
  • Any data element could not be created.
  • The importer fails to import all data sets selected for import.
See also:
setEditType()

Implements ExecutableAgent.

virtual std::vector<DataElement*> ImportAgent::getImportedElements (  )  const [pure virtual]

Returns all successfully imported data elements.

The execute() method must be called prior to calling this method for the returned vector to be populated.

Exceptions:
std::logic_error Thrown if the instantiate() method has not yet been called on this instance.
Returns:
A vector containing pointers to the data elements that were created as a result of calling execute(). An empty vector is returned if execute() has not previously been called or if the importer was not able to import any data.

Software Development Kit - Opticks 4.9.0 Build 16218