uk.ac.starlink.table

## Interface ValueInfo

- All Known Implementing Classes:
    ColumnInfo, DefaultValueInfo, ServiceDescriptorInfo, URLValueInfo

      public interface ValueInfo

  Describes a value, for instance one obtained from cells in a given table column, or from a table parameter. This interface encapsulates the name, description, UCD etc, as well as information about the kind of object that the value can assume, such as Java class and array shape where applicable. It will normally be associated with a method which is declared to return one or more `Object`s; use of the information in this class can then be used to make additional sense of the object(s) thus returned.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.String` | `formatValue(java.lang.Object value, int maxLength)` Returns a string representation of a given value described by this `ValueInfo`.
    `java.util.List<DescribedValue>` | `getAuxData()` Returns a list of auxiliary metadata objects pertaining to this info.
    `default DescribedValue` | `getAuxDatumByName(java.lang.String name)` Gets an item of auxiliary metadata by its name.
    `java.lang.Class<?>` | `getContentClass()` Returns the java class of the values described by this object.
    `java.lang.String` | `getDescription()` Returns a description of the values described by this object.
    `DomainMapper[]` | `getDomainMappers()` Returns an array of objects which may be able to convert from the values described by this info to a particular target value domain.
    `int` | `getElementSize()` May indicate the size of a value element stored as the value of this info.
    `java.lang.String` | `getName()` Returns the name of this object.
    `int[]` | `getShape()` Returns the shape associated with array value types.
    `java.lang.String` | `getUCD()` Returns the Unified Column Descriptor string applying to the values described by this object.
    `java.lang.String` | `getUnitString()` Returns a string representing the units of the values described by this object.
    `java.lang.String` | `getUtype()` Returns the Utype string applying to the values described by this object.
    `java.lang.String` | `getXtype()` Returns the Xtype string applying to the values described by this object.
    `boolean` | `isArray()` Indicates whether the values described by this object are java arrays.
    `boolean` | `isNullable()` Indicates whether values returned described by this object may have the value `null`.
    `default void` | `setAuxDatum(DescribedValue dval)` Adds the given DescribedValue to the list of auxiliary metadata for this object.
    `java.lang.Object` | `unformatString(java.lang.String rep)` Returns an object of the sort described by this `ValueInfo` represented by the given string `rep`.

- - ### Method Detail

    - #### getName

          java.lang.String getName()

      Returns the name of this object.
      Returns:
        the name

    - #### getUnitString

          java.lang.String getUnitString()

      Returns a string representing the units of the values described by this object. The syntax and conventions should ideally match those adopted by VOTable, as defined by CDS.
      Returns:
        a string giving the units, or `null` if units are unknown
      See Also:
        Standards for Astronomical Catalogues: Units, CDS Strasbourg

    - #### getUCD

          java.lang.String getUCD()

      Returns the Unified Column Descriptor string applying to the values described by this object.
      Returns:
        the UCD, or `null` if none is known
      See Also:
        Unified Column Descriptor scheme, `UCD`

    - #### getUtype

          java.lang.String getUtype()

      Returns the Utype string applying to the values described by this object. Utype is a string which references a data model. It is used pervasively within IVOA standards; probably an official IVOA definition of Utype syntax and semantics will arise one day.
      Returns:
        the Utype, or `null` if none is known

    - #### getXtype

          java.lang.String getXtype()

      Returns the Xtype string applying to the values described by this object. The Xtype string is the 'extended type' information characterising the data type beyond the primitive data type. It is used within IVOA standards, and a number of standard values are defined within the DALI standard.
      Returns:
        the Xtype, or `null` if none is known

    - #### getDescription

          java.lang.String getDescription()

      Returns a description of the values described by this object. It may contain a short or long textual description of the kind of information represented by the value.
      Returns:
        a textual description, or the empty string "" if there is nothing to be said

    - #### getContentClass

          java.lang.Class<?> getContentClass()

      Returns the java class of the values described by this object. The intention is that any `Object` described by this `ValueInfo` will be an instance of the returned class or one of its subclasses. Note therefore that it must not return one of the primitive class objects (`int.class` et al.); the appropriate wrapper classes must be used instead (`Integer.class` etc).

      The class returned should not under normal circumstances be an array of arrays; to express multidimensionality of arrays you should store an array of non-array objects or of primitives and provide shape information via the `getShape` method. There is nothing to stop you describing arrays of arrays with a `ValueInfo`, but some other elements of the tables infrastructure and applications may work on the assumption that such objects are not present.

      Note that to store sets of more than 231 items it will be necessary to use some custom object, since java arrays are indexed by type `int`.

      Returns:
        the java class

    - #### isArray

          boolean isArray()

      Indicates whether the values described by this object are java arrays. This convenience method should return the same as

               getContentClass().getComponentType()!=null

      Returns:
        `true` iff the values described by this object are java arrays

    - #### getShape

          int[] getShape()

      Returns the shape associated with array value types. If the class returned by `getContentClass()` is a java array type, the return from this method may contain information about the shape of the rectangular array which this represents. The dimensions of the array are given in the elements of the return value of this method, fastest varying first. All elements of the array should be positive, except that the last (slowest varying) element may be <=0 (conventionally -1) to indicate that the number of `(shape.length-1)`-dimensional slices contained in the value is not known. If nothing is known about the shape of the array values, then a 1-element array whose only element is <=0 should be returned.

      If `getContentClass` does not give an array type (hence `isArray` returns false) the return value for this method is undefined (but should probably be `null`).

      Returns:
        the shape of the array value

    - #### getElementSize

          int getElementSize()

      May indicate the size of a value element stored as the value of this info. The total size of the value will in this case be the return value of this method multiplied by the number of elements, as indicated by `getShape()` (or by 1, if `getShape` is null).

      The exact meaning of the value returned is dependent on this ValueInfo. This method was introduced to return the maximum number of characters in a `String`-class ValueInfo; this information is necessary for writing out to certain formats (FITS). Other ValueInfo types however may use it for their own purposes.

      ValueInfo instances which decline to supply this information should return -1 from this method.

      Returns:
        notional size of each element an array of values described by this info

    - #### isNullable

          boolean isNullable()

      Indicates whether values returned described by this object may have the value `null`. In general this should return `true`, which implies no assertion about the return values (they may or may not be `null`). But if the values are known never to be `null`, it may return `false`.
      Returns:
        `false` if values are guaranteed non-`null`

    - #### getAuxData

          java.util.List<DescribedValue> getAuxData()

      Returns a list of auxiliary metadata objects pertaining to this info. This is intended as a repository for metadata which is not otherwise made available in this interface.
      Returns:
        a List of `DescribedValue` items

    - #### getDomainMappers

          DomainMapper[] getDomainMappers()

      Returns an array of objects which may be able to convert from the values described by this info to a particular target value domain. This can used for non-obvious representations of certain coordinates such as time and angular position. In most cases the returned array will be empty, since the target domain is obvious (e.g. numeric values). In the (unusual) case that the returned array contains multiple entries, it should have no more than one for any given target domain, and the first entry may be considered "primary" in some sense. Absence of a mapper for a given target domain does not necessarily indicate that the described values cannot be used in that domain.
      Returns:
        array of domain mappers for the values described by this info

    - #### formatValue

          java.lang.String formatValue(java.lang.Object value,
                                       int maxLength)

      Returns a string representation of a given value described by this `ValueInfo`. The returned string should be no longer than a given maximum length.
      Parameters:
        `value` - the value to represent
        `maxLength` - the maximum number of characters in the returned string

    - #### unformatString

          java.lang.Object unformatString(java.lang.String rep)

      Returns an object of the sort described by this `ValueInfo` represented by the given string `rep`.
      Parameters:
        `rep` - the string representation of a value described by this `ValueInfo`
      Returns:
        the Object value represented by `rep`; must match this info's content class (or be null)

    - #### getAuxDatumByName

          default DescribedValue getAuxDatumByName(java.lang.String name)

      Gets an item of auxiliary metadata by its name.
      Parameters:
        `name` - the name of an auxiliary metadata item
      Returns:
        a `DescribedValue` object representing the named auxiliary metadata item for this column, or `null` if none exists

    - #### setAuxDatum

          default void setAuxDatum(DescribedValue dval)

      Adds the given DescribedValue to the list of auxiliary metadata for this object. If an item in the metadata list with the same name as the supplied value already exists, it is removed from the list.
      Parameters:
        `dval` - the new datum to add