com.rs.xbrl.instructions

Class TaxonomyBuilder

java.lang.Object

com.rs.xbrl.instructions.TaxonomyBuilder

public class TaxonomyBuilder
extends java.lang.Object

Generates an XBRL DTS executing all the instructions available in one excel sheet prepared specifically for this purpose. Read the documentation about the taxonomyBuilder in order to know more about the available instructions.

Process:

1. Create an instance of the TaxonomyBuilder using the Excel URI and the name of the sheet with the instructions.
2. Call generate()

The process will be logged to the logger. See log4j and initialize the logger property accordingly.

Author:

Ignacio

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	DTS_BUILDER_EXTENDED_LINKS_POLICY The property DTS_BUILDER_EXTENDED_LINKS_POLICY defines how the tool creates new extended links inside linkbase containers.
static java.lang.String	DTS_BUILDER_EXTENDED_LINKS_POLICY_CREATE_NEW This value of the Extended Links Policy indicates that a every instruction in the DTS Definition Language generates a new extended link within the parent container.
static java.lang.String	DTS_BUILDER_EXTENDED_LINKS_POLICY_REUSE_EXISTING This value of the Extended Links Policy indicates that a every instruction in the DTS Definition Language generates will try to reuse existing extended links already created in the parent container.
static java.lang.String	DTS_BUILDER_TARGET_OUT_OF_CURRENT_FILE_MESSAGE This property control what message level is assigned to the event that occurs when, during the creation of an arc, a resource referenced in the from or to (source or target of the relationship) is out of the file where the arc is created but the ID of the target resource exists on another file.
static java.lang.String	LOGGER_NAME This is the logger name where this Taxonomy Builder sends logs to.
static java.lang.String	PROPERTY_VALUE_ERROR Property value for error messages.
static java.lang.String	PROPERTY_VALUE_IGNORE Property value for ignore messages.
static java.lang.String	PROPERTY_VALUE_TRACE Property value for trace messages.
static java.lang.String	PROPERTY_VALUE_WARN Property value for warning messages.

Constructor Summary

Constructors

Constructor and Description
TaxonomyBuilder() Creates a new TaxonomyBuilder instance.
TaxonomyBuilder(java.net.URI excelURI, java.lang.String sheetInstructions) Creates a new TaxonomyBuilder instance.

Method Summary

Modifier and Type	Method and Description
static void	addToSchemaLocation(java.lang.String namespace, java.lang.String absoluteURL, GenerationContext gc) Adds the schema to schemaLocation attribute if it is not already there.
static java.util.Properties	createDefaultProperties() Creates the default properties.
void	generate() Generates the new DTS using default values for all properties.
void	generate(GenerationContext gc) Generates the new DTS using the properties indicated and the workbook form the GenerationContext. the instructions sheet will be taken from the constructor of this class
XBRLArcroleType	getArcroleType(GenerationContext gc, java.lang.String arcrole) Returns an arcrole type in the DTS from the arcrole type URI
XMLFragment	getConceptAtPoint(DTSContainer dts, ExcelSheetPoint conceptPrefixPoint) Search the DTS for a concept definition using the prefix and local name.
java.lang.String	getContentAsStringFromTextOrRef(ExcelSheetPoint sp, GenerationContext gc) Returns the content of the cell in the sp parameter as text, if that cell content is another cell reference, the reference is resolved to the final text and returned.
java.net.URI	getExcelURI() Gets the excel uri.
GenerationContext	getGenerationContext() Generates the new DTS using the properties indicated.
GenerationContext	getGenerationContext(java.util.Properties props) Generates the new DTS using the properties indicated.
org.apache.log4j.Logger	getLogger() Access to the logger on this class.
javax.xml.namespace.QName	getQName(java.lang.String token, GenerationContext gc, XBRLTaxonomy tx, XBRLLinkbase lb) Obtains a QName from the token string.
javax.xml.namespace.QName	getQNameAtPoint(GenerationContext gc, ExcelSheetPoint qnamePoint, boolean bIsConcept) Reads a concept reference as defined in the Taxonomy Builder documentation The cell pointed to by the qnamePoint parameter is the concept prefix.
javax.xml.namespace.QName	getQNameConcept(DTSContainer dts, java.lang.String conceptPrefix, java.lang.String conceptName) Returns the QName of a concept already defined in one of the taxonomies in the DTS.
static XBRLXSDTypeDefinition	getTypeDefinitionAtPoint(GenerationContext gc, ExcelSheetPoint typePoint) Gets the type definition at point.
static XMLFragment	getXMLFragment(java.lang.String keyToken, GenerationContext gc) Obtains an XMLFragment from the DTS using either the cache of Generic Labels or the loc({href}) function.
static void	main(java.lang.String[] args) The main method.
javax.xml.namespace.QName	putGlobalName(java.lang.String name, javax.xml.namespace.QName q, GenerationContext gc) Adds an entry to the global table of names to QNames.
XBRLAttribute[]	readAttributes(ExcelSheetPoint attSp, GenerationContext gc, boolean useContextTaxonomyNamespace, java.lang.String[] validNoNamespaceAtts) Obtain attributes for the new elements.
static void	registerInstructionsFactory(java.lang.String clazz) Instantiates and registers a new factory class for instructions.
void	setExcelURI(java.net.URI excelURI) Sets the excel uri.
void	setSheetInstructions(java.lang.String sheetInstructions) Sets the sheet instructions.
static void	usage() Usage.

