excelExporter.excelParser.dataModel

## Class RowObjectContainer

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

- All Implemented Interfaces:
    java.util.Map<java.lang.Object,java.lang.Object>
  Direct Known Subclasses:
    ExcelWorksheet

      public class RowObjectContainer
      extends ObjectMap<RowObjectContainer>

  This is the recursive data structure, which holds the tree structure of groups or containers of row objects. An Excel worksheet is one such container.

  Formally, a `RowObjectContainer` object is a Java Map, which contains other `RowObjectContainer` objects, looked up by name. The map entries are the nested groups of row objects, which can thus be accessed directly by name from a StringTemplate V4 template and by means of the dot notation. If the worksheet `ws` defines the groups `A` and `B` on root level then the template can address to these groups by `<ws.A>` and `<ws.B>`. If `C` was a sub-group of `A` then then the template can address to `C` by an expression like `<ws.A.C>`

  The map entries are sorted in case-sensitive lexical order. If in a StringTemplate V4 template the map iteration operator is applied to a group object then it delivers the keys (i.e. group names) in lexical order. This order is hard coded and can't be influenced by command line arguments. Map iteration could look as follows in a template:

  `All sub groups of worksheet: <ws:{key|<\n> group name: <key>}><\n>`

  In the example before, the produced output should list `A` and `B`, maybe among more sub-groups of the worksheet.

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

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

  `RowObjectContainer` 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`.

  There are two (sorted) list objects which give access to the row objects of the given group (the leafs of the data tree) and to its nested sub-groups. The sort order is controlled from the application command line. The first pseudo-field `RowObjectContainer.PseudoFieldName.rowAry` permits an iteration of the row objects owned by the given group.

  Extending the previous example, the root level row objects of the worksheet would be visisted by `<ws.rowAry:{row|<renderRowObject(row)>}>`. The iteration of all row objects owned by group `A` would look like `<ws.A.rowAry:{row|<renderRowObject(row)>}>`.

  The second additional field `RowObjectContainer.PseudoFieldName.groupAry` permits an iteration of the sub-groups of the group in controlled sort order. Different to the example above, which applied the map iteration of the StringTemplate V4 engine, will the iteration of this list object directly visit the `RowObjectContainer` objects that represent the sub-groups. Putting it all together will we get a complete recursive iteration of the worksheet by a template fragment like:

  `<renderGroup(workSheet)>`

  `renderGroup(g) ::= "<g.rowAry:{row|<renderRowObject(row)>}> <g.groupAry:{subGroup|<renderGroup(subGroup)>}>"`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `RowObjectContainer.PseudoFieldName` This is the list of pseudo-fields of class `RowObjectContainer` 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
    --- | ---
    `RowObject` | `prop` A reference to the one and only row object in `rowAry`.
    `ObjectList<RowObject>` | `rowAry` The list of leaf objects of the tree of row objects and groups of such.

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

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

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `RowObjectContainer(excelExporter.excelParser.ErrorCounter errCnt, java.lang.String logContext, Identifier name, int idxColWorksheet)` Create a new container object.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addRow(RowObject row)` Add a row object to the list of those.
    `void` | `addRowWithPath(RowObject row, excelExporter.excelParser.ColumnTitleMgr colTitleMgr)` Add a row object to the list of those in the right group.
    `int` | `getNoRows()` The number of row objects in `rowAry`.
    `boolean` | `putGroup(RowObjectContainer group, int idxRow, int idxCol)` Add a group object (i.e.
    `void` | `sort(excelExporter.excelParser.ColumnTitleMgr colTitleMgr)` Sort the contents of this container, sort the row objects and the sub-groups in this container.

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

    - #### rowAry

          public ObjectList<RowObject> rowAry

      The list of leaf objects of the tree of row objects and groups of such. Each row of the Excel worksheet is considered one data object, mostly refered to as a "row object". It is placed in the root container (the worksheet object) or in one of its groups or nested sub-groups. The collection `rowAry` holds all row objects, which belong into the group represented by this `RowObjectContainer` object.

      The order of row objects in the list is controlled by the application command line arguments `sort-order-of-column` and `sort-priority-of-column`. Please note, that several instances of these arguments may all affect the sort order.

    - #### prop

          public RowObject prop

      A reference to the one and only row object in `rowAry`.

      A typical use case of grouping is the implementation of direct lookup of row objects by name. The group has the name of the row object and the group will contain one and only one row object. In this situation some typical template code could look like:

      `<first(mySheet.(myRowObjsName).rowAry).myRowObjsProp>`

      This example assumes that `mySheet` is a worksheet object, which has a group for each row object, which direct look up is implemented for. The name of the particular row object of interest is held in attribute `myRowObjsName` and the requested property of that row object is (literally) `myRowObjsProp`. Using this field here, `prop`, the same result would be achieved with:

      `<mySheet.(myRowObjsName).prop.myRowObjsProp>`

      which is much more to the point and a bit shorter.

      The name of this field has been chosen to support the use-case: From the perspective of the Excel spreadsheet maintenance the group actually isn't a group but rather a row object (that can be accessed by name). Now `.prop` references its properties and `.myRowObjsProp` selects a particular one out of them.

      `prop` is null if there are no or more than one row objects in the group. (This field is designed only to support the outline use-case.) Having null for `prop` implicitly makes the template code safer: The former but not the latter template example would require additional explicit code for error reporting if the input doesn't matches the assumed format, i.e. if there were more than a single row object in the group.

      Note, the StringTemplate V4 engine will not make a difference between not having a single row object (and `prop` being null) or having a single row object (`prop` not being null) without any property; `<if(mySheet.(myRowObjsName).prop)>` will evaluate to the unmet condition in either case. For most template applications will this however be irrelevant as either situation will be considered an error.

  - ### Constructor Detail

    - #### RowObjectContainer

          public RowObjectContainer(excelExporter.excelParser.ErrorCounter errCnt,
                                    java.lang.String logContext,
                                    Identifier name,
                                    int idxColWorksheet)

      Create a new container object.
      Parameters:
        `errCnt` - A client supplied error counter. The use case is to permit consecutive error counting across different phases of parsing.
        `logContext` - A string used to precede all logging statements of this module. Pass null if not needed.
        `name` - The container represents a group of row objects. This is the name of the group.
        `idxColWorksheet` - The null based index of the column of the input worksheet, which initially specifies this group and its properties.

        Pass pseudo index -1 for the root container, which represents the whole worksheet.

      Remark:
        This method is irrelevant and meaningless to a StringTemplate V4 template.

  - ### Method Detail

    - #### getNoRows

          public int getNoRows()

      The number of row objects in `rowAry`. From a StringTemplate V4 template this member is accessed as `<group.noRows>`.

    - #### putGroup

          public boolean putGroup(RowObjectContainer group,
                                  int idxRow,
                                  int idxCol)

      Add a group object (i.e. a sub-container) to the map.
      Parameters:
        `group` - The object to add.
        `idxRow` - The null based row index; used for error reporting.
        `idxCol` - The null based column index; used for error reporting.
      Returns:
        Get the Boolean information whether the group object could be added to the map. Adding can fail if the group name clashes with a reserved keyword or an already existing group.
      Remark:
        This method is irrelevant and meaningless to a StringTemplate V4 template.

    - #### addRow

          public void addRow(RowObject row)

      Add a row object to the list of those.
      Parameters:
        `row` - The object to add.
      Remark:
        This method is irrelevant and meaningless to a StringTemplate V4 template.

    - #### addRowWithPath

          public void addRowWithPath(RowObject row,
                                     excelExporter.excelParser.ColumnTitleMgr colTitleMgr)

      Add a row object to the list of those in the right group. The right group is addressed by a path of groups and child-groups. A sub-set of the row object's properties is specified to be path elements in a particular order. The values of these properties specify groups and child groups until the targeted parent of the row object is found.

      The path matching starts with container this. The path therefore is a relative path in general. Only if this is the root container (i.e. the container associated with the worksheet) then the path is interpreted as an absolute path.

      If the groups of the path don't exist yet then they are created as side effect of the operation.

      Parameters:
        `row` - The object to add.
        `colTitleMgr` - The column title manager by reference. Used to retrieve the information about the grouping path scheme.
      Remark:
        This method is irrelevant and meaningless to a StringTemplate V4 template.

    - #### sort

          public void sort(excelExporter.excelParser.ColumnTitleMgr colTitleMgr)

      Sort the contents of this container, sort the row objects and the sub-groups in this container. This is done recursively for all sub-groups and their row-objects and sub-groups.

      This method should be called after complete build-up of the container.

      Parameters:
        `colTitleMgr` - The column title manager by reference. Used to retrieve the information about the column sort attributes.
      Remark:
        This method is irrelevant and meaningless to a StringTemplate V4 template.