com.ihr.xbrl.mapper

## Class MapEngine

- java.lang.Object
- - com.ihr.xbrl.mapper.MapEngine

-     public class MapEngine
      extends java.lang.Object

  This is the server side map engine. This MapEngine is responsible of providing an available mapper to the calling proces and to instantiate a new mapper if there is none available.
  Author:
    Ignacio

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `MAPPER_LAZY_OUTPUT_INSTACE` The MAPPER_LAZY_OUTPUT_INSTACE defines how the final produced instance document is going to be further processed.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MapEngine(java.net.URI configFile)` Creates a mapping engine.
    `MapEngine(java.net.URI configFile, int initialMappers)` Creates a mapping engine.
    `MapEngine(java.net.URI configFile, int initialMappers, DTSLoadingBarInterface bar, boolean bCreateMasterMapper)` Creates a mapping engine.
    `MapEngine(java.net.URI configFile, int initialMappers, DTSLoadingBarInterface bar, boolean bCreateMasterMapper, java.util.Properties dtsProperties)` Creates a mapping engine.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Mapper` | `getMasterMapper()` Access to the master mapper.
    `Mapper` | `getMasterMapper(DTSLoadingBarInterface bar)` Access to the master mapper.
    `XBRLInstance` | `map(java.lang.Object[] inputs)` Executes the mapping defined in the configuration file.
    `XBRLInstance` | `map(java.lang.Object[] inputs, DTSLoadingBarInterface bar)` Executes the mapping defined in the configuration file.
    `void` | `migrateConfigFile(XBRLInstance versioningReport, java.net.URI outputReportUri, java.net.URI newConfigFileUri)` Migrates a configuration file from using a DTS to using a new DTS with information from an XBRL versioning report.

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

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