Methods inherited from class java.lang.Object

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

Field Detail

DTS_BUILDER_EXTENDED_LINKS_POLICY

public static final java.lang.String DTS_BUILDER_EXTENDED_LINKS_POLICY

The property DTS_BUILDER_EXTENDED_LINKS_POLICY defines how the tool creates new extended links inside linkbase containers. Possible values for this property are:

"create-new": see DTS_BUILDER_EXTENDED_LINKS_POLICY_CREATE_NEW

"reuse-existing": see DTS_BUILDER_EXTENDED_LINKS_POLICY_REUSE_EXISTING (default)

See Also:

Constant Field Values

DTS_BUILDER_EXTENDED_LINKS_POLICY_CREATE_NEW

public static final java.lang.String DTS_BUILDER_EXTENDED_LINKS_POLICY_CREATE_NEW

This value of the Extended Links Policy indicates that a every instruction in the DTS Definition Language generates a new extended link within the parent container.

See Also:

Constant Field Values

DTS_BUILDER_EXTENDED_LINKS_POLICY_REUSE_EXISTING

public static final java.lang.String DTS_BUILDER_EXTENDED_LINKS_POLICY_REUSE_EXISTING

This value of the Extended Links Policy indicates that a every instruction in the DTS Definition Language generates will try to reuse existing extended links already created in the parent container. If no extended links exist a new one will be created. This is the default value for the Extended links policy.

See Also:

Constant Field Values

DTS_BUILDER_TARGET_OUT_OF_CURRENT_FILE_MESSAGE

public static final java.lang.String DTS_BUILDER_TARGET_OUT_OF_CURRENT_FILE_MESSAGE

This property control what message level is assigned to the event that occurs when, during the creation of an arc, a resource referenced in the from or to (source or target of the relationship) is out of the file where the arc is created but the ID of the target resource exists on another file. During the taxonomy generation this can be either a warning (property value is 'warn'), or nor reported at all (property value is 'ignore'). The default value is PROPERTY_VALUE_WARN.

See Also:

Constant Field Values

PROPERTY_VALUE_WARN

public static final java.lang.String PROPERTY_VALUE_WARN

Property value for warning messages.

See Also:

Constant Field Values

PROPERTY_VALUE_ERROR

public static final java.lang.String PROPERTY_VALUE_ERROR

Property value for error messages.

See Also:

Constant Field Values

PROPERTY_VALUE_IGNORE

public static final java.lang.String PROPERTY_VALUE_IGNORE

Property value for ignore messages.

See Also:

Constant Field Values

PROPERTY_VALUE_TRACE

public static final java.lang.String PROPERTY_VALUE_TRACE

Property value for trace messages.

See Also:

Constant Field Values

LOGGER_NAME

public static final java.lang.String LOGGER_NAME

This is the logger name where this Taxonomy Builder sends logs to. For historical reasons this is not the same as the class name. This may be changed in the future.

See Also:

Constant Field Values

Constructor Detail

TaxonomyBuilder

