com.ihr.xbrl.mapper

## Class Mapper

- java.lang.Object
- - com.ihr.xbrl.mapper.MapperBase
  - - com.ihr.xbrl.mapper.Mapper

- All Implemented Interfaces:
    HasFacts, MapperFileSaveInterface

      public class Mapper
      extends MapperBase
      implements MapperFileSaveInterface

  This is the main class responsible of the overall process.
  Author:
    Ignacio

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Mapper.PeriodMapping` This is a simple grouping class that is used for packaging information about how to map an XBRLPeriod to information inside the configuration files in order to translate the Periods into generic mappings for reuse over time.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Mapper(java.net.URI configFile, DTSLoadingBarInterface bar)` Creates a mapping engine object.
    `Mapper(java.net.URI configFile, DTSLoadingBarInterface bar, java.util.Properties dtsProperties)` Creates a mapping engine object.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static MapperFileSaveInterface` | `createConfigFile(XBRLInstance instance, java.net.URI config, java.net.URI configConfUri, java.lang.String scheme, java.lang.String company, java.util.ArrayList<Mapper.PeriodMapping> mappingPeriods, XBRLDataSource dataSource)` This function generates a sample configuration file for a given DTS.
    `XBRLInstance` | `generateInstance(java.lang.Object[] inputs)` Generates a new instance document obtaining data from data sources and using the information in the configuration file.
    `XBRLInstance` | `generateInstance(java.lang.Object[] inputs, DTSLoadingBarInterface bar)` Generates a new instance document obtaining data from data sources and using the information in the configuration file.
    `java.lang.String` | `getCompany()` Gets the company.
    `DTSContainer` | `getContainer()` Access to the surrounding DTSContainer of this Mapper instance.
    `java.lang.String[]` | `getDtsURLs()` Gets the dts ur ls.
    `java.lang.String` | `getScheme()` Gets the scheme.
    `java.net.URI` | `getUriOfConfigFile()` Gets the uri of config file.
    `MapVersion` | `getVersion()` Gets the version.
    `java.util.Collection<MapperWarningMessage>` | `getWarnings()` In case there where duplicates in the map identifiers warning messages are generated.
    `void` | `migrateConfigFile(XBRLInstance versioningReport, java.net.URI outputReportUri, java.net.URI newConfigFileUri)` Migrates a mapping configuration file to a new release of a DTS Produces a XHTML file in the given URI with information about the migration process.
    `void` | `removeUnassignedFacts()` This method removes from the loaded xbrlt template file all entries that has been mapped to an XBRLDataSource but the targer XBRLDataSource contains no further information about the fact map identifier.
    `void` | `save()` Stores the content of this configuration file on disk using the uriOfConfigFile.
    `static void` | `save(MapperFileSaveInterface mapperFileSave)` Save the Mapper configuration file to disk using the file name assigned with a call to `setURI(URI)`. this method rebuilds the entire configuration file from the object model.
    `void` | `setURI(java.net.URI newURI)` Changes or sets this URI new config file.

    - ### Methods inherited from class com.ihr.xbrl.mapper.MapperBase

      `addContext, addFact, addFactAt, addSection, addSource, addUnit, checkDuplicates, delFact, delSection, getAllFactsForElement, getAllMapIdentifiersForElement, getChildrenFacts, getContextById, getContexts, getContextsKeys, getFactFromMapIdentifier, getKeyForSource, getMapIdentifierForElement, getNewMapIdentifier, getParent, getSectionForKey, getSectionKeys, getSections, getSourceForKey, getSourceKeys, getUnitForKey, getUnitKeys, registerFact, unregisterFact`

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface com.ihr.xbrl.mapper.MapperFileSaveInterface

      `getChildrenFacts, getContextById, getContexts, getContextsKeys, getSections, getSourceForKey, getSourceKeys, getUnitForKey, getUnitKeys`

    - ### Methods inherited from interface com.ihr.xbrl.mapper.HasFacts

      `equals, hashCode`

- - ### Constructor Detail

    - #### Mapper

          public Mapper(java.net.URI configFile,
                DTSLoadingBarInterface bar)
                 throws MapConfigurationFileException

      Creates a mapping engine object. The configuration file is loaded into the mapping processor

      Typically, next call to the engine will be to the generateInstance method

      Mappers are created by the MapEngine. Applications should not create instantiations of the Mapper out of a MapEngine for normal Mapping processing

      Parameters:
        `configFile` - cannot be null and must refer to an existing template file
        `bar` - DTSLoadingBarInterface
      Throws:
        `MapConfigurationFileException` - the map configuration file exception

    - #### Mapper

          public Mapper(java.net.URI configFile,
                DTSLoadingBarInterface bar,
                java.util.Properties dtsProperties)
                 throws MapConfigurationFileException

      Creates a mapping engine object. The configuration file is loaded into the mapping processor

      Typically, next call to the engine will be to the generateInstance method

      Mappers are created by the MapEngine. Applications should not create instantiations of the Mapper out of a MapEngine for normal Mapping processing

      Parameters:
        `configFile` - cannot be null and must refer to an existing template file
        `bar` - DTSLoadingBarInterface
        `dtsProperties` - properties for the dts configuration file
      Throws:
        `MapConfigurationFileException` - the map configuration file exception

  - ### Method Detail

    - #### createConfigFile

          public static MapperFileSaveInterface createConfigFile(XBRLInstance instance,
                                                 java.net.URI config,
                                                 java.net.URI configConfUri,
                                                 java.lang.String scheme,
                                                 java.lang.String company,
                                                 java.util.ArrayList<Mapper.PeriodMapping> mappingPeriods,
                                                 XBRLDataSource dataSource)
                                                          throws XBRLSerializationException,
                                                                 MapConfigurationFileException

      This function generates a sample configuration file for a given DTS. The configuration file would require further editing. The information that must be provided is:
      1. The instance DTS; may be an empty instance just the DTS components are required in order to obtain the DTS starting point(s),
      2. the initial contexts (instant and duration), and
      3. the units (at least one unit).
      There may be one instant context and one duration context (or more). If all facts are of one period type, then the method will success if only one context of that period type is provided.

      Facts are not required in the incoming instance document. They will be read from the DTS. But if the instance contains facts then only facts from the instance will be included in the output template file.

      XBRL Dimensions

      Prior to 03/02/2011 (Version 2.7), this method did not use XBRL Dimensions. Only plain XBRL 2.1 template files was generated. Now, this method is able to obtain dimensions from the DTS applicable to each fact item in the DTS. If the primary item contains dimensions a new context is created and dimensions are added according to one of the hypercubes selected from the definition linkbase. Please bear in mind that:

      1. The method already explores all hypercubes linked with a primary item in all base sets. All combinations are merged into the set of possible combinations. There will be a fact item reported in the template for each possibility defined in the dimensional space.
      2. If the primary item is open, the context may contain additional dimensions not declared in the hypercubes. This will be documented with a comment (open context)
      3. If the primary item is closed, the context must not contain additional dimensions. This will be documented with a comment (closed context)
      4. If the primary item contains typed dimensions then the typed dimension value will be text string 'sample typed dimension value' this may not be a valid value for the typed dimension domain container.
      5. If the user's license does not allows for the dimensions processor to be created then no dimensional information will be added to the contexts
      6. If the DTS is dimensionally invalid. Then the dimensions processor will not be used.
      Parameters:
        `instance` - an XBRL Instance. May be an empty instance just with the DTS elements (schemaRef and linkbaseRef)
        `config` - URI of the template file
        `configConfUri` - if the mapper driver requires a configuration file this is the URI of the mapper driver configuration file. Otherwise this is null.
        `scheme` - String for the scheme in contexts that uses "_" in the scheme
        `company` - String for company name in contexts that uses "_" in the identifier
        `mappingPeriods` - array of PeriodMapping instances. This array will be used to match periods in the XBRL instance with the corresponding period in the instance template (Note they are not the same because the Period in the instance template allow for some variable substitution and formula processing of the dates).
        `dataSource` - an instance of the XBRLDataSource class whose class name will be used as the first and unique source of data on this template file. If null then VoidDataSource will be used.
      Returns:
        Mapper object
      Throws:
        `XBRLSerializationException` - the XBRL serialization exception
        `MapConfigurationFileException` - the map configuration file exception

    - #### getContainer

          public DTSContainer getContainer()

      Access to the surrounding DTSContainer of this Mapper instance. May return null if the instance is not initialized (no configuration file has been provided).

      Access to this property is provided in order to let the external tools like the Mapper Task Pane to access to the DTS content and properly work with it inside Excel.

      Specified by:
        `getContainer` in interface `MapperFileSaveInterface`
      Returns:
        DTSContainer or null.
      Since:
        2.6.10

    - #### setURI

          public void setURI(java.net.URI newURI)

      Changes or sets this URI new config file.
      Parameters:
        `newURI` - URI

    - #### migrateConfigFile

          public void migrateConfigFile(XBRLInstance versioningReport,
                               java.net.URI outputReportUri,
                               java.net.URI newConfigFileUri)

      Migrates a mapping configuration file to a new release of a DTS Produces a XHTML file in the given URI with information about the migration process. This function does not override old configuration file. It creates a new configuration file instead.
      Parameters:
        `versioningReport` - XBRLInstance the versioning report where information about the two DTSs exists
        `outputReportUri` - URI the XHTML file generated by this process
        `newConfigFileUri` - URI the new configuration file

    - #### save

          public void save()
                    throws XBRLSerializationException

      Stores the content of this configuration file on disk using the uriOfConfigFile.
      Throws:
        `XBRLSerializationException` - the XBRL serialization exception

    - #### save

          public static void save(MapperFileSaveInterface mapperFileSave)
                           throws XBRLSerializationException

      Save the Mapper configuration file to disk using the file name assigned with a call to `setURI(URI)`. this method rebuilds the entire configuration file from the object model.

      All the information to store in the configuration file will be obtained from the parameter `MapperFileSaveInterface`. Note that a call to `createConfigFile(XBRLInstance, URI, URI, String, String, ArrayList, XBRLDataSource)` already returns an instance of that class. A `Mapper` instance also implements that interface.

      Parameters:
        `mapperFileSave` - the mapper file save
      Throws:
        `XBRLSerializationException` - the XBRL serialization exception

    - #### getWarnings

          public java.util.Collection<MapperWarningMessage> getWarnings()

      In case there where duplicates in the map identifiers warning messages are generated. This method returns the warning messages as a collection of objects
      Returns:
        Collection<MapperWarningMessage>

    - #### removeUnassignedFacts

          public void removeUnassignedFacts()

      This method removes from the loaded xbrlt template file all entries that has been mapped to an XBRLDataSource but the targer XBRLDataSource contains no further information about the fact map identifier.

      The algorithm used to detect if the fact is not used requires the driver implements the interface XBRLDataSourceMapIdInUse. The algorithm used is as follows:

      1. For each Fact in the template
      2. Obtain the XBRLDataSource
      3. If the XBRLDataSource implements XBRLDataSourceMapIdInUse call the isMapIdentifierInUse(mapIdentifier) method
      4. If the returned value is false, then remove the fact
      The algorithm works for the Excel data source, but may not work for other data sources.

    - #### generateInstance

          public XBRLInstance generateInstance(java.lang.Object[] inputs)
                                        throws MapException

      Generates a new instance document obtaining data from data sources and using the information in the configuration file. The new instance document is returned
      Parameters:
        `inputs` - input parameters to the XBRLDataSources
      Returns:
        XBRLInstance
      Throws:
        `MapException` - the map exception

    - #### generateInstance

          public XBRLInstance generateInstance(java.lang.Object[] inputs,
                                      DTSLoadingBarInterface bar)
                                        throws MapException

      Generates a new instance document obtaining data from data sources and using the information in the configuration file. The new instance document is returned
      Parameters:
        `inputs` - input parameters to the XBRLDataSources
        `bar` - instance of DTSLoadingBarInterface or null if not required
      Returns:
        XBRLInstance
      Throws:
        `MapException` - the map exception

    - #### getScheme

          public java.lang.String getScheme()

      Gets the scheme.
      Specified by:
        `getScheme` in interface `MapperFileSaveInterface`
      Specified by:
        `getScheme` in class `MapperBase`
      Returns:
        String

    - #### getCompany

          public java.lang.String getCompany()

      Gets the company.
      Specified by:
        `getCompany` in interface `MapperFileSaveInterface`
      Specified by:
        `getCompany` in class `MapperBase`
      Returns:
        String

    - #### getVersion

          public MapVersion getVersion()

      Gets the version.
      Specified by:
        `getVersion` in class `MapperBase`
      Returns:
        the version

    - #### getUriOfConfigFile

          public java.net.URI getUriOfConfigFile()

      Gets the uri of config file.
      Specified by:
        `getUriOfConfigFile` in interface `MapperFileSaveInterface`
      Returns:
        the uriOfConfigFile

    - #### getDtsURLs

          public java.lang.String[] getDtsURLs()

      Gets the dts ur ls.
      Specified by:
        `getDtsURLs` in interface `MapperFileSaveInterface`
      Returns:
        the dtsURLs