uk.ac.starlink.gbin

## Class ItemReader

- java.lang.Object
- - uk.ac.starlink.gbin.ItemReader

-     public class ItemReader
      extends java.lang.Object

  Object which can read the value of a given table column from the (GaiaRoot) data object representing a table row. ItemReaders are arranged hierarchically, since objects may contain objects, and it is in general the leaf nodes that get turned into columns.
  Since:
    6 Jun 2017

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static ItemReader` | `ROOT` Special instance used as the reader root.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ItemReader(ItemReader parentReader, java.lang.reflect.Method method, java.lang.String itemName, Representation<?> repr)` Constructor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static ItemReader[]` | `createItemReaders(java.lang.Class<?> rootClazz, GbinTableProfile profile)` Constructs a list of objects that can each read a field from an object.
    `static java.lang.String` | `getColumnName(ItemReader rdr, java.util.Map<java.lang.String,java.util.List<ItemReader>> nameMap, boolean forceHier, java.lang.String separator)` Works out what name to use for the table column using data from a given item reader.
    `java.lang.Class<?>` | `getItemContentClass()` Returns the class of objects returned by `readItem`
    `java.lang.String` | `getItemName()` Returns the (non-hierarchical) name of the data item represented by this reader.
    `ItemReader` | `getParentReader()` Returns the parent of this reader.
    `boolean` | `isRoot()` Determines whether this instance is the tree root.
    `java.lang.Object` | `readItem(java.util.Map<ItemReader,java.lang.Object> itemMap)` Reads the value for this reader in the context of a given row object.

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

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

- - ### Field Detail

    - #### ROOT

          public static final ItemReader ROOT

      Special instance used as the reader root.

  - ### Constructor Detail

    - #### ItemReader

          public ItemReader(ItemReader parentReader,
                            java.lang.reflect.Method method,
                            java.lang.String itemName,
                            Representation<?> repr)

      Constructor.
      Parameters:
        `parentReader` - parent instance
        `method` - the no-arg public instance method whose return value when applied to the parent reader's object gives this column's value
        `itemName` - basic name for this item
        `repr` - value representation

  - ### Method Detail

    - #### isRoot

          public boolean isRoot()

      Determines whether this instance is the tree root.
      Returns:
        true iff this == ROOT

    - #### getParentReader

          public ItemReader getParentReader()

      Returns the parent of this reader.
      Returns:
        parent, it's null only for ROOT

    - #### getItemName

          public java.lang.String getItemName()

      Returns the (non-hierarchical) name of the data item represented by this reader.
      Returns:
        the Xxx for method getXxx() or isXxx()

    - #### getItemContentClass

          public java.lang.Class<?> getItemContentClass()

      Returns the class of objects returned by `readItem`
      Returns:
        item content class

    - #### readItem

          public java.lang.Object readItem(java.util.Map<ItemReader,java.lang.Object> itemMap)
                                    throws java.io.IOException

      Reads the value for this reader in the context of a given row object. The row object is represented as a map which caches ItemReader->value pairs. The map will be updated by this method, not only by inserting its own value, but also by inserting the values of any missing parent objects as required. Thus each method only needs to be invoked reflectively once per row even for hierarchically nested data items. The only precondition is that the map must contain the entry ROOT->rowObject.
      Parameters:
        `itemMap` - reader->value map, may be modified
      Returns:
        value associated with this reader for the row represented by the submitted map
      Throws:
        `java.io.IOException`

    - #### createItemReaders

          public static ItemReader[] createItemReaders(java.lang.Class<?> rootClazz,
                                                       GbinTableProfile profile)

      Constructs a list of objects that can each read a field from an object. There is one ItemReader returned for each column in the output table.
      Parameters:
        `rootClazz` - class of per-row element
        `profile` - table configuration

    - #### getColumnName

          public static java.lang.String getColumnName(ItemReader rdr,
                                                       java.util.Map<java.lang.String,java.util.List<ItemReader>> nameMap,
                                                       boolean forceHier,
                                                       java.lang.String separator)

      Works out what name to use for the table column using data from a given item reader.
      Parameters:
        `rdr` - item reader supplying data
        `nameMap` - map of all item reader names to a list of the item readers having that name; it can be used to detect name duplication
        `forceHier` - true iff hierarchical names should always be used
        `separator` - separator string for components of a hierarchical column name