public TaxonomyBuilder(java.net.URI excelURI,
                       java.lang.String sheetInstructions)
                throws com.rs.lic.LicenseVerificationException

Creates a new TaxonomyBuilder instance. After the creation of the object, an invocation to the generate() method will execute the instructions in the sheet indicated in the sheetInstructions parameter.

Parameters:

excelURI - the excel uri

sheetInstructions - name of the sheet with instructions to execute

Throws:

com.rs.lic.LicenseVerificationException - if the user does not have rights to use this class or any problem with the license has occurred

TaxonomyBuilder

public TaxonomyBuilder()
                throws com.rs.lic.LicenseVerificationException

Creates a new TaxonomyBuilder instance. After the creation of the object, an invocation to the generate() method will execute the instructions in the sheet indicated in the sheetInstructions parameter.

Throws:

com.rs.lic.LicenseVerificationException - if the user does not have rights to use this class or any problem with the license has occurred

Method Detail

setExcelURI

public void setExcelURI(java.net.URI excelURI)

Sets the excel uri.

Parameters:

excelURI - the excelURI to set

getExcelURI

public java.net.URI getExcelURI()

Gets the excel uri.

Returns:

the excelURI

setSheetInstructions

public void setSheetInstructions(java.lang.String sheetInstructions)

Sets the sheet instructions.

Parameters:

sheetInstructions - the sheetInstructions to set

registerInstructionsFactory

public static void registerInstructionsFactory(java.lang.String clazz)
                                        throws XBRLInitializationException

Instantiates and registers a new factory class for instructions.

Parameters:

clazz - the clazz

Throws:

XBRLInitializationException - the XBRL initialization exception

main

public static void main(java.lang.String[] args)
                 throws java.lang.Exception

The main method.

Parameters:

args - the arguments

Throws:

java.lang.Exception - the exception

generate

public void generate()
              throws TaxonomyBuilderException

Generates the new DTS using default values for all properties.

Throws:

TaxonomyBuilderException - the taxonomy builder exception

getLogger

public org.apache.log4j.Logger getLogger()

Access to the logger on this class.

Returns:

Logger

getGenerationContext

public GenerationContext getGenerationContext()
                                       throws TaxonomyBuilderException

Generates the new DTS using the properties indicated.

Returns:

the generation context

Throws:

TaxonomyBuilderException - the taxonomy builder exception

getGenerationContext

public GenerationContext getGenerationContext(java.util.Properties props)
                                       throws TaxonomyBuilderException

Generates the new DTS using the properties indicated.

Parameters:

props - the props

Returns:

the generation context

Throws:

TaxonomyBuilderException - the taxonomy builder exception

createDefaultProperties

public static java.util.Properties createDefaultProperties()

Creates the default properties.

Returns:

the properties

generate

public void generate(GenerationContext gc)
              throws TaxonomyBuilderException

Generates the new DTS using the properties indicated and the workbook form the GenerationContext. the instructions sheet will be taken from the constructor of this class

Parameters:

gc - the gc

Throws:

TaxonomyBuilderException - the taxonomy builder exception

addToSchemaLocation

public static void addToSchemaLocation(java.lang.String namespace,
                                       java.lang.String absoluteURL,
                                       GenerationContext gc)

Adds the schema to schemaLocation attribute if it is not already there.

The GenerationContext needs to have an existing not null value in gc.lb which is the current linkbase file being processed

Parameters:

namespace - the namespace

absoluteURL - the absolute url

gc - the gc

putGlobalName

public javax.xml.namespace.QName putGlobalName(java.lang.String name,
                                               javax.xml.namespace.QName q,
                                               GenerationContext gc)

Adds an entry to the global table of names to QNames. This function is used by the Name2QName instruction.

Parameters:

name - as string, this is the key for the QName

q - as QName this is the QName the key refers to.

Returns:

the previously assigned QName if any or null.

getTypeDefinitionAtPoint

public static XBRLXSDTypeDefinition getTypeDefinitionAtPoint(GenerationContext gc,
                                                             ExcelSheetPoint typePoint)

Gets the type definition at point.

Parameters:

gc - the gc

typePoint - the type point

Returns:

the type definition at point

getArcroleType

