com.ihr.xbrl.dts

## Class InstanceExplorer

- java.lang.Object
- - com.ihr.xbrl.dts.InstanceExplorerAbstract
  - - com.ihr.xbrl.dts.InstanceExplorer

- All Implemented Interfaces:
    ContextProvider, InstanceExplorerInterface, InstanceExplorerListener, UnitsProvider

      public class InstanceExplorer
      extends InstanceExplorerAbstract

  This class provides methods to investigate the content of an XBRL instance document from a high level point of view so the development of tools reading the content of instance document will be much easier.
  Author:
    Ignacio

- - ### Field Summary

    - ### Fields inherited from class com.ihr.xbrl.dts.InstanceExplorerAbstract

      `ACUM_Q1Q3, ALL, DAYS, FOREVER, HALVES, HOURS, INSTANT, MINUTES, MONTHS, NONSTANDARD, notesOrderer, QUARTERS, sDays, SECONDS, sForever, sHalves, sHours, sMinutes, sMonths, sNonstandard, sQuarters, sSeconds, sWeeks, sYears, unkownUnit, WEEKS, YEARS`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `InstanceExplorer(LangsProvider lp, HasBoySupport hb, NegatedSupport ns, DefaultUnitProviderInterface defaultUnitProvider)` Instantiates a new instance explorer.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addColumn(CompanyKey ck, ColumnPeriod col)` Adds the column.
    `void` | `addContext(XBRLContext newContext)` Adds a new context to this context provider.
    `void` | `addFact(XBRLFact fact)` Receives notification a fact has been added to the instance being explored.
    `void` | `clear()` Clear.
    `void` | `delColumn(CompanyKey ck, ColumnPeriod col)` Del column.
    `void` | `delContext(XBRLContext ctx)` Removing a context requires removing all facts using the context.
    `void` | `delFact(XBRLFact fact, XBRLFactsList parent)` Announces a fact has been removed from the instance being explored.
    `void` | `factChangedContext(XBRLFactItem fact, XBRLContext oldContext, XBRLContext newContext)` Informs the Context provider that the fact has changed its context information.
    `void` | `factChangedUnit(XBRLFactNumeric fact, XBRLUnit oldUnit, XBRLUnit newUnit)` Fact changed unit.
    `XBRLFactItem` | `findFact(java.util.ArrayList<Member<?>> allMembers)` if the allMembers contains LineTitleMember elements, we need to resolve the hierarchy resolution before calling this method.
    `static java.util.GregorianCalendar` | `gcCloneAndAdd(java.util.GregorianCalendar initial, int dateStep, boolean bSignIsPlus)` Helper method to calculate the date end as a copy of the initial date and an amount of time since then.
    `java.util.Collection<XBRLContext>` | `getAllContexts(CompanyKey ck, XBRLItem.PeriodType periodType)` Access to a collection of all contexts that are associated with factColumns in this InstanceExplorer.
    `java.util.Collection<XBRLUnit>` | `getAllUnits(CompanyKey ck, XBRLItem item)` Returns all the units in the instance document that are used by the company indicated by the CompanyKey parameter.
    `ColumnPeriod` | `getColumn(CompanyKey ck, int index)` Gets the column.
    `java.util.Iterator<ColumnPeriod>` | `getColumnKeysIterator(CompanyKey ck)` Gets the column keys iterator.
    `int[]` | `getColumnsCount(CompanyKey ck, java.util.Collection<FactUse> concepts, boolean bSkipEmptyColumns)` Returns an array of indexes of columns with data for the list of concepts in the concepts parameter.
    `java.util.Iterator<XBRLContext>` | `getCompatibleContexts(XBRLFactItem fact)` Returns an iterator over compatible contexts for this fact.
    `int` | `getDateStepForFact(XBRLFactItem item, int dateStep)` Prepares a dateStep depending on the contextual information of the fact.
    `java.util.Iterator<java.lang.String>` | `getDateStepIterator(CompanyKey ck)` Gets the date step iterator.
    `int` | `getDateStepNumKeys(CompanyKey ck)` Gets the date step num keys.
    `FactsColumn[]` | `getFactsColumn(CompanyKey ck, ColumnPeriod period)` This is never null.
    `XBRLInstance` | `getInstance()` Access to the XBRLInstance in the instance explorer.
    `int` | `getMaxGranularityCode()` Gets the max granularity code.
    `java.util.Vector<XBRLContext>` | `getVectorForKey(CompanyKey ck, java.lang.String keyContexts)` Access to a Vector of XBRLContexts .
    `void` | `instanceEvent(InstanceExplorerEvent e)` Instance event.
    `static java.lang.String` | `instanceModeToString(HandleDateStep.InstantMode instantMode)` Instance mode to string.
    `static XBRLPeriod` | `makePeriod(XBRLItem.PeriodType periodType, int dateStep, DTSContainer dts)` Creates a period of a specified period type (Instant or Duration) and sets the values according to the dateStep value.
    `void` | `processContexts(java.util.Iterator<XBRLContext> contexts)` Process contexts.
    `void` | `setInstance(XBRLInstance instance)` Sets the instance.

    - ### Methods inherited from class com.ihr.xbrl.dts.InstanceExplorerAbstract

      `addInstanceExplorerListener, getCompanyKeys, getFactNotes, getInstanceExplorerListeners, getNumberOfCompanies, getNumTokens, getStringOfDateStep, getStringOfPeriod, getSuggestedUnit, getSuggestedUnits, getVNotes, hasDataForCompany, indexOfDateStepCode, intTokenToString, removeInstanceExplorerListener, sendEvent, setSuggestedUnit, stepsCodeForIndex, stringTokenToInt`

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

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

- - ### Constructor Detail

    - #### InstanceExplorer

          public InstanceExplorer(LangsProvider lp,
                          HasBoySupport hb,
                          NegatedSupport ns,
                          DefaultUnitProviderInterface defaultUnitProvider)

      Instantiates a new instance explorer.
      Parameters:
        `lp` - the lp
        `hb` - the hb
        `ns` - the ns
        `defaultUnitProvider` - the default unit provider

  - ### Method Detail

    - #### getMaxGranularityCode

          public int getMaxGranularityCode()

      Gets the max granularity code.
      Returns:
        the max granularity code

    - #### setInstance

          public void setInstance(XBRLInstance instance)

      Description copied from interface: `InstanceExplorerInterface`
      Sets the instance.
      Parameters:
        `instance` - the new instance

    - #### getVectorForKey

          public java.util.Vector<XBRLContext> getVectorForKey(CompanyKey ck,
                                                      java.lang.String keyContexts)

      Access to a Vector of XBRLContexts .
      Parameters:
        `ck` - the ck
        `keyContexts` - the key contexts
      Returns:
        Vector<XBRLContext>

    - #### getFactsColumn

          public FactsColumn[] getFactsColumn(CompanyKey ck,
                                     ColumnPeriod period)

      This is never null. A new Facts Column is created if none is found
      Parameters:
        `ck` - the ck
        `period` - the period
      Returns:
        FactsColumn

    - #### getDateStepIterator

          public java.util.Iterator<java.lang.String> getDateStepIterator(CompanyKey ck)

      Gets the date step iterator.
      Parameters:
        `ck` - the ck
      Returns:
        Iterator<String>

    - #### getColumnKeysIterator

          public java.util.Iterator<ColumnPeriod> getColumnKeysIterator(CompanyKey ck)

      Gets the column keys iterator.
      Parameters:
        `ck` - the ck
      Returns:
        the column keys iterator

    - #### getDateStepNumKeys

          public int getDateStepNumKeys(CompanyKey ck)

      Gets the date step num keys.
      Parameters:
        `ck` - the ck
      Returns:
        the date step num keys

    - #### getColumnsCount

          public int[] getColumnsCount(CompanyKey ck,
                              java.util.Collection<FactUse> concepts,
                              boolean bSkipEmptyColumns)

      Returns an array of indexes of columns with data for the list of concepts in the concepts parameter.

      If the concepts parameter is null, the returned array contains all columns, one index per column

      The number of elements in the array is the number of columns

      If there is no data for the company the function returns an empty array

      Parameters:
        `ck` - company key
        `concepts` - is a Collection of concepts to filter. if null all concepts are selected.
        `bSkipEmptyColumns` - the b skip empty columns
      Returns:
        array of integers

    - #### getColumn

          public ColumnPeriod getColumn(CompanyKey ck,
                               int index)

      Gets the column.
      Parameters:
        `ck` - the ck
        `index` - the index
      Returns:
        the column

    - #### gcCloneAndAdd

          public static java.util.GregorianCalendar gcCloneAndAdd(java.util.GregorianCalendar initial,
                                                  int dateStep,
                                                  boolean bSignIsPlus)

      Helper method to calculate the date end as a copy of the initial date and an amount of time since then.
      Parameters:
        `initial` - GregorianCalendar
        `dateStep` - constant indicating the period duration. This constant corresponds with GregorianCalendar defined fields extended by constants defined in InstanceExplorerAbstract class
        `bSignIsPlus` - boolean true means positive period false means negative period
      Returns:
        GregorianCalendar

    - #### instanceModeToString

          public static java.lang.String instanceModeToString(HandleDateStep.InstantMode instantMode)

      Instance mode to string.
      Parameters:
        `instantMode` - the instant mode
      Returns:
        the string

    - #### processContexts

          public void processContexts(java.util.Iterator<XBRLContext> contexts)

      Process contexts.
      Parameters:
        `contexts` - the contexts

    - #### getAllContexts

          public java.util.Collection<XBRLContext> getAllContexts(CompanyKey ck,
                                                         XBRLItem.PeriodType periodType)

      Access to a collection of all contexts that are associated with factColumns in this InstanceExplorer. And are of the specified context type.

      The returned collection is ordered from the lowest date to the highest date.

      If periodType is XBRLItem.UNDEFINED_PERIOD_TYPE then all context are included

      Parameters:
        `ck` - the ck
        `periodType` - the period type
      Returns:
        Collection<XBRLContext>

    - #### getCompatibleContexts

          public java.util.Iterator<XBRLContext> getCompatibleContexts(XBRLFactItem fact)

      Description copied from interface: `ContextProvider`
      Returns an iterator over compatible contexts for this fact. the first element in the iterator is the context currently associated to the fact.
      Parameters:
        `fact` - the fact
      Returns:
        Iterator<XBRLContext>

    - #### addContext

          public void addContext(XBRLContext newContext)

      Description copied from interface: `ContextProvider`
      Adds a new context to this context provider. This happens when the user creates a new context
      Parameters:
        `newContext` - XBRLContext to add

    - #### delContext

          public void delContext(XBRLContext ctx)

      Removing a context requires removing all facts using the context.

      This process is independent from removing the context from the instance document

      Parameters:
        `ctx` - the ctx

    - #### addFact

          public void addFact(XBRLFact fact)

      Receives notification a fact has been added to the instance being explored.
      Parameters:
        `fact` - the fact

    - #### delFact

          public void delFact(XBRLFact fact,
                     XBRLFactsList parent)

      Announces a fact has been removed from the instance being explored.

      Note: after removing a fact from its container the fact parent is set to null.

      The fact has to be removed from the parent container prior to call this method and this is the reason this method has a second parameter that indicated what the parent container was.

      Parameters:
        `fact` - the fact
        `parent` - the parent

    - #### delColumn

          public void delColumn(CompanyKey ck,
                       ColumnPeriod col)

      Del column.
      Parameters:
        `ck` - the ck
        `col` - the col

    - #### addColumn

          public void addColumn(CompanyKey ck,
                       ColumnPeriod col)

      Adds the column.
      Parameters:
        `ck` - the ck
        `col` - the col

    - #### getAllUnits

          public java.util.Collection<XBRLUnit> getAllUnits(CompanyKey ck,
                                                   XBRLItem item)

      Returns all the units in the instance document that are used by the company indicated by the CompanyKey parameter. The first element in the collection will be the "preferred" unit for the item indicated in the item parameter. If item is null then the order will be random.
      Parameters:
        `ck` - the ck
        `item` - the item
      Returns:
        Collection<XBRLUnit>

    - #### makePeriod

          public static XBRLPeriod makePeriod(XBRLItem.PeriodType periodType,
                              int dateStep,
                              DTSContainer dts)

      Creates a period of a specified period type (Instant or Duration) and sets the values according to the dateStep value.

      For instant periods bigger than days the instant time is set to 24 hours before of the lowest time where today's date is in the dateStep period

      For instant periods lower than days the instant time is set to the time of the lowest time where today's date is in the dateStep period. Minutes, seconds are set to 0 to indicate the non required precision.

      For periods, the start date and end date is indicating the beginning and ending period time under the range specified by dateStep

      Parameters:
        `periodType` - the period type
        `dateStep` - the date step
        `dts` - DTSContainer
      Returns:
        XBRLPeriod

    - #### factChangedContext

          public void factChangedContext(XBRLFactItem fact,
                                XBRLContext oldContext,
                                XBRLContext newContext)

      Description copied from interface: `ContextProvider`
      Informs the Context provider that the fact has changed its context information.
      Parameters:
        `fact` - the fact
        `oldContext` - the old context
        `newContext` - the new context

    - #### factChangedUnit

          public void factChangedUnit(XBRLFactNumeric fact,
                             XBRLUnit oldUnit,
                             XBRLUnit newUnit)

      Description copied from interface: `UnitsProvider`
      Fact changed unit.
      Parameters:
        `fact` - the fact
        `oldUnit` - the old unit
        `newUnit` - the new unit

    - #### getDateStepForFact

          public int getDateStepForFact(XBRLFactItem item,
                               int dateStep)

      Prepares a dateStep depending on the contextual information of the fact. If the fact is instant, the date step received in the dateStep parameter is returned
      Parameters:
        `item` - the XBRLFactItem
        `dateStep` - suggested value for date step
      Returns:
        int representing the dateStep

    - #### clear

          public void clear()

      Description copied from interface: `InstanceExplorerInterface`
      Clear.
      Specified by:
        `clear` in interface `InstanceExplorerInterface`
      Overrides:
        `clear` in class `InstanceExplorerAbstract`

    - #### findFact

          public XBRLFactItem findFact(java.util.ArrayList<Member<?>> allMembers)

      Description copied from interface: `InstanceExplorerInterface`
      if the allMembers contains LineTitleMember elements, we need to resolve the hierarchy resolution before calling this method. In other words, this method no longer supports LineTitleMember as members of the ArrayList
      Parameters:
        `allMembers` - the all members
      Returns:
        the XBRL fact item

    - #### instanceEvent

          public void instanceEvent(InstanceExplorerEvent e)

      Description copied from interface: `InstanceExplorerListener`
      Instance event.
      Specified by:
        `instanceEvent` in interface `InstanceExplorerListener`
      Overrides:
        `instanceEvent` in class `InstanceExplorerAbstract`
      Parameters:
        `e` - the e

    - #### getInstance

          public XBRLInstance getInstance()

      Description copied from interface: `InstanceExplorerInterface`
      Access to the XBRLInstance in the instance explorer.
      Returns:
        single instance of InstanceExplorerInterface