ImporterShell Class Reference
[Plug-In Shells]

Importer Shell More...

#include <ImporterShell.h>

Inheritance diagram for ImporterShell:

List of all members.

Public Member Functions
	ImporterShell ()
virtual	~ImporterShell ()
virtual std::string	getDefaultExtensions () const
virtual bool	isProcessingLocationSupported (ProcessingLocation location) const
virtual QWidget *	getPreview (const DataDescriptor *pDescriptor, Progress *pProgress)
virtual bool	validate (const DataDescriptor *pDescriptor, std::string &errorMessage) const
virtual QWidget *	getImportOptionsWidget (DataDescriptor *pDescriptor)
virtual void	polishDataDescriptor (DataDescriptor *pDescriptor)
Protected Types
enum	ValidationTestEnum {   NO_VALIDATION = 0x00000000, EXISTING_FILE = 0x00000001, NO_EXISTING_DATA_ELEMENT = 0x00000002, VALID_CLASSIFICATION = 0x00000004,   VALID_METADATA = 0x00000008, VALID_PROCESSING_LOCATION = 0x00000010, RASTER_SIZE = 0x00000020, VALID_DATA_TYPE = 0x00000040,   NO_HEADER_BYTES = 0x00000080, NO_PRE_POST_LINE_BYTES = 0x00000100, NO_PRE_POST_BAND_BYTES = 0x00000200, NO_TRAILER_BYTES = 0x00000400,   FILE_SIZE = 0x00000800 | EXISTING_FILE, NO_BAND_FILES = 0x00001000, EXISTING_BAND_FILES = 0x00002000, BAND_FILE_SIZES = 0x00004000 | EXISTING_BAND_FILES,   VALID_BAND_NAMES = 0x00008000 | VALID_METADATA, VALID_WAVELENGTHS = 0x00010000 | VALID_METADATA, NO_INTERLEAVE_CONVERSIONS = 0x00020000, NO_ROW_SKIP_FACTOR = 0x00040000,   NO_COLUMN_SKIP_FACTOR = 0x00080000, NO_SKIP_FACTORS = NO_ROW_SKIP_FACTOR | NO_COLUMN_SKIP_FACTOR, NO_ROW_SUBSETS = 0x00100000, NO_COLUMN_SUBSETS = 0x00200000,   NO_BAND_SUBSETS = 0x00400000, NO_SUBSETS = NO_ROW_SUBSETS | NO_COLUMN_SUBSETS | NO_BAND_SUBSETS, AVAILABLE_MEMORY = 0x00800000 }
typedef EnumWrapper < ValidationTestEnum >	ValidationTest
Protected Member Functions
void	setExtensions (const std::string &extensions)
virtual int	getValidationTest (const DataDescriptor *pDescriptor) const
ValidationTest	getValidationError () const

---

Detailed Description

Importer Shell

This class represents the shell for an importer plug-in. Importer developers would take this class and extend it to support thier importer specific code.

See also:

ExecutableShell, Importer

Definition at line 29 of file ImporterShell.h.

---

Member Typedef Documentation

typedef EnumWrapper<ValidationTestEnum> ImporterShell::ValidationTest [protected]

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 ImporterShell::ValidationTestEnum.

Definition at line 204 of file ImporterShell.h.

---

Member Enumeration Documentation

enum ImporterShell::ValidationTestEnum [protected]

Identifies the test that should be performed to validate the import.

See also:

validate(), getValidationTest(), getValidationError()

Enumerator:

