com.ihr.xbrl.mapper
Class Mapper

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

All Implemented Interfaces:

HasFacts, MapperFileSaveInterface

public class Mapper
extends java.lang.Object
implements HasFacts, MapperFileSaveInterface

This is the main class responsible of the overall process

Author:

Ignacio

Nested Class Summary

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

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

java.lang.String	addContext(MapperContext newContext)
void	addFact(Fact newFact) Adds a new Fact to the end of the Facts container.
void	addFactAt(Fact newFact, int pos) Adds a new Fact at the position indicated by pos.
void	addSection(Section section) This is called internally when a new Fact is added and the fact contains a section that is not on this file.
java.lang.String	addSource(XBRLDataSource ds)
java.lang.String	addUnit(XBRLUnit newUnit)
java.util.Vector<java.util.Vector<java.lang.String>>	checkDuplicates() Verifies the content of the mapper file and explore possible duplicate mappings (same concept for the same context and unit mapped more than once) If this happens the mapper has to make an election during the instance document generation time.
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.
void	delFact(Fact fact) Removes a fact from the container
void	delSection(Section section)
XBRLInstance	generateInstance(java.lang.Object[] inputs) Generates a new instance document obtaining data from data sources and using the information in the configuration file.
java.util.Vector<Fact>	getAllFactsForElement(XMLElementDefinition definition) Return all facts associated with this element definition
java.util.Vector<java.lang.String>	getAllMapIdentifiersForElement(XMLElementDefinition definition) Return all map identifiers associated with this element definition
java.util.Iterator<Fact>	getChildrenFacts() Access to an iterator over the children facts of this object
java.lang.String	getCompany() Access to the generic string that corresponds with the company
DTSContainer	getContainer() Access to the surrounding DTSContainer of this Mapper instance.
MapperContext	getContextById(java.lang.String key) Access to a MapperContext instance using the context ID which is a key for all the MapperContexts that exist on this Mapper
java.util.Collection<MapperContext>	getContexts() Returns a collection of MapperContext objects that will be saved to this new file.
java.util.Iterator<java.lang.String>	getContextsKeys() Returns an iterator over all context keys
java.lang.String[]	getDtsURLs() Access to all URLs that will be part of the DTS file section Note, all strings shall be valid converted to URIs to avoid errors.
Fact	getFactFromMapIdentifier(java.lang.String mapIdentifier) Returns the Fact associated with the mapIdentifier or null if the mapIdentifier is not associated with any Fact
java.lang.String	getKeyForSource(XBRLDataSource source) Returns the key used for this XBRLDataSource.
java.lang.String	getMapIdentifierForElement(XMLElementDefinition definition) Return the first map identifier associated to this element definition.
java.lang.String	getNewMapIdentifier(XMLElementDefinition element) Generates a new identifier for the element used as a parameter.
HasFacts	getParent() Access to the parent element of a Fact.
java.lang.String	getScheme() Access to the generic scheme string for the mapper configuration file Note, as this is a String, this may not be a valid URI.
Section	getSectionForKey(java.lang.String key)
java.util.Set<java.lang.String>	getSectionKeys()
java.util.Collection<Section>	getSections() Access to the collection of sections
XBRLDataSource	getSourceForKey(java.lang.String key) Returns the XBRLDataSource object associated with the specified key
java.util.Set<java.lang.String>	getSourceKeys() Returns the set of keys for data sources for this mapper
XBRLUnit	getUnitForKey(java.lang.String key) Returns the XBRLUnit object associated with the specified key
java.util.Set<java.lang.String>	getUnitKeys() Returns the set of keys for units for this mapper
java.net.URI	getUriOfConfigFile() Access to the file name associated with the mapper configuration file
MapVersion	getVersion()
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	registerFact(Fact fact) Registers a new fact has been added to the container.
void	save() Stores the content of this configuration file on disk using the uriOfConfigFile
static void	save(MapperFileSaveInterface mapperFileSave)
void	setURI(java.net.URI newURI) Changes or sets this URI new config file
void	unregisterFact(Fact fact) Same as HasFacts.registerFact(Fact) but in this case for removing the information stored

Methods inherited from class java.lang.Object

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

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 -

bar - DTSLoadingBarInterface

Throws:

MapConfigurationFileException

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 -

bar - DTSLoadingBarInterface