- - ### Field Detail

    - #### MAPPER_LAZY_OUTPUT_INSTACE

          public static final java.lang.String MAPPER_LAZY_OUTPUT_INSTACE

      The MAPPER_LAZY_OUTPUT_INSTACE defines how the final produced instance document is going to be further processed. If the value of this property is "true" then the consequences and observations must be considered:
      - The generateInstance method on the Mapper class will produce a new instance document but the output DTS of that document will be the same DTS than the DTS for the mapper file. See note about sections below
      - The generateInstance method will run much faster than setting this value to "false"
      - It is supposed the instance document is going to be serialized to a file or not processed for XBRL validation as the DTS for the mapper file may include files not in the DTS of the produced result
      This property is a consequence of the existence of sections in the mapper file. The DTS of the mapper file is a "Super DTS" that contains all files in all sections. This is OK for creating a new XBRL report but may not be OK for validating the new XBRL report.

      The default value of this property is "false"

      Since:
        2.7.4
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### MapEngine

          public MapEngine(java.net.URI configFile)
                    throws com.rs.lic.LicenseVerificationException,
                           MapConfigurationFileException

      Creates a mapping engine. Normally called at the beginning of the application or in a static class in a server based solution. This constructor does not initialize any number of mappers so it is faster than the constructor that initializes mappers.
      Parameters:
        `configFile` - URI of the configuration file for mappers
      Throws:
        `com.rs.lic.LicenseVerificationException` - the license verification exception
        `MapConfigurationFileException` - never thrown as the number of mappers to initialize is 0

    - #### MapEngine

          public MapEngine(java.net.URI configFile,
                   int initialMappers)
                    throws com.rs.lic.LicenseVerificationException,
                           MapConfigurationFileException

      Creates a mapping engine. Normally called at the beginning of the application or in a static class in a server based solution.

      This constructor initializes a number of mappers as inidicated in the initialMappers parameter.

      The new mappers will be in the free state

      Parameters:
        `configFile` - URI of the configuration file for mappers
        `initialMappers` - number of mappers to initialize
      Throws:
        `com.rs.lic.LicenseVerificationException` - the license verification exception
        `MapConfigurationFileException` - if there is a problem initializing the mappers

    - #### MapEngine

          public MapEngine(java.net.URI configFile,
                   int initialMappers,
                   DTSLoadingBarInterface bar,
                   boolean bCreateMasterMapper)
                    throws com.rs.lic.LicenseVerificationException,
                           MapConfigurationFileException

      Creates a mapping engine. Normally called at the beginning of the application or in a static class in a server based solution.

      This constructor initializes a number of mappers as inidicated in the initialMappers parameter.

      The new mappers will be in the free state

      Parameters:
        `configFile` - URI of the configuration file for mappers
        `initialMappers` - number of mappers to initialize
        `bar` - this is a class that will be updated with messages during the process. Can be null
        `bCreateMasterMapper` - is true if the master mapper shall be created during this call. If bar is not null, there will be messages sent to the bar during the creation of the master.
      Throws:
        `com.rs.lic.LicenseVerificationException` - the license verification exception
        `MapConfigurationFileException` - if there is a problem initializing the mappers

    - #### MapEngine

          public MapEngine(java.net.URI configFile,
                   int initialMappers,
                   DTSLoadingBarInterface bar,
                   boolean bCreateMasterMapper,
                   java.util.Properties dtsProperties)
                    throws com.rs.lic.LicenseVerificationException,
                           MapConfigurationFileException

      Creates a mapping engine. Normally called at the beginning of the application or in a static class in a server based solution.

      This constructor initializes a number of mappers as inidicated in the initialMappers parameter.

      The new mappers will be in the free state

      Parameters:
        `configFile` - URI of the configuration file for mappers
        `initialMappers` - number of mappers to initialize
        `bar` - this is a class that will be updated with messages during the process
        `bCreateMasterMapper` - is true if the master mapper shall be created during this call. If bar is not null, there will be messages sent to the bar during the creation of the master.
        `dtsProperties` - properties for new DTSContainers inside the Mapper and mapper specific properties
      Throws:
        `com.rs.lic.LicenseVerificationException` - the license verification exception
        `MapConfigurationFileException` - if there is a problem initializing the mappers

  - ### Method Detail

    - #### map

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

      Executes the mapping defined in the configuration file. In this case the XBRLDataSource(s) involved will receive the input parameters before start.

      The returned instance is not validated against the taxonomy and may not be valid if the taxonomy contains tuples. The validation of the generated report must be responsibility of the next step in the process

      Parameters:
        `inputs` - array of parameters to be sent to the drivers. null is valid value
      Returns:
        XBRLInstance
      Throws:
        `MapException` - the map exception

    - #### map

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

      Executes the mapping defined in the configuration file. In this case the XBRLDataSource(s) involved will receive the input parameters before start.

      The returned instance is not validated against the taxonomy and may not be valid if the taxonomy contains tuples. The validation of the generated report must be responsibility of the next step in the process

      Parameters:
        `inputs` - array of parameters to be sent to the drivers. null is valid value
        `bar` - instance of DTSLoadingBarInterface or null if not required
      Returns:
        XBRLInstance
      Throws:
        `MapException` - the map exception

    - #### migrateConfigFile

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

      Migrates a configuration file from using a DTS to using a new DTS with information from an XBRL versioning report.
      Parameters:
        `versioningReport` - XBRLInstance the versioning report describing the changes between the two DTSs
        `outputReportUri` - where the report about the migration process will be serailized
        `newConfigFileUri` - the URI for the new configuration file
      Throws:
        `MapException` - if there is something wrong.

    - #### getMasterMapper

          public Mapper getMasterMapper()
                                 throws MapConfigurationFileException

      Access to the master mapper. A master mapper is a mapper used by GUIs so properties of the mapper can be set and tested.
      Returns:
        the master mapper
      Throws:
        `MapConfigurationFileException` - the map configuration file exception

    - #### getMasterMapper

          public Mapper getMasterMapper(DTSLoadingBarInterface bar)
                                 throws MapConfigurationFileException

      Access to the master mapper. A master mapper is a mapper used by GUIs so properties of the mapper can be set and tested.
      Parameters:
        `bar` - DTSLoadingBarInterface for sending messages during the master creation process
      Returns:
        the master mapper
      Throws:
        `MapConfigurationFileException` - the map configuration file exception