NO_VALIDATION	0x00000000 - No validation is performed.
EXISTING_FILE	0x00000001 - Checks that the filename contained in the file descriptor is a valid file that exists on the disk.
NO_EXISTING_DATA_ELEMENT	0x00000002 - Checks that an existing DataElement does not already exist by calling ModelServices::getElement().
VALID_CLASSIFICATION	0x00000004 - Checks for the existence of classification markings by checking the return value of DataDescriptor::getClassification() for a non-NULL pointer. Also reports a warning if the classification level of the data being imported is greater than the overall classification level of the system.
VALID_METADATA	0x00000008 - Checks for the existence of metadata by checking the return value of DataDescriptor::getMetadata() for a non-NULL pointer.
VALID_PROCESSING_LOCATION	0x00000010 - Checks that the processing location set in the data descriptor is valid by calling isProcessingLocationSupported().
RASTER_SIZE	0x00000020 - Checks for at least one data pixel by checking for a non-zero number of rows, columns, bands, and bits per element.
VALID_DATA_TYPE	0x00000040 - Checks that the data type set in the raster data descriptor is one of the valid data types returned by RasterDataDescriptor::getValidDataTypes().
NO_HEADER_BYTES	0x00000080 - Checks for no header bytes set on the raster file descriptor.
NO_PRE_POST_LINE_BYTES	0x00000100 - Checks for no preline or postline bytes set on the raster file descriptor.
NO_PRE_POST_BAND_BYTES	0x00000200 - Checks for no preband or postband bytes set on the raster file descriptor.
NO_TRAILER_BYTES	0x00000400 - Checks for no trailer bytes set on the raster file descriptor.
FILE_SIZE	0x00000800 - Checks that the size of the file set in the raster file descriptor (in bytes) is greater than or equal to required file size determined by calling RasterUtilities::calculateFileSize().
NO_BAND_FILES	0x00001000 - Checks that the number of band files is zero. Should not be combined with EXISTING_BAND_FILES.
EXISTING_BAND_FILES	0x00002000 - Checks that number of band files is equal to the number of bands in the raster file descriptor and that each of the band files exists on the disk. Should not be combined with NO_BAND_FILES.
BAND_FILE_SIZES	0x00004000 - Checks that the size of each band file (in bytes) is greater than or equal to the required file size determined by calling RasterUtilities::calculateFileSize().
VALID_BAND_NAMES	0x00008000 | VALID_METADATA - Checks that the number of band names set in the metadata is equal to the number of bands in the raster file descriptor. This test will succeed if band names are not present in the metadata.
VALID_WAVELENGTHS	0x00010000 | VALID_METADATA - Checks that the number of wavelengths set in the metadata is equal to the number of bands in the raster file descriptor by calling Wavelengths::getNumWavelengths(). This test will succeed if wavelengths are not present in the metadata.
NO_INTERLEAVE_CONVERSIONS	0x00020000 - Checks that the interleave format in the raster data descriptor matches the interleave format in the raster file descriptor. No check is performed if RasterFileDescriptor::getBandCount() returns 1.
NO_ROW_SKIP_FACTOR	0x00040000 - Checks for no skip factor in the raster data descriptor rows by calling RasterDataDescriptor::getRowSkipFactor().
NO_COLUMN_SKIP_FACTOR	0x00080000 - Checks for no skip factor in the raster data descriptor columns by calling RasterDataDescriptor::getColumnSkipFactor().
NO_SKIP_FACTORS	NO_ROW_SKIP_FACTOR | NO_COLUMN_SKIP_FACTOR - Convenience value that performs both NO_ROW_SKIP_FACTOR and NO_COLUMN_SKIP_FACTOR checks.
NO_ROW_SUBSETS	0x00100000 - Checks that the number of rows to import in the raster data descriptor matches the number of rows in the raster file descriptor.
NO_COLUMN_SUBSETS	0x00200000 - Checks that the number of columns to import in the raster data descriptor matches the number of columns in the raster file descriptor.
NO_BAND_SUBSETS	0x00400000 - Checks that the number of bands to import in the raster data descriptor matches the number of bands in the raster file descriptor.
NO_SUBSETS	NO_ROW_SUBSETS | NO_COLUMN_SUBSETS | NO_BAND_SUBSETS - Convenience value that performs all NO_ROW_SUBSETS, NO_COLUMN_SUBSETS, and NO_BAND_SUBSETS checks.
AVAILABLE_MEMORY	0x00800000 - Checks that the amount of required memory calculated from the rows, columns, bands, and bytes per element set in the raster data descriptor can be successfully allocated.

Definition at line 121 of file ImporterShell.h.

---

Constructor & Destructor Documentation

ImporterShell::ImporterShell

(

)

Creates an importer plug-in.

The constructor sets the plug-in type to PlugInManagerServices::ImporterType().

See also:

getType()

virtual ImporterShell::~ImporterShell

(

)

[virtual]

Destroys the importer plug-in.

---

Member Function Documentation

virtual std::string ImporterShell::getDefaultExtensions

(

)

const [virtual]

Returns the default file extensions recognized by the importer.

Returns:

The file extensions recognized by the importer as a string. The string consists of a description followed by one or more file extensions separated by a space. Multiple file types may be specified with a double semicolon. Examples include "ENVI Header Files (*.hdr)", "TIFF Files (*.tif *.tiff)", and "Source Files (*.c*);;Header Files (*.h)".

Default Implementation:

The default implementation returns the extension string that was passed into setExtensions(). If setExtensions() has not yet been called, an empty string is returned.

Implements Importer.

virtual bool ImporterShell::isProcessingLocationSupported

(

ProcessingLocation

location

)

const [virtual]

Queries whether the user can select the given processing location.

Parameters:

location

The processing location being queried to determine if it is supported.

Returns:

Returns true if the user can select the given processing location, otherwise returns false.

See also:

ProcessingLocation

Default Implementation:

Only a processing location of ProcessingLocation::IN_MEMORY is supported. If location is ProcessingLocation::IN_MEMORY, the default implementation returns true, otherwise false is returned.

Implements Importer.

Reimplemented in RasterElementImporterShell.

virtual QWidget* ImporterShell::getPreview	(	const DataDescriptor *	pDescriptor,
		Progress *	pProgress
	)			[virtual]

Returns a preview of a given data set.

This method provides the means by which the user can preview a data set before importing. Derived importers can override this method to create a Qt widget displaying preview contents.

This method is called by the core when the user views a preview of a data set before importing. The core application assumes ownership of the Qt widget, so the importer should not delete it. A View object can also be created for the preview, where the returned value should be View::getWidget().