dtsProperties - properties for the dts configuration file

Throws:

MapConfigurationFileException

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

MapConfigurationFileException

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

addUnit

public java.lang.String addUnit(XBRLUnit newUnit)

Parameters:

newUnit -

addContext

public java.lang.String addContext(MapperContext newContext)

Parameters:

newContext -

getContextById

public MapperContext getContextById(java.lang.String key)

Access to a MapperContext instance using the context ID which is a key for all the MapperContexts that exist on this Mapper

Specified by:

getContextById in interface MapperFileSaveInterface

Parameters:

key - string

Returns:

MapperContext instance or null if none found

getContextsKeys

public java.util.Iterator<java.lang.String> getContextsKeys()

Returns an iterator over all context keys

Specified by:

getContextsKeys in interface MapperFileSaveInterface

Returns:

Iterator<String>

addSource

public java.lang.String addSource(XBRLDataSource ds)

Parameters:

ds -

Returns:

the new source key

getNewMapIdentifier

public java.lang.String getNewMapIdentifier(XMLElementDefinition element)

Generates a new identifier for the element used as a parameter. This operation is not thread safe. The returned value may be duplicate if multiple calls to this method are made without a method to add the new generated Fact

Parameters:

element -

Returns:

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

save

public static void save(MapperFileSaveInterface mapperFileSave)
                 throws XBRLSerializationException

Throws:

XBRLSerializationException

getSourceKeys

public java.util.Set<java.lang.String> getSourceKeys()

Returns the set of keys for data sources for this mapper

Specified by:

getSourceKeys in interface MapperFileSaveInterface

Returns:

Set<String> with all data source keys

getSourceForKey

public XBRLDataSource getSourceForKey(java.lang.String key)

Returns the XBRLDataSource object associated with the specified key

Specified by:

getSourceForKey in interface MapperFileSaveInterface

Parameters:

key - string

Returns:

XBRLDataSource

getUnitKeys

public java.util.Set<java.lang.String> getUnitKeys()

Returns the set of keys for units for this mapper

Specified by:

getUnitKeys in interface MapperFileSaveInterface

Returns:

Set<String> with all unit keys

Since:

2.6.11

getUnitForKey

public XBRLUnit getUnitForKey(java.lang.String key)

Returns the XBRLUnit object associated with the specified key

Specified by:

getUnitForKey in interface MapperFileSaveInterface

Parameters:

key - string

Returns:

XBRLUnit

Since:

2.6.11

getKeyForSource

public java.lang.String getKeyForSource(XBRLDataSource source)

Returns the key used for this XBRLDataSource. This is not efficient because sources are indexed by ID but this is not a problem because only GUIs are interested on this function and there will presumably be quite a small number of sources.

This method returns null if the source is not found.

Parameters:

source - XBRLDataSource

Returns:

String

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>

checkDuplicates

public java.util.Vector<java.util.Vector<java.lang.String>> checkDuplicates()

Verifies the content of the mapper file and explore possible duplicate mappings (same concept for the same context and unit mapped more than once) If this happens the mapper has to make an election during the instance document generation time.

If two (or more) facts are mapped to income data one of the following may occurs:

• The user may want to force duplicates to be processed independently, possibly generating duplicate facts in the output instance
• The user may be interested in grouping the duplicates in a "sequence reduction" processing unit. In this case, the output of a "sequence reduction processing unit" will always be the minimum number of non duplicate facts.

Returns:

a Vector of Vector of Strings. The string matches a fact identifier. The most internal nested Vector contains the all fact identifiers that belongs to a duplicate group. The most external Vector is a Vector of the groups of identifiers.

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

getMapIdentifierForElement

public java.lang.String getMapIdentifierForElement(XMLElementDefinition definition)

Return the first map identifier associated to this element definition.

Parameters:

definition - XMLElementDefinition

Returns:

String or null if not found

getAllMapIdentifiersForElement

public java.util.Vector<java.lang.String> getAllMapIdentifiersForElement(XMLElementDefinition definition)

Return all map identifiers associated with this element definition

Parameters:

definition - XMLElementDefinition

Returns:

Vector<String>

getAllFactsForElement

public java.util.Vector<Fact> getAllFactsForElement(XMLElementDefinition definition)

Return all facts associated with this element definition

Parameters:

