WARNING: PLEASE DON'T USE THE CONFIGURATOR PATTERN. THE RELATED BASE CLASSES
WILL BECOME DEPRECATED AS SOON AS GENERICSETUP ITSELF NO LONGER USES THEM.

The Products.GenericSetup.utils.ImportConfiguratorBase class provides
a convenient shortcut for defining how an XML file should be parsed
and converted to a python dictionary.  To use this, create a subclass
of ImportConfiguratorBase and implement a _getImportMapping method
which returns a dictionary.  The returned dictionary should adhere to
the following guidelines:

- The utils module provides CONVERTER, DEFAULT, and KEY constants that
  are to be used in the import mapping to define certain behaviours.

- Any possible tag that you want your XML file format to support must
  be listed as a top-level key in the import mapping dictionary.

- The value of any key in the import mapping dictionary should be
  another dictionary.

- If an outer key represents a possible tag, then the nested
  dictionary represents the possible "properties" of that tag, where a
  property might be an attribute of the tag, the text content of the
  tag, or possibly a nested tag.

- If a key of the nested dictionary represents a nested tag, you will
  also need a top-level key to represent that tag.  The nested
  representation of the tag is where you make statements about how the
  tag itself should be represented, while the top-level key allows you
  to express information about how the data that is further nested
  within the nested tag should be represented.

- A CONVERTER can be registered on a an element to change the way that
  the element is represented in the generated data structure.
  self._convertToUnique will cause the element to be represented as a
  single item and not a tuple of items, for instance.

- A KEY can be specified for an element.  If it is specified then the
  element's value will be stored in the resulting python dictionary
  with the KEY value as the key.  If KEY is None, then the value will
  be stored in a tuple rather than as a value in a nested dictionary.
  If KEY is omitted, then the name of the element will be used as the
  key.

- A DEFAULT value can be specified on an element, which will be used
  as the value on that element if the element doesn't actually exist
  in the XML file.

- Reference examples for this syntax can be found in the
  metadata.ProfileMetadata and the rolemap.RolemapImportConfigurator
  classes.
