com.ihr.xbrl.mapper.source

Class CSVDataSource

java.lang.Object

com.ihr.xbrl.mapper.source.CSVDataSource

All Implemented Interfaces:

HasSomethingToSay, HasAddMap, HasDataFile, MapeableDataSource, XBRLDataSource

public class CSVDataSource
extends java.lang.Object
implements MapeableDataSource, HasDataFile, HasSomethingToSay

Comma separated values file data source.

Author:

Ignacio

Constructor Summary

Constructors

Constructor and Description
CSVDataSource()

Method Summary

Modifier and Type	Method and Description
void	addMap(java.lang.String mapIdentifier, java.lang.String columName, java.util.Properties props) This method must be implemented by XBRLDataSource interfaces that are capable to read information collected during the processing of representable forms and generate a sample conversion file for the surrounding data format .
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.util.Collection<ApiHistoricalEventImpl>	getApiMessages() This is the method that must be implemented by classes that provides historical information.
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.String	getDataFile() Access to the name of the data file.
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) Every footnote MUST have an xml:lang attribute.
XBRLNumber.ExactitudeMode	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.
HistoricalEventInterface	getHistoricalMessage() This is the method that must be implemented by classes that provides historical information.
java.util.Map<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, MapperFact 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.
java.lang.String	getTooltip() This is the method that must be implemented by classes that provides the tooltip historical information.
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(MapperFileSaveInterface mapperFileSave) Save the content of the configuration file to disk.
void	setConfigFile(java.net.URI configFile) Sets the configuration file for this XBRLDataSource.
void	setDataFile(java.lang.String dataFile) Sets the data name file for this XBRLDataSource.
void	setFormat(XBRLNumber.ExactitudeMode 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(MapperSection 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 - this is the XBRLInstance document.

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.

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

Every footnote 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. The call is made after the footnote resource is created.

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 XBRLNumber.ExactitudeMode 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(XBRLNumber.ExactitudeMode 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

addMap

public void addMap(java.lang.String mapIdentifier,
                   java.lang.String columName,
                   java.util.Properties props)

Description copied from interface: HasAddMap

This method must be implemented by XBRLDataSource interfaces that are capable to read information collected during the processing of representable forms and generate a sample conversion file for the surrounding data format .

Specified by:

addMap in interface HasAddMap

Parameters:

mapIdentifier - the identifier

columName - the cell

props - the props

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,
                             MapperFact 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 XBRLInstance 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(MapperFileSaveInterface mapperFileSave)
          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

Parameters:

mapperFileSave - optional parameter, if the configuration file content is empty, and the mapperFileSave parameter is not null, the driver can use the parameter to prepare a sample configuration file. Note not all drivers can do this, for example the Excel data source driver cannot, but the SQL Data source can prepare a kind of virtual table from which the data would eventually come

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.Map<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(MapperSection 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

getHistoricalMessage

public HistoricalEventInterface getHistoricalMessage()

Description copied from interface: HasSomethingToSay

This is the method that must be implemented by classes that provides historical information.

Specified by:

getHistoricalMessage in interface HasSomethingToSay

Returns:

HistoricalEventInterface instance so it can be added to the fact history

getDataFile

public java.lang.String getDataFile()

Description copied from interface: HasDataFile

Access to the name of the data file.

Specified by:

getDataFile in interface HasDataFile

Returns:

String of the data file or null if not needed or not set

setDataFile

public void setDataFile(java.lang.String dataFile)

Description copied from interface: HasDataFile

Sets the data name file for this XBRLDataSource.

Specified by:

setDataFile in interface HasDataFile

Parameters:

dataFile - the new data name file

getTooltip

public java.lang.String getTooltip()

Description copied from interface: HasSomethingToSay

This is the method that must be implemented by classes that provides the tooltip historical information.

Specified by:

getTooltip in interface HasSomethingToSay

Returns:

the tooltip

getApiMessages

public java.util.Collection<ApiHistoricalEventImpl> getApiMessages()

Description copied from interface: HasSomethingToSay

This is the method that must be implemented by classes that provides historical information.

Specified by:

getApiMessages in interface HasSomethingToSay

Returns:

HistoricalEventInterface instance so it can be added to the fact history