com.ihr.xbrl.mapper.source

## Class CSVDataSource

- java.lang.Object
- - com.ihr.xbrl.mapper.source.CSVDataSource

- All Implemented Interfaces:
    XBRLDataSource

      public class CSVDataSource
      extends java.lang.Object
      implements XBRLDataSource

  Comma separated values file data source.
  Author:
    Ignacio

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `CSVDataSource()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addMapEntry(java.lang.String columName, java.lang.String mapIdentifier)` Adds a new map entry from columnName to mapIdentifier.
    `void` | `createConfigFileContent()` This function is used by the GUI during the generation of a new mapper.
    `void` | `endOfDocument(XBRLInstance instance)` Called by the MapEngine when a new instance is finished Can be used to close connections to data sources.
    `void` | `endOfFact(java.lang.String mapIdenfifier, javax.xml.namespace.QName factName)` Called by the MapEngine when a new fact is finalized returns nothing.
    `java.net.URI` | `getConfigFile()` Access to the name of the configuration file.
    `XBRLContext` | `getContext(java.lang.String mapIdentifier, int index, XBRLContext context)` Each data item has mapIdentifier string each used concept in the taxonomy has at least one mapIdentifier returns the XBRLContext to be used for the fact item.
    `java.lang.Object` | `getFootnote(java.lang.String mapIdentifier, int index, XBRLFact fact)` After a fact is produced the data source is asked for a footnote to be added to the instance document by doing a call to this method.
    `java.lang.String` | `getFootnoteLang(java.lang.String mapIdentifier, int index, XBRLFact fact, java.lang.Object footnoteContent)` After a footnote resource is create it MUST have an xml:lang attribute.
    `int` | `getFormat(java.lang.String mapIdentifier, int index, XBRLContext context, XBRLUnit localUnit)` Ask the driver for the preferred serialization for the numeric data.
    `java.lang.String` | `getFormatValue(java.lang.String mapIdentifier, int index, XBRLContext context, XBRLUnit localUnit)` Returns the value (as string) for the data format.
    `java.util.Hashtable<java.lang.String,java.lang.String>` | `getMap()` Access to the map information.
    `java.lang.Object[]` | `getMapIdentifierReferences(java.lang.String mapIdentifier)` This method is used to automatically generate loader files from mapper files.
    `int` | `getNumberOfValues(java.lang.String mapIdentifier, Fact fact)` Each data item has mapIdentifier string, each used concept in the taxonomy has at least one mapIdentifier This method returns the number of facts in the source that corresponds to the mapIdentifier string.
    `java.lang.Object` | `getSampleData(java.lang.Object data)` This method is used by the mapper editor during test cycles of the mapper The implemented class should use the incoming data to produce an object that the mapper can use later to produce an instance document .
    `java.lang.String` | `getSourceReference(java.lang.String mapIdentifier, int index, XBRLContext localContext, net.sf.saxon.type.SimpleType theType)` Returns a string that describes the source of data for a specific mapIdentifier, index, localContext and data type This method is used in order to build an error message that takes into consideration where the data comes from so the user can better track the path the data is following inside the tools.
    `XBRLUnit` | `getUnit(java.lang.String mapIdentifier, int index, XBRLContext localContext, XBRLUnit unit)` Each time a numeric concept is created this function is called to request or change the required unit.
    `net.sf.saxon.value.AtomicValue` | `getValue(java.lang.String mapIdentifier, int index, XBRLContext context, net.sf.saxon.type.SimpleType type)` Each data item has mapIdentifier string each used concept in the taxonomy has at least one mapIdentifier returns the Value to be sent to the fact item. null is allowed and will be considered as no input data available
    `void` | `init()` Called by the mapping engine once the object is created.
    `boolean` | `isConfigfileRequired()` Returns true if the configuration file is required for this XBRLDataSource.
    `boolean` | `isInputFileRequired()` Returns true if this driver requires an input file.
    `boolean` | `isNil(java.lang.String mapIdentifier, int index, XMLElementDefinition concept)` Return true if the concept content is xsi:nil so there will be no request for a value.
    `boolean` | `isTupleSourceRequired()` Returns a boolean value indicating if the source format has a meaning to indicate the number of occurrences of a tuple.
    `void` | `resetMapEntries()` Clears the content of the map entries.
    `void` | `save()` Save the content of the configuration file to disk.
    `void` | `setConfigFile(java.net.URI configFile)` Sets the configuration file for this XBRLDataSource.
    `void` | `setFormat(int newFormat)` Changes the format of this CSVDataSource.
    `void` | `setFormatValue(java.lang.String newFormatValue)` Changes the format value of this CSVDataSource.
    `void` | `startOfDocument(XBRLInstance instance, java.lang.Object[] inputs, DTSLoadingBarInterface bar)` Called by the MapEngine when a new instance that requires this data source is going to be created.
    `void` | `startOfFact(java.lang.String mapIdentifier, javax.xml.namespace.QName factName)` Called by the MapEngine when a new fact is about to be started Return nothing.
    `boolean` | `verifyRule(Section section)` Checks the current driver for a rule for section passed in in the parameter.

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

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

    - ### Methods inherited from interface com.ihr.xbrl.mapper.source.XBRLDataSource

      `equals, hashCode`

