com.ihr.xbrl.mapper

Class Mapper

java.lang.Object

com.ihr.xbrl.mapper.MapperBase

com.ihr.xbrl.mapper.Mapper

All Implemented Interfaces:

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

Modifier and Type	Method and Description
void	clear()
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, XBRLValidationReport mapReport) Generates a new instance document obtaining data from data sources and using the information in the configuration file.
XBRLInstance	generateInstance(java.lang.Object[] inputs, XBRLValidationReport mapReport) Generates a new instance document obtaining data from data sources and using the information in the configuration file.
java.util.Iterator<MapperFact>	getChildrenFacts() Access to facts on the configuration file.
int	getChildrenFactsCount() Returns the number of facts.
DTSContainer	getContainer() Access to the surrounding DTSContainer of this Mapper instance.
java.lang.String[]	getDtsURLs() Gets the dts urls.
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.
void	save(DTSLoadingBarInterface bar) 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 setUriOfConfigFile(URI). this method rebuilds the entire configuration file from the object model.
static void	save(MapperFileSaveInterface mapperFileSave, DTSLoadingBarInterface bar) Save the Mapper configuration file to disk using the file name assigned with a call to setUriOfConfigFile(URI). this method rebuilds the entire configuration file from the object model.
void	setUriOfConfigFile(java.net.URI newURI) Changes or sets this URI new config file.

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

addContext, addContext, addFact, addFactAt, addMapperId, addSection, addSource, addUnit, addUnit, addWarning, checkDuplicates, createEmptyMapperDoc, delContext, delFact, delSection, delUnit, getAllFactsForElement, getAllMapIdentifiersForElement, getCompany, getContextById, getContexts, getContextsKeys, getFactFromMapIdentifier, getKeyForSource, getMapIdentifierForElement, getMapperDoc, getNewMapIdentifier, getScheme, getSectionForKey, getSections, getSourceForKey, getSourceKeys, getUnitById, getUnitForKey, getUnitKeys, setCompany, setMapperDoc, setScheme

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

getCompany, getContextById, getContexts, getContextsKeys, getMapperDoc, getScheme, getSections, getSourceForKey, getSourceKeys, getUnitForKey, getUnitKeys

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(Object[]) 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

setUriOfConfigFile

public void setUriOfConfigFile(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(DTSLoadingBarInterface bar)
          throws XBRLSerializationException,
                 MapConfigurationFileException

Stores the content of this configuration file on disk using the uriOfConfigFile. This method produces output to the DTSLoadingBarInterface received in the parameter

Parameters:

bar - DTSLoadingBarInterface to produce messages and progress information

Throws:

XBRLSerializationException - the XBRL serialization exception

MapConfigurationFileException - the map configuration file exception

save

public void save()
          throws XBRLSerializationException,
                 MapConfigurationFileException

Stores the content of this configuration file on disk using the uriOfConfigFile.

Throws:

XBRLSerializationException - the XBRL serialization exception

MapConfigurationFileException - the map configuration file 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 setUriOfConfigFile(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

save

public static void save(MapperFileSaveInterface mapperFileSave,
                        DTSLoadingBarInterface bar)
                 throws XBRLSerializationException

Save the Mapper configuration file to disk using the file name assigned with a call to setUriOfConfigFile(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 class instance implementing MapperFileSaveInterface interface

bar - the DTSLoadingBarInterface instance to report progress and messages

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,
                                     XBRLValidationReport mapReport)
                              throws MapException

Generates a new instance document obtaining data from data sources and using the information in the configuration file.

If mapReport not is null, at the end it will contain all the problems encountered during the import. If mapReport is null, the process will stop when it encounters the first problem encountered during the import.

The new instance document is returned

Parameters:

inputs - input parameters to the XBRLDataSources

mapReport - the optional mapper report

Returns:

XBRLInstance

Throws:

MapException - the map exception

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,
                                     XBRLValidationReport mapReport)
                              throws MapException

Generates a new instance document obtaining data from data sources and using the information in the configuration file.

If mapReport not is null, at the end it will contain all the problems encountered during the import. If mapReport is null, the process will stop when it encounters the first problem encountered during the import.

The new instance document is returned

Parameters:

inputs - input parameters to the XBRLDataSources

bar - instance of DTSLoadingBarInterface or null if not required

mapReport - the optional mapper report

Returns:

XBRLInstance

Throws:

MapException - the map exception

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 urls.

Specified by:

getDtsURLs in interface MapperFileSaveInterface

Returns:

the dtsURLs

getChildrenFacts

public java.util.Iterator<MapperFact> getChildrenFacts()

Description copied from interface: MapperFileSaveInterface

Access to facts on the configuration file.

Specified by:

getChildrenFacts in interface MapperFileSaveInterface

Returns:

iterator on Fact instances

getChildrenFactsCount

public int getChildrenFactsCount()

Description copied from interface: MapperFileSaveInterface

Returns the number of facts.

Specified by:

getChildrenFactsCount in interface MapperFileSaveInterface

Returns:

the children facts count

clear

public void clear()
           throws java.lang.Throwable

Overrides:

clear in class MapperBase

Throws:

java.lang.Throwable