excelExporter.excelParser.dataModel

## Class Cluster

- java.lang.Object
- - java.util.AbstractMap<java.lang.Object,java.lang.Object>
  - - excelExporter.excelParser.dataModel.ObjectMap<ExcelWorkbook>
    - - excelExporter.excelParser.dataModel.Cluster

- All Implemented Interfaces:
    java.util.Map<java.lang.Object,java.lang.Object>

      public class Cluster
      extends ObjectMap<ExcelWorkbook>

  The root of all parsed and rendered information.

  The "data model" is the Java representation of the Excel input, the parse tree with other words. The "Cluster" is the root of the data model and information rendering in a StringTemplate V4 template will always begin with the one and only object of this class.

  An object of this class contains the results of parsing the input files, completed by some configuration data. The object is passed to the template engine for rendering the information in the wanted format.

  Formally, a `Cluster` object is a Java Map, which contains Excel workbooks, looked up by name. The name of a workbook is subject to the application configuration. It might be the Excel file name but this is not a must and not even common practice. If the application has parsed two Excel workbooks "myBookA" and "myBookB", then these workbooks would be accessed from a StringTemplate V4 template with an expression like `<cluster.myBookA>` or `<cluster.myBookB>`.

  The cluster provides more information to the rendering process. The map of workbooks is extended by some so-called "pseudo-fields", which can be accessed from a template by means of the dot notation. As an example, the cluster has a name and this name can be accessed by the template expression `<cluster.name_>`; where `name_` denotes a pseudo-field. (It's impossible to name a workbook "name_", this is a reserved keyword.)

  The list of all supported pseudo-fields is documented as enumeration `Cluster.PseudoFieldName`.

  `Cluster` is derived from its base class and the base class' pseudo-fields are inherited and can be accessed in the same way. They are documented as enumeration `ObjectMap.PseudoFieldName`.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Cluster.PseudoFieldName` This is the list of pseudo-fields of class `Cluster` that can be accessed from a StringTemplate V4 template.

    - ### Nested classes/interfaces inherited from class java.util.AbstractMap

      `java.util.AbstractMap.SimpleEntry<K,V>, java.util.AbstractMap.SimpleImmutableEntry<K,V>`

    - ### Nested classes/interfaces inherited from interface java.util.Map

      `java.util.Map.Entry<K,V>`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `int` | `noSheets` The total number of parsed sheets, regardless of how this relates to different books and sheet groups.
    `java.util.Map<java.lang.String,ObjectList<ExcelWorksheet>>` | `sheetGroupMap` The worksheets of all the workbooks are held a second time in a map of global worksheet groups.
    `ExcelWorkbook` | `theOnlyWorkbook` To simplify template writing in a special but quite common case the data model offers a direct reference to the workbook.
    `ExcelWorksheet` | `theOnlyWorksheet` To simplify template writing in a special but quite common case the data model offers a direct reference to the worksheet.

    - ### Fields inherited from class excelExporter.excelParser.dataModel.ObjectMap

      `exists, i_, i0_, itemAry, itemMap, name_, objId`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Cluster(excelExporter.excelParser.ErrorCounter errCnt, java.lang.String name)` Create a new cluster object.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `getNoSheetGroups()` The number of global groups of worksheets in `sheetGroupMap`.
    `void` | `putBook(ExcelWorkbook book)` Add a new workbook.
    `void` | `reportDirectDataAccess()` User feedback: This method reports if the direct access to a single workbook/worksheet is available.
    `void` | `sort(SortOrder.Order sortOrderBooks, SortOrder.Order sortOrderSheets)` Sort the workbooks of this cluster and the worksheets in the global groups, which are managed by the cluster.

    - ### Methods inherited from class excelExporter.excelParser.dataModel.ObjectMap

      `containsKey, createComparator, entrySet, get, getNoItems, put, putItem, setIndexInCollection, toString`

    - ### Methods inherited from class java.util.AbstractMap

      `clear, containsValue, equals, hashCode, isEmpty, keySet, putAll, remove, size, values`

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

      `getClass, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface java.util.Map

      `compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, remove, replace, replace, replaceAll`

- - ### Field Detail

    - #### theOnlyWorkbook

          public ExcelWorkbook theOnlyWorkbook

      To simplify template writing in a special but quite common case the data model offers a direct reference to the workbook. This will work only if only a single workbook is parsed in total. If no or more than one workbook is parsed this reference is set to null in order to avoid unrecognized problems due to ambiguities.

      How this field is set, how it relates to parsed workbooks is written to the application log on logging level INFO and more in detail on logging level DEBUG.

      This field can be available even if the other field `theOnlyWorksheet` is null.

    - #### theOnlyWorksheet

          public ExcelWorksheet theOnlyWorksheet

      To simplify template writing in a special but quite common case the data model offers a direct reference to the worksheet. This will work only if a single worksheet is parsed in total. In all other cases this reference is set to null in order to avoid unrecognized problems due to ambiguities.

      How this field is set, how it relates to parsed worksheets is written to the application log on logging level INFO and more in detail on logging level DEBUG.

      If this field is available (not null) then the other field `theOnlyWorkbook` will be available, too.

    - #### sheetGroupMap

          public java.util.Map<java.lang.String,ObjectList<ExcelWorksheet>> sheetGroupMap

      The worksheets of all the workbooks are held a second time in a map of global worksheet groups. The names of the groups and the assignment of worksheets into these groups is user-specified by means of application configuration.

      The use case is to order the worksheets of inhomogenous workbooks into homogenous groups of identically structured worksheets. Using the map of groups one can iterate along all worksheets of same structure.

      This field is null if no global sheet groups are defined.

    - #### noSheets

          public int noSheets

      The total number of parsed sheets, regardless of how this relates to different books and sheet groups. Please note, the number of references to parsed sheets will in general be greater since one and the same sheet can be held in more than one collection.

  - ### Constructor Detail

    - #### Cluster

          public Cluster(excelExporter.excelParser.ErrorCounter errCnt,
                         java.lang.String name)

      Create a new cluster object.
      Parameters:
        `errCnt` - A client supplied error counter. The use case is to permit consecutive error counting across different phases of processing.
        `name` - The user chosen name of the data cluster.
      Remark:
        This method is irrelevant and meaningless to a StringTemplate V4 template.

  - ### Method Detail

    - #### getNoSheetGroups

          public int getNoSheetGroups()

      The number of global groups of worksheets in `sheetGroupMap`. From a StringTemplate V4 template this member is accessed as `<cluster.noSheetGroups>`.

    - #### putBook

          public void putBook(ExcelWorkbook book)

      Add a new workbook. From a StringTemplate V4 template this member is inaccessible.
      Parameters:
        `book` - The added workbook object. Its name must not be empty; it is the key into the map to fetch the book.
      Remark:
        This method is irrelevant and meaningless to a StringTemplate V4 template.

    - #### reportDirectDataAccess

          public void reportDirectDataAccess()

      User feedback: This method reports if the direct access to a single workbook/worksheet is available.
      Remark:
        This method is irrelevant and meaningless to a StringTemplate V4 template.

    - #### sort

          public void sort(SortOrder.Order sortOrderBooks,
                           SortOrder.Order sortOrderSheets)

      Sort the workbooks of this cluster and the worksheets in the global groups, which are managed by the cluster.

      This method should be called at the end of parsing all the workbooks.

      Parameters:
        `sortOrderBooks` - The wanted sort order for the workbooks. Sorting is done with respect to the names of the workbooks. Sorting is done based on `SortOrder.createComparatorString(excelExporter.excelParser.SortOrder.Order)`; refer to this method to get details about the behavior of sorting.
        `sortOrderSheets` - The wanted sort order for the worksheets. Sorting is done with respect to the names of the worksheets. Sorting is done based on `SortOrder.createComparatorString(excelExporter.excelParser.SortOrder.Order)`; refer to this method to get details about the behavior of sorting.
      Remark:
        This method is irrelevant and meaningless to a StringTemplate V4 template.