uk.ac.starlink.table

## Class DefaultValueInfo

- java.lang.Object
- - uk.ac.starlink.table.DefaultValueInfo

- All Implemented Interfaces:
    ValueInfo
  Direct Known Subclasses:
    ColumnInfo, ServiceDescriptorInfo

      public class DefaultValueInfo
      extends java.lang.Object
      implements ValueInfo

  Default implementation of the `ValueInfo` interface. Additionally provides mutator methods for the accessors defined in `ValueInfo`.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `DefaultValueInfo()` Constructs a new generic `DefaultValueInfo` object without a name.
    `DefaultValueInfo(java.lang.String name)` Constructs a new generic `DefaultValueInfo` object with a given name.
    `DefaultValueInfo(java.lang.String name, java.lang.Class<?> contentClass)` Constructs a new `DefaultValueInfo` object with a given name and class.
    `DefaultValueInfo(java.lang.String name, java.lang.Class<?> contentClass, java.lang.String description)` Constructs a new `DefaultValueInfo` object with a given name, class and description.
    `DefaultValueInfo(ValueInfo base)` Constructs a DefaultValueInfo object which is a copy of an existing one.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static java.lang.String` | `formatClass(java.lang.Class<?> clazz)` Returns a human-friendly string indicating the class and shape of a given class object.
    `static java.lang.String` | `formatShape(int[] shape)` Returns a string representing the shape of this object, if it is array-like.
    `java.lang.String` | `formatValue(java.lang.Object value, int maxLength)` Returns a string representation of a given value described by this `ValueInfo`.
    `static ValueInfo` | `generalise(ValueInfo vi1, ValueInfo vi2)` Returns a `ValueInfo` object which is sufficiently general to cover every object described by either of two given `ValueInfo` objects.
    `java.util.List<DescribedValue>` | `getAuxData()` Returns a list of auxiliary metadata objects pertaining to this column.
    `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`.
    `void` | `setAuxData(java.util.List<DescribedValue> auxData)` Sets the list of auxiliary metadata items for this column.
    `void` | `setContentClass(java.lang.Class<?> contentClass)` Sets the java class of objects contained in this column.
    `void` | `setDescription(java.lang.String description)` Sets a textual description of the values described by this object.
    `void` | `setDomainMappers(DomainMapper[] domainMappers)` Sets the domain mappers known for this object.
    `void` | `setElementSize(int size)` Sets the element size of values described by this object.
    `void` | `setName(java.lang.String name)` Sets the name for this object.
    `void` | `setNullable(boolean isNullable)` Sets whether values described by this object may have the value `null`.
    `void` | `setShape(int[] shape)` Sets the shape of values described by this object.
    `void` | `setUCD(java.lang.String ucd)` Sets the Unified Content Descriptor string applying to values described by this object.
    `void` | `setUnitString(java.lang.String unitString)` Sets the string representing the units for the values described by this object.
    `void` | `setUtype(java.lang.String utype)` Sets the Utype string applying to values described by this object.
    `void` | `setXtype(java.lang.String xtype)` Sets the Xtype string applying to values described by this object.
    `java.lang.String` | `toString()` Returns a string representation of this object.
    `static int[]` | `unformatShape(java.lang.String txt)` Takes a stringified version of the shape and turns it into an array.
    `java.lang.Object` | `unformatString(java.lang.String rep)` Returns an object of the sort described by this `ValueInfo` represented by the given string `rep`.

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

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

    - ### Methods inherited from interface uk.ac.starlink.table.ValueInfo

      `getAuxDatumByName, setAuxDatum`

- - ### Constructor Detail

    - #### DefaultValueInfo

          public DefaultValueInfo()

      Constructs a new generic `DefaultValueInfo` object without a name.

    - #### DefaultValueInfo

          public DefaultValueInfo(java.lang.String name)

      Constructs a new generic `DefaultValueInfo` object with a given name.
      Parameters:
        `name` - the name applying to described values

    - #### DefaultValueInfo

          public DefaultValueInfo(java.lang.String name,
                                  java.lang.Class<?> contentClass)

      Constructs a new `DefaultValueInfo` object with a given name and class.
      Parameters:
        `name` - the name applying to described values
        `contentClass` - the class of which described values should be instances

    - #### DefaultValueInfo

          public DefaultValueInfo(java.lang.String name,
                                  java.lang.Class<?> contentClass,
                                  java.lang.String description)

      Constructs a new `DefaultValueInfo` object with a given name, class and description.
      Parameters:
        `name` - the name applying to described values
        `contentClass` - the class of which described values should be instances
        `description` - a textual description of the described values

    - #### DefaultValueInfo

          public DefaultValueInfo(ValueInfo base)

      Constructs a DefaultValueInfo object which is a copy of an existing one. The fields of the new object are copies (where possible not references to) those of the base one.
      Parameters:
        `base` - the object to copy

  - ### Method Detail

    - #### setName

          public void setName(java.lang.String name)

      Sets the name for this object.
      Parameters:
        `name` - the name

    - #### getName

          public java.lang.String getName()

      Description copied from interface: `ValueInfo`
      Returns the name of this object.
      Specified by:
        `getName` in interface `ValueInfo`
      Returns:
        the name

    - #### setUnitString

          public void setUnitString(java.lang.String unitString)

      Sets the string representing the units for the values described by this object.
      Parameters:
        `unitString` - a string giving the units, or `null` if units are unknown

    - #### getUnitString

          public java.lang.String getUnitString()

      Description copied from interface: `ValueInfo`
      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.
      Specified by:
        `getUnitString` in interface `ValueInfo`
      Returns:
        a string giving the units, or `null` if units are unknown
      See Also:
        Standards for Astronomical Catalogues: Units, CDS Strasbourg

    - #### setUCD

          public void setUCD(java.lang.String ucd)

      Sets the Unified Content Descriptor string applying to values described by this object.
      Parameters:
        `ucd` - the UCD, or `null` if none is known

    - #### getUCD

          public java.lang.String getUCD()

      Description copied from interface: `ValueInfo`
      Returns the Unified Column Descriptor string applying to the values described by this object.
      Specified by:
        `getUCD` in interface `ValueInfo`
      Returns:
        the UCD, or `null` if none is known
      See Also:
        Unified Column Descriptor scheme, `UCD`

    - #### setUtype

          public void setUtype(java.lang.String utype)

      Sets the Utype string applying to values described by this object.
      Parameters:
        `utype` - the Utype, or `null` if none is known

    - #### getUtype

          public java.lang.String getUtype()

      Description copied from interface: `ValueInfo`
      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.
      Specified by:
        `getUtype` in interface `ValueInfo`
      Returns:
        the Utype, or `null` if none is known

    - #### setXtype

          public void setXtype(java.lang.String xtype)

      Sets the Xtype string applying to values described by this object.
      Parameters:
        `xtype` - the Xtype, or `null` if none is known

    - #### getXtype

          public java.lang.String getXtype()

      Description copied from interface: `ValueInfo`
      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.
      Specified by:
        `getXtype` in interface `ValueInfo`
      Returns:
        the Xtype, or `null` if none is known

    - #### setDescription

          public void setDescription(java.lang.String description)

      Sets a textual description of the values described by this object.
      Parameters:
        `description` - a texttual description of this column, or the empty string "" if there is nothing to be said

    - #### getDescription

          public java.lang.String getDescription()

      Description copied from interface: `ValueInfo`
      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.
      Specified by:
        `getDescription` in interface `ValueInfo`
      Returns:
        a textual description, or the empty string "" if there is nothing to be said

    - #### getContentClass

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

      Description copied from interface: `ValueInfo`
      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`.

      Specified by:
        `getContentClass` in interface `ValueInfo`
      Returns:
        the java class

    - #### setContentClass

          public void setContentClass(java.lang.Class<?> contentClass)

      Sets the java class of objects contained in this column.
      Parameters:
        `contentClass` - the class of items in this column
      Throws:
        `java.lang.IllegalArgumentException` - if `contentClass` is primitive

    - #### isArray

          public boolean isArray()

      Description copied from interface: `ValueInfo`
      Indicates whether the values described by this object are java arrays. This convenience method should return the same as

               getContentClass().getComponentType()!=null

      Specified by:
        `isArray` in interface `ValueInfo`
      Returns:
        `true` iff the values described by this object are java arrays

    - #### getShape

          public int[] getShape()

      Description copied from interface: `ValueInfo`
      Returns the shape associated with array value types. If the class returned by `ValueInfo.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`).

      Specified by:
        `getShape` in interface `ValueInfo`
      Returns:
        the shape of the array value

    - #### setShape

          public void setShape(int[] shape)

      Sets the shape of values described by this object.
      Parameters:
        `shape` - the shape
      Throws:
        `java.lang.IllegalArgumentException` - if `shape` has elements apart from the last one which are <=0

    - #### getElementSize

          public int getElementSize()

      Description copied from interface: `ValueInfo`
      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 `ValueInfo.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.

      Specified by:
        `getElementSize` in interface `ValueInfo`
      Returns:
        notional size of each element an array of values described by this info

    - #### setElementSize

          public void setElementSize(int size)

      Sets the element size of values described by this object.
      Parameters:
        `size` - the element size

    - #### isNullable

          public boolean isNullable()

      Description copied from interface: `ValueInfo`
      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`.
      Specified by:
        `isNullable` in interface `ValueInfo`
      Returns:
        `false` if values are guaranteed non-`null`

    - #### setNullable

          public void setNullable(boolean isNullable)

      Sets whether values described by this object may have the value `null`. By setting this to `false` you assert that no `null` objects will be returned from this column.
      Parameters:
        `isNullable` - `false` if objects in this column are guaranteed non-`null`

    - #### getDomainMappers

          public DomainMapper[] getDomainMappers()

      Description copied from interface: `ValueInfo`
      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.
      Specified by:
        `getDomainMappers` in interface `ValueInfo`
      Returns:
        array of domain mappers for the values described by this info

    - #### setDomainMappers

          public void setDomainMappers(DomainMapper[] domainMappers)

      Sets the domain mappers known for this object.
      Parameters:
        `domainMappers` - new domain mapper array

    - #### getAuxData

          public java.util.List<DescribedValue> getAuxData()

      Returns a list of auxiliary metadata objects pertaining to this column. The returned value may, if mutable, be modified to change the aux data of this object.
      Specified by:
        `getAuxData` in interface `ValueInfo`
      Returns:
        a List of `DescribedValue` items

    - #### setAuxData

          public void setAuxData(java.util.List<DescribedValue> auxData)

      Sets the list of auxiliary metadata items for this column.
      Parameters:
        `auxData` - a list of `DescribedValue` objects

    - #### generalise

          public static ValueInfo generalise(ValueInfo vi1,
                                             ValueInfo vi2)

      Returns a `ValueInfo` object which is sufficiently general to cover every object described by either of two given `ValueInfo` objects. For most of the info attributes this entails setting to null any attribute which is not the same for both, though for contentClass it involves finding the most specific common ancestor class.
      Parameters:
        `vi1` - one `ValueInfo` object
        `vi2` - the other `ValueInfo` object
      Returns:
        a generalised `ValueInfo` object

    - #### formatValue

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

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

    - #### formatClass

          public static java.lang.String formatClass(java.lang.Class<?> clazz)

      Returns a human-friendly string indicating the class and shape of a given class object. This will read something like "Integer" or "byte[][]" or "uk.ac.starlink.FrameSet".
      Parameters:
        `clazz` - the class
      Returns:
        a string showing the class and shape of `clazz`

    - #### formatShape

          public static java.lang.String formatShape(int[] shape)

      Returns a string representing the shape of this object, if it is array-like. This will look something like "1024,1024,3" or "2,*".
      Parameters:
        `shape` - the shape to format
      Returns:
        a human-readable representation of the value shape
      See Also:
        `unformatShape(String)`

    - #### unformatShape

          public static int[] unformatShape(java.lang.String txt)

      Takes a stringified version of the shape and turns it into an array. This performs the opposite of `formatShape(int[])`, so values are comma-separated, and the last one only may be "*".
      Parameters:
        `txt` - string representation of value shape
      Returns:
        array representation of value shape
      Throws:
        `java.lang.IllegalArgumentException` - if the argument is not in a comprehensible format
      See Also:
        `formatShape(int[])`

    - #### unformatString

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

      Description copied from interface: `ValueInfo`
      Returns an object of the sort described by this `ValueInfo` represented by the given string `rep`.
      Specified by:
        `unformatString` in interface `ValueInfo`
      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)

    - #### toString

          public java.lang.String toString()

      Returns a string representation of this object. The result indicates the object's name, class and shape.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        a string representation of this object