Parameters:

	pDescriptor	The data set to preview.
	pProgress	A progress object in which the importer can report progress while getting the preview.

Returns:

A pointer to a Qt widget containing the preview contents that will be displayed to the user. The core application assumes ownership of the widget and will delete it when necessary. NULL is returned if no preview is available for the given data set.

Default Implementation:

The default implementation of this method does not create a preview and returns NULL.

Implements Importer.

Reimplemented in RasterElementImporterShell.

virtual bool ImporterShell::validate	(	const DataDescriptor *	pDescriptor,
		std::string &	errorMessage
	)			const [virtual]

Queries whether a given data descriptor can be successfully loaded by the importer.

This method is called for the importer to parse the current settings in the data descriptor to see if it supports loading the data as currently specified in the data descriptor. This allows importers that do not support certain combinations of values to indicate as such. This method is called each time the user changes a value in the import options dialog. This method is also called by ImportAgent::execute() before executing the importer.

Parameters:

	pDescriptor	The data descriptor to query if it can be successfully imported.
	errorMessage	An error message that is populated with the reason why the importer cannot load the given data descriptor. This message will be displayed to the user via the importer's Progress object. If this method returns true, this message will be displayed to the user as a warning. If this method returns false, this message will be displayed to the user as an error.

Returns:

Returns true if the importer can successfully import the given data descriptor; otherwise returns false.

See also:

DataDescriptor, FileDescriptor

Default Implementation:

The default implementation calls getValidationTest() to get the tests that should be used to validate the data set and then performs each of the tests specified.

Warning:

This method should not be called from within execute() because one or more of the tests (e.g. NO_EXISTING_DATA_ELEMENT) may fail since the import process has already started.

Implements Importer.

Reimplemented in RasterElementImporterShell, HdfImporterShell, and Nitf::NitfImporterShell.

virtual QWidget* ImporterShell::getImportOptionsWidget

(

DataDescriptor *

pDescriptor

)

[virtual]

Returns a widget to display custom import option values.

This method provides an interface for which specialized import options for a data set can be displayed to the user. The method returns a Qt widget that is added to the default import options dialog. The importer should create the widget with a NULL parent, and should destroy the widget when the importer itself is destroyed.

Importers should call QWidget::setWindowTitle() on the widget that is returned to set the name that appears on the tab in the import options dialog. If the window title is not set, the importer name is displayed.

Parameters:

pDescriptor

The data set for which to set the current values in the widget.

Returns:

A QWidget that will be displayed as an additional tab in the default import options dialog. NULL should be returned if the importer does not have custom options to display to the user.

Default Implementation:

The default implementation returns NULL.

Implements Importer.

virtual void ImporterShell::polishDataDescriptor

(

DataDescriptor *

pDescriptor

)

[virtual]

Modifies a data descriptor before it is imported.

This method is called after the user has made changes to the data descriptor contained in an ImportDescriptor returned in getImportDescriptors() and before the element is created for import.

Warning:

It is generally not recommended for an importer to modify values that the user has the capability to change in the import options dialog since any value that the user sets would be overridden without the user's knowledge.

Parameters:

pDescriptor

The data set to modify before import.

Default Implementation:

The default implementation does nothing.

Implements Importer.

void ImporterShell::setExtensions

(

const std::string &

extensions

)

[protected]

Sets the default file extensions recognized by the importer.

Parameters:

extensions

The file extensions recognized by the importer. The string should consist of a description followed by one or more extensions separated by a space. Multiple file types may be specified with a double semicolon. Examples include "ENVI Header Files (*.hdr)", "TIFF Files (*.tif *.tiff)", and "Source Files (*.c*);;Header Files (*.h)".

virtual int ImporterShell::getValidationTest

(

const DataDescriptor *

pDescriptor

)

const [protected, virtual]

Returns the test that should be performed when validating the given data set for import.

This method is called by validate() to determine which tests should be performed to validate the import. This method should be overridden by derived importers to add additional tests or remove default tests.

Parameters:

pDescriptor

The data descriptor for the data set that is being imported.

Returns:

Returns the test that should be used to validate the import. The value should be an OR'd combination of ValidationTest values.

Default Implementation:

The default implementation of this method returns the OR'd combination of the following tests:

• EXISTING_FILE
• NO_EXISTING_DATA_ELEMENT
• VALID_PROCESSING_LOCATION

Reimplemented in RasterElementImporterShell, HdfImporterShell, and Nitf::NitfImporterShell.

ValidationTest ImporterShell::getValidationError

(

)

const [protected]

Returns the test that failed during the last call to validate().

This method can be called by importers from within an override of the default implementation of validate() to determine which test failed the validation process while calling the base class ImporterShell::validate() method. This allows the importer to report custom error messages or to continue importing by converting an error to a warning and changing the validate() return value to true.

This method should not be called for importers that do not call this base class implementation.

Returns:

Returns the validation test that failed during the last call to ImporterShell::validate(). If this base class method has not been called or returned true, then an invalid value is returned. An invalid value is also returned if the data descriptor passed into validate() or its file descriptor are NULL.