public XBRLArcroleType getArcroleType(GenerationContext gc,
                                      java.lang.String arcrole)

Returns an arcrole type in the DTS from the arcrole type URI

Parameters:

gc - Generation context

arcrole - the arcrole URI value as string

Returns:

XBRLArcroleType instance or null in case of errors

getXMLFragment

public static XMLFragment getXMLFragment(java.lang.String keyToken,
                                         GenerationContext gc)

Obtains an XMLFragment from the DTS using either the cache of Generic Labels or the loc({href}) function.

Parameters:

keyToken - the key token

gc - the gc

Returns:

the XML fragment

getQName

public javax.xml.namespace.QName getQName(java.lang.String token,
                                          GenerationContext gc,
                                          XBRLTaxonomy tx,
                                          XBRLLinkbase lb)

Obtains a QName from the token string. The prefix must exist in the dts associated to a namespace in order to success

Parameters:

token - the token

gc - the GenerationContext

tx - in scope taxonomy if any (for resolution of namespaces), can be null

lb - in scope linkbase if any (for resolution of namespaces), can be null

Returns:

the q name

getConceptAtPoint

public XMLFragment getConceptAtPoint(DTSContainer dts,
                                     ExcelSheetPoint conceptPrefixPoint)
                              throws SheetPointAccessException

Search the DTS for a concept definition using the prefix and local name. A warning is sent out to the logger only when no taxonomy can be found for the prefix

Parameters:

dts - DTSContainer for concept searching

conceptPrefixPoint - SheetPoint for the prefix

Returns:

null if the prefix is "END" or the XMLElementDefinition as an XMLFragment

Throws:

SheetPointAccessException - if the concept is not found.

getQNameAtPoint

public javax.xml.namespace.QName getQNameAtPoint(GenerationContext gc,
                                                 ExcelSheetPoint qnamePoint,
                                                 boolean bIsConcept)
                                          throws SheetPointAccessException

Reads a concept reference as defined in the Taxonomy Builder documentation

The cell pointed to by the qnamePoint parameter is the concept prefix. The following cell is the element name in the namespace defined by the prefix.

The method searches loaded namespaces for a namespace that corresponds to the prefix. Once one is found, a new QName is created on that namespace for that prefix using the name found in the following cell.

Parameters:

qnamePoint - the cell where the prefix is defined

bIsConcept - the b is concept

Returns:

QName of the concept, new concept or existing concept

Throws:

SheetPointAccessException - in case of problems reading the parameters

getQNameConcept

public javax.xml.namespace.QName getQNameConcept(DTSContainer dts,
                                                 java.lang.String conceptPrefix,
                                                 java.lang.String conceptName)

Returns the QName of a concept already defined in one of the taxonomies in the DTS. The taxonomy is identified by the prefix. if the prefix is not unique, all taxonomies for the same prefix are used to search for the conceptName, if both taxonomies with the same prefix contains the same conceptName the result is unpredictable

Parameters:

dts - the dts

conceptPrefix - the concept prefix

conceptName - the concept name

Returns:

a QName or null if not found

readAttributes

public XBRLAttribute[] readAttributes(ExcelSheetPoint attSp,
                                      GenerationContext gc,
                                      boolean useContextTaxonomyNamespace,
                                      java.lang.String[] validNoNamespaceAtts)

Obtain attributes for the new elements.

Parameters:

attSp - the att sp

gc - the GenerationContext

useContextTaxonomyNamespace - a boolean value. when true, the taxonomy namespace will have priority when resolving prefixes

validNoNamespaceAtts - the valid no namespace atts

Returns:

the XBRL attribute[]

Since:

version 2

usage

public static void usage()

Usage.

getContentAsStringFromTextOrRef

public java.lang.String getContentAsStringFromTextOrRef(ExcelSheetPoint sp,
                                                        GenerationContext gc)
                                                 throws SheetPointException

Returns the content of the cell in the sp parameter as text, if that cell content is another cell reference, the reference is resolved to the final text and returned. May return null if the initial sheet point is not a cell in the workbook with a value

Parameters:

sp - the excel sheet point to start looking at

gc - the generation context

Returns:

the text directly or indirectly referenced

Throws:

SheetPointException - in case sp contains nothing (the cell does not exist with a content in the workbook)