- - ### Constructor Detail

    - #### CSVDataSource

          public CSVDataSource()

  - ### Method Detail

    - #### endOfDocument

          public void endOfDocument(XBRLInstance instance)

      Description copied from interface: `XBRLDataSource`
      Called by the MapEngine when a new instance is finished Can be used to close connections to data sources.
      Specified by:
        `endOfDocument` in interface `XBRLDataSource`
      Parameters:
        `instance` - XBRLInstance

    - #### endOfFact

          public void endOfFact(java.lang.String mapIdenfifier,
                       javax.xml.namespace.QName factName)

      Description copied from interface: `XBRLDataSource`
      Called by the MapEngine when a new fact is finalized returns nothing. It is used to inform the "other side" and can be used to free-up resources.
      Specified by:
        `endOfFact` in interface `XBRLDataSource`
      Parameters:
        `mapIdenfifier` - the map identifier
        `factName` - the fact name

    - #### getConfigFile

          public java.net.URI getConfigFile()

      Description copied from interface: `XBRLDataSource`
      Access to the name of the configuration file.
      Specified by:
        `getConfigFile` in interface `XBRLDataSource`
      Returns:
        URI of the configuration file or null if not needed or not set

    - #### getContext

          public XBRLContext getContext(java.lang.String mapIdentifier,
                               int index,
                               XBRLContext context)

      Description copied from interface: `XBRLDataSource`
      Each data item has mapIdentifier string each used concept in the taxonomy has at least one mapIdentifier returns the XBRLContext to be used for the fact item. Or the proposed context if no modifications are required. MUST not return null.
      Specified by:
        `getContext` in interface `XBRLDataSource`
      Parameters:
        `mapIdentifier` - String
        `index` - int
        `context` - XBRLContext the context proposed by the mapping engine. If the context is modified it will be modified for all concepts using this context. So if the context requires modifications for a specified fact it would be better to clone the context before modifications are performed.
      Returns:
        net.sf.saxon.Value

    - #### getFootnote

          public java.lang.Object getFootnote(java.lang.String mapIdentifier,
                                     int index,
                                     XBRLFact fact)

      Description copied from interface: `XBRLDataSource`
      After a fact is produced the data source is asked for a footnote to be added to the instance document by doing a call to this method. If this method returns null then the concept has no text in a footnote. If this method returns a java.lang.String then the string text will be added as a footnote to the instance document. If this method returns a org.jdom.Content
      Specified by:
        `getFootnote` in interface `XBRLDataSource`
      Parameters:
        `mapIdentifier` - String
        `index` - int
        `fact` - XBRLFactItem
      Returns:
        Object , null, String or Content

    - #### getFootnoteLang

          public java.lang.String getFootnoteLang(java.lang.String mapIdentifier,
                                         int index,
                                         XBRLFact fact,
                                         java.lang.Object footnoteContent)

      Description copied from interface: `XBRLDataSource`
      After a footnote resource is create it MUST have an xml:lang attribute. This function is called by the mapping engine in order to obtain the value of the xml:lang attribute for a particular footnote
      Specified by:
        `getFootnoteLang` in interface `XBRLDataSource`
      Parameters:
        `mapIdentifier` - the map identifier
        `index` - the index
        `fact` - the fact
        `footnoteContent` - the footnote content
      Returns:
        String

    - #### getFormat

          public int getFormat(java.lang.String mapIdentifier,
                      int index,
                      XBRLContext context,
                      XBRLUnit localUnit)

      Description copied from interface: `XBRLDataSource`
      Ask the driver for the preferred serialization for the numeric data. One of XBRLNumericValue.DECIMALS or XBRLNumericValue.PRECISION constants must be returned
      Specified by:
        `getFormat` in interface `XBRLDataSource`
      Parameters:
        `mapIdentifier` - the map identifier
        `index` - the index
        `context` - the context
        `localUnit` - the local unit
      Returns:
        integer

    - #### getFormatValue

          public java.lang.String getFormatValue(java.lang.String mapIdentifier,
                                        int index,
                                        XBRLContext context,
                                        XBRLUnit localUnit)

      Description copied from interface: `XBRLDataSource`
      Returns the value (as string) for the data format. "INF" means infinite. integers (positive and negative) can be set for decimals="-6" (millions of the specified unit etc).
      Specified by:
        `getFormatValue` in interface `XBRLDataSource`
      Parameters:
        `mapIdentifier` - the map identifier
        `index` - the index
        `context` - the context
        `localUnit` - the local unit
      Returns:
        String

    - #### setFormat

          public void setFormat(int newFormat)

      Changes the format of this CSVDataSource. This method is mainly used by the dialog that edits this CSVConfiguration file
      Parameters:
        `newFormat` - integer constant XBRLNumericValue.DECIMALS or XBRLNumericValue.PRECISION

    - #### setFormatValue

          public void setFormatValue(java.lang.String newFormatValue)

      Changes the format value of this CSVDataSource. This method is mainly used by the dialog that edits this CSVConfiguration file
      Parameters:
        `newFormatValue` - String representation of the new value

    - #### addMapEntry

          public void addMapEntry(java.lang.String columName,
                         java.lang.String mapIdentifier)

      Adds a new map entry from columnName to mapIdentifier. Used by the GUI configuring the CSVDataSource
      Parameters:
        `columName` - the colum name
        `mapIdentifier` - the map identifier

    - #### resetMapEntries

          public void resetMapEntries()

      Clears the content of the map entries. Used by the GUI updating the configuration

    - #### getNumberOfValues

          public int getNumberOfValues(java.lang.String mapIdentifier,
                              Fact fact)

      Description copied from interface: `XBRLDataSource`
      Each data item has mapIdentifier string, each used concept in the taxonomy has at least one mapIdentifier This method returns the number of facts in the source that corresponds to the mapIdentifier string. Normally this is 1 but there may be cases in which more are returned by the source. Facts inside tuples often returns more than one. Facts with dimensions may be mappend using different map identifiers for each dimension combination.
      Specified by:
        `getNumberOfValues` in interface `XBRLDataSource`
      Parameters:
        `mapIdentifier` - the map identifier
        `fact` - the fact
      Returns:
        int

    - #### getUnit

          public XBRLUnit getUnit(java.lang.String mapIdentifier,
                         int index,
                         XBRLContext localContext,
                         XBRLUnit unit)

      Description copied from interface: `XBRLDataSource`
      Each time a numeric concept is created this function is called to request or change the required unit. If no change is required then unit (the incoming parameter) must be returned
      Specified by:
        `getUnit` in interface `XBRLDataSource`
      Parameters:
        `mapIdentifier` - String code
        `index` - int indicating which value we are working on
        `localContext` - the context for the new data
        `unit` - the proposed unit. Can be changed
      Returns:
        XBRLUnit the original unit or a new unit to use

    - #### getValue

          public net.sf.saxon.value.AtomicValue getValue(java.lang.String mapIdentifier,
                                                int index,
                                                XBRLContext context,
                                                net.sf.saxon.type.SimpleType type)
                                                  throws MapException

      Description copied from interface: `XBRLDataSource`
      Each data item has mapIdentifier string each used concept in the taxonomy has at least one mapIdentifier returns the Value to be sent to the fact item. null is allowed and will be considered as no input data available
      Specified by:
        `getValue` in interface `XBRLDataSource`
      Parameters:
        `mapIdentifier` - String
        `index` - int
        `context` - XBRLContext the XBRL Context for the fact being reported. The context should not be modified here.
        `type` - This is that target schema type obtained from the element definition
      Returns:
        net.sf.saxon.Value
      Throws:
        `MapException` - the map exception

    - #### init

          public void init()
                    throws MapConfigurationFileException

      Description copied from interface: `XBRLDataSource`
      Called by the mapping engine once the object is created. Allows the driver to read the configuration file for the driver.
      Specified by:
        `init` in interface `XBRLDataSource`
      Throws:
        `MapConfigurationFileException` - the map configuration file exception

    - #### isNil

          public boolean isNil(java.lang.String mapIdentifier,
                      int index,
                      XMLElementDefinition concept)

      Description copied from interface: `XBRLDataSource`
      Return true if the concept content is xsi:nil so there will be no request for a value.
      Specified by:
        `isNil` in interface `XBRLDataSource`
      Parameters:
        `mapIdentifier` - the map identifier
        `index` - the index
        `concept` - the concept
      Returns:
        boolean

    - #### setConfigFile

          public void setConfigFile(java.net.URI configFile)

      Description copied from interface: `XBRLDataSource`
      Sets the configuration file for this XBRLDataSource. If the driver requires no configuration file the argument configFile is null
      Specified by:
        `setConfigFile` in interface `XBRLDataSource`
      Parameters:
        `configFile` - the new config file

    - #### startOfDocument

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

      Description copied from interface: `XBRLDataSource`
      Called by the MapEngine when a new instance that requires this data source is going to be created. Can be used to open connections to data sources. Be careful when processing the inputs because the same mapper could use more than one driver and inputs are shared across all the drivers. Don't assume there will always be just one driver providing data to the mapper.
      Specified by:
        `startOfDocument` in interface `XBRLDataSource`
      Parameters:
        `instance` - this is the instance document.
        `inputs` - Input parameters, they are different objects for each driver.
        `bar` - this is an optional parameter, if not null, the driver can send messages to inform about the initialization process
      Throws:
        `MapException` - the map exception

    - #### startOfFact

          public void startOfFact(java.lang.String mapIdentifier,
                         javax.xml.namespace.QName factName)

      Description copied from interface: `XBRLDataSource`
      Called by the MapEngine when a new fact is about to be started Return nothing. It is used to inform the "other side" and can be used to attach resources
      Specified by:
        `startOfFact` in interface `XBRLDataSource`
      Parameters:
        `mapIdentifier` - String
        `factName` - QName

    - #### getSampleData

          public java.lang.Object getSampleData(java.lang.Object data)
                                         throws MapException

      Description copied from interface: `XBRLDataSource`
      This method is used by the mapper editor during test cycles of the mapper The implemented class should use the incoming data to produce an object that the mapper can use later to produce an instance document .
      Specified by:
        `getSampleData` in interface `XBRLDataSource`
      Parameters:
        `data` - object
      Returns:
        another object
      Throws:
        `MapException` - in the case the input object cannot be used

    - #### createConfigFileContent

          public void createConfigFileContent()

      Description copied from interface: `XBRLDataSource`
      This function is used by the GUI during the generation of a new mapper. Generates a sample configuration file that can be loaded by the XBRLDataSource without generating java exceptions.
      Specified by:
        `createConfigFileContent` in interface `XBRLDataSource`

    - #### isConfigfileRequired

          public boolean isConfigfileRequired()

      Description copied from interface: `XBRLDataSource`
      Returns true if the configuration file is required for this XBRLDataSource. Returns false if it is optional or not required at all.
      Specified by:
        `isConfigfileRequired` in interface `XBRLDataSource`
      Returns:
        boolean value

    - #### save

          public void save()
                    throws MapException

      Description copied from interface: `XBRLDataSource`
      Save the content of the configuration file to disk. This method is called by the GUI when the mapper has changes in the configuration and the configuration requires to be serialized to disk
      Specified by:
        `save` in interface `XBRLDataSource`
      Throws:
        `MapException` - in the event of problems like IOException

    - #### isInputFileRequired

          public boolean isInputFileRequired()

      Description copied from interface: `XBRLDataSource`
      Returns true if this driver requires an input file. This function is used by the GUI in order to enable or disable the "Test Mapper" menu item depending on whether or not input files are required
      Specified by:
        `isInputFileRequired` in interface `XBRLDataSource`
      Returns:
        boolean

    - #### getMap

          public java.util.Hashtable<java.lang.String,java.lang.String> getMap()

      Access to the map information.

      This driver holds a map between mapIdentifiers and CSV column names. Map keys are CSV column names. Map values are mapIdentifiers.

      Returns:
        Hashtable<String,String>

    - #### isTupleSourceRequired

          public boolean isTupleSourceRequired()

      Description copied from interface: `XBRLDataSource`
      Returns a boolean value indicating if the source format has a meaning to indicate the number of occurrences of a tuple.

      This information is used during the algorithm for generating a template file automatically.

      Excel Data Source, for example, does not provides a meaning to indicate the number of occurrences of a tuple. The number of occurrences will be indicated in the instance document template itself. SQL Data Source, is on the other side. The SQL Driver and the source format may have information to provide the number of occurrences for a tuple.

      Note, once a template has been automatically generated. it is up to the team to change the generated template into something different if this is required by the project.

      Specified by:
        `isTupleSourceRequired` in interface `XBRLDataSource`
      Returns:
        boolean value.

    - #### getSourceReference

          public java.lang.String getSourceReference(java.lang.String mapIdentifier,
                                            int index,
                                            XBRLContext localContext,
                                            net.sf.saxon.type.SimpleType theType)

      Description copied from interface: `XBRLDataSource`
      Returns a string that describes the source of data for a specific mapIdentifier, index, localContext and data type

      This method is used in order to build an error message that takes into consideration where the data comes from so the user can better track the path the data is following inside the tools.

      Specified by:
        `getSourceReference` in interface `XBRLDataSource`
      Parameters:
        `mapIdentifier` - current map identifier
        `index` - current index for the map identifier
        `localContext` - XBRL context for the generated fact
        `theType` - data type as SimpleType
      Returns:
        String with target description

    - #### verifyRule

          public boolean verifyRule(Section section)

      Description copied from interface: `XBRLDataSource`
      Checks the current driver for a rule for section passed in in the parameter. If the rule is satisfied the return value shall be true, otherwise, the return value shall be false.

      This method is called only if the fact contains a sectionRef and the sectionRef contains a rule.

      The algorithm to determine the output value is driver dependant and there is no default value.

      If the return value is true, the fact will be included to the output instance and all files in the section will be added to the DTS. If the return value is false, the fact will be skipped.

      Specified by:
        `verifyRule` in interface `XBRLDataSource`
      Parameters:
        `section` - the section
      Returns:
        boolean value

    - #### getMapIdentifierReferences

          public java.lang.Object[] getMapIdentifierReferences(java.lang.String mapIdentifier)

      Description copied from interface: `XBRLDataSource`
      This method is used to automatically generate loader files from mapper files.
      Specified by:
        `getMapIdentifierReferences` in interface `XBRLDataSource`
      Parameters:
        `mapIdentifier` - the map identifier
      Returns:
        the map identifier references