com.rs.xbrl

## Class TaxonomyBuilder

- java.lang.Object
- - com.rs.xbrl.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

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `addToSchemaLocation(java.lang.String namespace, java.lang.String absoluteURL, GenerationContext gc)` Adds the to schema location.
    `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
    `void` | `generateGenericArc(GenerationContext gc, java.lang.String arcrole, java.lang.String from, java.lang.String to, ExcelSheetPoint spAttributes)` Generate generic arc.
    `void` | `generateGenericArc(GenerationContext gc, XBRLArcroleType arcroleT, XMLFragment xfrom, XMLFragment xto, XBRLAttribute[] attributes)`
    `XBRLResource` | `generateGenericLabel(GenerationContext gc, java.lang.String labelRole, java.lang.String lang, ExcelSheetPoint spLabelText, java.lang.String token)` Creates a generic label resource and attach it to the cache indexed by the token key.
    `XBRLArcroleType` | `getArcroleType(GenerationContext gc, java.lang.String arcrole)` Returns an arcrole type in the DTS from the arcrole type URI
    `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` | `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.
    `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.
    `void` | `setVersion(int version)` Sets the excel source version to version 1 or version 2.
    `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

    - #### setVersion

          public void setVersion(int version)

      Sets the excel source version to version 1 or version 2. See the documentation for the differences between the two versions. This method is called by the VERSION instruction
      Parameters:
        `version` - the new version

    - #### 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 to schema location.
      Parameters:
        `namespace` - the namespace
        `absoluteURL` - the absolute url
        `gc` - the gc

    - #### 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

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

    - #### 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

    - #### generateGenericArc

          public void generateGenericArc(GenerationContext gc,
                                java.lang.String arcrole,
                                java.lang.String from,
                                java.lang.String to,
                                ExcelSheetPoint spAttributes)

      Generate generic arc.
      Parameters:
        `gc` - the gc
        `arcrole` - the arcrole
        `from` - the from
        `to` - the to
        `spAttributes` - the sp attributes

    - #### generateGenericArc

          public void generateGenericArc(GenerationContext gc,
                                XBRLArcroleType arcroleT,
                                XMLFragment xfrom,
                                XMLFragment xto,
                                XBRLAttribute[] attributes)

    - #### 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

    - #### generateGenericLabel

          public XBRLResource generateGenericLabel(GenerationContext gc,
                                          java.lang.String labelRole,
                                          java.lang.String lang,
                                          ExcelSheetPoint spLabelText,
                                          java.lang.String token)

      Creates a generic label resource and attach it to the cache indexed by the token key.
      Parameters:
        `gc` - the gc
        `labelRole` - the label role
        `lang` - the lang
        `spLabelText` - the sp label text
        `token` - the token

    - #### 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

    - #### 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)