excelExporter.excelParser.dataModel

## Class ExcelWorkbook

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

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

      public class ExcelWorkbook
      extends ObjectMap<ExcelWorksheet>

  The data structure describing the complete workbook.

  An object of this class contains the results of parsing an Excel input file. The object is passed as part of the data model to the template engine for rendering the information in the wanted format.

  Formally, an `ExcelWorkbook` object is a Java Map, which contains Excel worksheets, looked up by name. The name of a worksheet is subject to the application configuration. It might be the tab of the Excel worksheet but this is not a must and not even common practice. If the application has parsed two Excel worksheets "mySheetA" and "mySheetB", then these worksheets would be accessed from a StringTemplate V4 template with an expression like `<book.mySheetA>` or `<book.mySheetB>`.

  The workbook provides more information to the rendering process. The map of worksheets 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 workbook has a name and this name can be accessed by the template expression `<book.name_>`; where `name_` denotes a pseudo-field. (It's impossible to name a worksheet "name_", this is a reserved keyword.)

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

  `ExcelWorkbook` 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` | `ExcelWorkbook.PseudoFieldName` This is the list of pseudo-fields of class `ExcelWorkbook` 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
    --- | ---
    `FileExt` | `excelFile` The file designation of the Excel source.
    `java.util.LinkedHashMap<java.lang.String,java.lang.Object>` | `optionMap` A map of user specified options or template attributes.
    `ExcelWorksheet` | `theOnlyWorksheet` To simplify template writing in a special but quite common case the data model offers a direct reference from the workbook to its worksheet.

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

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

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ExcelWorkbook(excelExporter.excelParser.ErrorCounter errCnt)` Create a new Excel workbook object.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `getNoOptions()` The number of user options in `optionMap`.
    `boolean` | `putSheet(ExcelWorksheet worksheet)` Add a worksheet object to the workbook.
    `void` | `setExcelFile(FileExt excelFile)` Set the name of the represented Excel file.
    `void` | `setName(java.lang.String givenName)` Set the name of the object and adjust the logging context accordingly.
    `void` | `sort(SortOrder.Order sortOrder)` Sort the worksheets in this workbook.

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

    - #### excelFile

          public FileExt excelFile

      The file designation of the Excel source.

    - #### theOnlyWorksheet

          public ExcelWorksheet theOnlyWorksheet

      To simplify template writing in a special but quite common case the data model offers a direct reference from the workbook to its worksheet. This will work only if a single worksheet is parsed in this book. Otherwise 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 logged on logging level DEBUG.

    - #### optionMap

          public java.util.LinkedHashMap<java.lang.String,java.lang.Object> optionMap

      A map of user specified options or template attributes. User options are template attributes, which are simply passed through from the application's command line to the StringTemplate V4 template and can there be used to control the code generation. The use case are optional constructs in the generated code, which are controlled from the command line.

      User options/attributes can be given in the context of an in- or output file. This map holds all options given in the context of the currently processed input file. (Refer to `Info.optionMap` for the output related options.)

      The name of an option or template attribute is the key into the map and the attribute's value is the value of the map entry. The value object's Java type is one out of String, Boolean, Integer or Double, depending on which fits best to the original command line argument; a command line argument cmdLineArg with value `true` would obviously be passed as Boolean into the template and would permit conditional code by using a construct like: `<if(wBook.optionMap.cmdLineArg)>Command line argument is TRUE!<endif>`

      A sorted map is used for the implementation. The map retains the order of appearance of options on the command line. If an option is set repeatedly then the first appearance on the command line counts. (Typical scenario: The option is set first in the global context as default value then in the context of a specific in- or output file with a value dedicated to that file.) A map iteration in the StringTemplate V4 template will yield this order. Example:

      `<wBook.optionMap:{name|<name>=<wBook.optionMap.(name)><\n>}>`

  - ### Constructor Detail

    - #### ExcelWorkbook

          public ExcelWorkbook(excelExporter.excelParser.ErrorCounter errCnt)

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

  - ### Method Detail

    - #### getNoOptions

          public int getNoOptions()

      The number of user options in `optionMap`. From a StringTemplate V4 template this member is accessed like `<wBook.noOptions>`.

    - #### setName

          public void setName(java.lang.String givenName)

      Set the name of the object and adjust the logging context accordingly.
      Parameters:
        `givenName` - The name of the object or empty string or null if the name should be set by rules. First the name is tried to be derived from the file name. If this is impossble then a generic name is taken.
      Remark:
        This method is irrelevant and meaningless to a StringTemplate V4 template.

    - #### setExcelFile

          public void setExcelFile(FileExt excelFile)

      Set the name of the represented Excel file.
      Parameters:
        `excelFile` - The designation of the parsed Excel file.
      Remark:
        This method is irrelevant and meaningless to a StringTemplate V4 template.

    - #### putSheet

          public boolean putSheet(ExcelWorksheet worksheet)

      Add a worksheet object to the workbook.
      Parameters:
        `worksheet` - The object to add.
      Returns:
        Get the Boolean information whether the worksheet could be put into the map. Adding can fail if the worksheet name clashes with a reserved keyword or an already existing worksheet.
      Remark:
        This method is irrelevant and meaningless to a StringTemplate V4 template.

    - #### sort

          public void sort(SortOrder.Order sortOrder)

      Sort the worksheets in this workbook.

      This method should be called at the end of parsing the workbook.

      Parameters:
        `sortOrder` - The wanted sort order. Sorting is done with respect to the name of the worksheet. 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.