Package org.apache.sis.util.collection

## Class TableColumn<V>

- Object
- - TableColumn<V>

- Type Parameters:
    `V` - base type of all values in the column identified by this instance.
  All Implemented Interfaces:
    `CheckedContainer<V>`

      public class TableColumn<V>
      extends Object
      implements CheckedContainer<V>

  Identifies a column in `TreeTable​.Node` instances. Each `TableColumn` instance contains the column header and the type of values for a particular column. `TableColumn`s are used for fetching values from nodes as in the following example:

  >     public class CityLocation {
  >         public static final ColumnTable<String> CITY_NAME = new ColumnTable<>(String.class, "City name");
  >         public static final ColumnTable<Float>  LATITUDE  = new ColumnTable<>(Float.class,  "Latitude");
  >         public static final ColumnTable<Float>  LONGITUDE = new ColumnTable<>(Float.class,  "Longitude");

  >         private String name;
  >         private float  latitude;
  >         private float  longitude;

  >         CityLocation(TreeTable.Node myNode) {
  >             name      = myNode.getValue(CITY_NAME);
  >             latitude  = myNode.getValue(LATITUDE);
  >             longitude = myNode.getValue(LONGITUDE);
  >         }
  >     }

  Identity comparisons and serialization
  This base class relies on identity comparisons instead than defining the `equals(Object)` method, because the element type is not a sufficient criterion for differentiating the columns (many columns have values of the same type) and the header is arbitrary. Consequently developers who create their own instances are encouraged to declare them as static final constants as in the above example, and use those constants consistently.

  This base class is not serializable because the default deserialization mechanism does not resolve automatically the deserialized instances to the above-cited singleton instances. Developers who need serialization support for their own instances have to resolve them in their own subclass. The following example is one possible way to achieve that goal:

  >     public class CityLocation {
  >         public static final ColumnTable<String> CITY_NAME = new Column<>("CITY_NAME", String.class, "City name");
  >         public static final ColumnTable<Float>  LATITUDE  = new Column<>("LATITUDE",  Float.class,  "Latitude");
  >         public static final ColumnTable<Float>  LONGITUDE = new Column<>("LONGITUDE", Float.class,  "Longitude");

  >         private static final class Column<V> extends TableColumn<V> implements Serializable {
  >             private final String field;

  >             private Column(String field, Class<V> type, CharSequence header) {
  >                 super(type, header);
  >                 this.field = field;
  >             }

  >             private Object readResolve() throws ObjectStreamException {
  >                 try {
  >                     return CityLocation.class.getField(field).get(null);
  >                 } catch (Exception cause) { // Many exceptions, including unchecked ones.
  >                     throw new InvalidObjectException(cause.toString());
  >                 }
  >             }
  >         }
  >     }

  The constants defined in this class use a similar approach for providing serialization support.
  Since:
    0.3

  Defined in the `sis-utility` module

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static TableColumn<String>` | `IDENTIFIER` | Frequently-used constant for a column of object identifiers.
    `static TableColumn<Integer>` | `INDEX` | Frequently-used constant for a column of index values.
    `static TableColumn<CharSequence>` | `NAME` | Frequently-used constant for a column of object names.
    `static TableColumn<CharSequence>` | `REMARKS` | Frequently-used constant for a column of remarks.
    `static TableColumn<Class<?>>` | `TYPE` | Frequently-used constant for a column of object types.
    `static TableColumn<Object>` | `VALUE` | Frequently-used constant for a column of object values.
    `static TableColumn<Number>` | `VALUE_AS_NUMBER` | Frequently-used constant for a column of object numerical values.
    `static TableColumn<CharSequence>` | `VALUE_AS_TEXT` | Frequently-used constant for a column of object textual values.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `TableColumn()` | Invoked on deserialization for creating an initially empty instance.
    `` | `TableColumn​(Class<V> type, CharSequence header)` | Creates a new instance for the given type of values.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `Class<V>` | `getElementType()` | Returns the base type of all values in any column identified by this `TableColumn` instance.
    `InternationalString` | `getHeader()` | Returns the text to display as column header.
    `String` | `toString()` | Returns a string representation of this table column.

    - ### Methods inherited from class Object

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

- - ### Field Detail

    - #### NAME

          public static final TableColumn<CharSequence> NAME

      Frequently-used constant for a column of object names. The column header is "Name" (eventually localized) and the column elements are typically instances of `String` or `InternationalString`, depending on whether the data provide localization support or not.

    - #### IDENTIFIER

          public static final TableColumn<String> IDENTIFIER

      Frequently-used constant for a column of object identifiers. The column header is "Identifier" (eventually localized) and the column elements are instances of `String`.

    - #### INDEX

          public static final TableColumn<Integer> INDEX

      Frequently-used constant for a column of index values. The column header is "Index" (eventually localized) and the column elements are instances of `Integer`.

    - #### TYPE

          public static final TableColumn<Class<?>> TYPE

      Frequently-used constant for a column of object types. The column header is "Type" (eventually localized).

    - #### VALUE

          public static final TableColumn<Object> VALUE

      Frequently-used constant for a column of object values. The column header is "Value" (eventually localized) and the column elements can be instance of any kind of objects.
      See Also:
        `VALUE_AS_TEXT`, `VALUE_AS_NUMBER`

    - #### VALUE_AS_TEXT

          public static final TableColumn<CharSequence> VALUE_AS_TEXT

      Frequently-used constant for a column of object textual values. The column header is "Value" (eventually localized) and the column elements are typically instances of `String` or `InternationalString`, depending on whether the data provide localization support or not.

    - #### VALUE_AS_NUMBER

          public static final TableColumn<Number> VALUE_AS_NUMBER

      Frequently-used constant for a column of object numerical values. The column header is "Value" (eventually localized).

    - #### REMARKS

          public static final TableColumn<CharSequence> REMARKS

      Frequently-used constant for a column of remarks. The column header is "Remarks" (eventually localized) and the column elements are typically instances of `String` or `InternationalString`, depending on whether the data provide localization support or not.
      Since:
        1.0

  - ### Constructor Detail

    - #### TableColumn

          protected TableColumn()

      Invoked on deserialization for creating an initially empty instance. This constructor has `protected` visibility only because the Java deserialization mechanism requires so; this constructor shall not be invoked in any other context. See the Identity comparisons and serialization section in the class javadoc for more information.

    - #### TableColumn

          public TableColumn​(Class<V> type,
                             CharSequence header)

      Creates a new instance for the given type of values.
      Parameters:
        `type` - base type of all values in the column identified by this instance.
        `header` - the text to display as column header.

  - ### Method Detail

    - #### getHeader

          public InternationalString getHeader()

      Returns the text to display as column header.
      Returns:
        the text to display as column header.

    - #### getElementType

          public final Class<V> getElementType()

      Returns the base type of all values in any column identified by this `TableColumn` instance.
      Specified by:
        `getElementType` in interface `CheckedContainer<V>`
      Returns:
        the element type.

    - #### toString

          public String toString()

      Returns a string representation of this table column. The default implementation returns the header in its default locale.
      Overrides:
        `toString` in class `Object`