public class RowObjectContainer extends ObjectMap<RowObjectContainer>
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)>}>"
| 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. |
| 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.
|
| Constructor and Description |
|---|
RowObjectContainer(excelExporter.excelParser.ErrorCounter errCnt,
java.lang.String logContext,
Identifier name,
int idxColWorksheet)
Create a new container object.
|
| 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.
|
containsKey, createComparator, entrySet, get, getNoItems, put, putItem, setIndexInCollection, toStringpublic ObjectList<RowObject> rowAry
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.
public RowObject prop
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.
public RowObjectContainer(excelExporter.excelParser.ErrorCounter errCnt,
java.lang.String logContext,
Identifier name,
int idxColWorksheet)
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.
public int getNoRows()
rowAry. From a StringTemplate V4 template
this member is accessed as <group.noRows>.public boolean putGroup(RowObjectContainer group, int idxRow, int idxCol)
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.public void addRow(RowObject row)
row - The object to add.public void addRowWithPath(RowObject row, excelExporter.excelParser.ColumnTitleMgr colTitleMgr)
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.
row - The object to add.colTitleMgr - The column title manager by reference. Used to retrieve the information about the
grouping path scheme.public void sort(excelExporter.excelParser.ColumnTitleMgr colTitleMgr)
This method should be called after complete build-up of the container.
colTitleMgr - The column title manager by reference. Used to retrieve the information about the
column sort attributes.