definition - XMLElementDefinition

Returns:

Vector<Fact>

getFactFromMapIdentifier

public Fact getFactFromMapIdentifier(java.lang.String mapIdentifier)

Returns the Fact associated with the mapIdentifier or null if the mapIdentifier is not associated with any Fact

Parameters:

mapIdentifier - string, key unique for each mapIdentifier

Returns:

the Fact object associated with this key

getChildrenFacts

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

Description copied from interface: HasFacts

Access to an iterator over the children facts of this object

Specified by:

getChildrenFacts in interface HasFacts

Specified by:

getChildrenFacts in interface MapperFileSaveInterface

Returns:

Iterator over children facts

getScheme

public java.lang.String getScheme()

Description copied from interface: MapperFileSaveInterface

Access to the generic scheme string for the mapper configuration file

Note, as this is a String, this may not be a valid URI.

Specified by:

getScheme in interface MapperFileSaveInterface

Returns:

String

getCompany

public java.lang.String getCompany()

Description copied from interface: MapperFileSaveInterface

Access to the generic string that corresponds with the company

Specified by:

getCompany in interface MapperFileSaveInterface

Returns:

String

getParent

public HasFacts getParent()

Description copied from interface: HasFacts

Access to the parent element of a Fact. This is null only when the current HasFacts is a template document

Specified by:

getParent in interface HasFacts

Returns:

Fact that represents a tupleFact or templateDocument. Null when current HasFacts object is the template.

addFact

public void addFact(Fact newFact)

Description copied from interface: HasFacts

Adds a new Fact to the end of the Facts container.

This method does not updates the taxonomy URLs.

Specified by:

addFact in interface HasFacts

Parameters:

newFact - the new fact to be added

addFactAt

public void addFactAt(Fact newFact,
                      int pos)

Description copied from interface: HasFacts

Adds a new Fact at the position indicated by pos.

Specified by:

addFactAt in interface HasFacts

Parameters:

newFact - Fact to be added

pos - integer. Zero based

registerFact

public void registerFact(Fact fact)

Description copied from interface: HasFacts

Registers a new fact has been added to the container. This method updates the Hashtables in the instance template and passes UP to its parent the registration of facts for tuples. This method is called internally by the API and should not be called manually

Specified by:

registerFact in interface HasFacts

addSection

public void addSection(Section section)

This is called internally when a new Fact is added and the fact contains a section that is not on this file.

It is also possible calling this method for adding sections in advance

Note: if the section already exists, the old section is replaced by the new section

Parameters:

section - Section to be added

delFact

public void delFact(Fact fact)

Description copied from interface: HasFacts

Removes a fact from the container

Specified by:

delFact in interface HasFacts

Parameters:

fact - Fact to remove

delSection

public void delSection(Section section)

unregisterFact

public void unregisterFact(Fact fact)

Description copied from interface: HasFacts

Same as HasFacts.registerFact(Fact) but in this case for removing the information stored

Specified by:

unregisterFact in interface HasFacts

getVersion

public MapVersion getVersion()

Returns:

the version

getContexts

public java.util.Collection<MapperContext> getContexts()

Description copied from interface: MapperFileSaveInterface

Returns a collection of MapperContext objects that will be saved to this new file.

Specified by:

getContexts in interface MapperFileSaveInterface

Returns:

getUriOfConfigFile

public java.net.URI getUriOfConfigFile()

Description copied from interface: MapperFileSaveInterface

Access to the file name associated with the mapper configuration file

Specified by:

getUriOfConfigFile in interface MapperFileSaveInterface

Returns:

the uriOfConfigFile

getDtsURLs

public java.lang.String[] getDtsURLs()

Description copied from interface: MapperFileSaveInterface

Access to all URLs that will be part of the DTS file section

Note, all strings shall be valid converted to URIs to avoid errors.

Specified by:

getDtsURLs in interface MapperFileSaveInterface

Returns:

the dtsURLs

getSections

public java.util.Collection<Section> getSections()

Description copied from interface: MapperFileSaveInterface

Access to the collection of sections

Specified by:

getSections in interface MapperFileSaveInterface

Returns:

Collection of sections

getSectionKeys

public java.util.Set<java.lang.String> getSectionKeys()

getSectionForKey

public Section getSectionForKey(java.lang.String key)