uk.ac.starlink.table
Interface ValueInfo

All Known Implementing Classes:
DefaultValueInfo

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 Objects; use of the information in this class can then be used to make additional sense of the object(s) thus returned.


Method Summary
 String formatValue(Object value, int maxLength)
          Returns a string representation of a given value described by this ValueInfo.
 TableCellRenderer getCellRenderer()
          Returns a renderer suitable for rendering values described by this object in a JTable cell.
 Class getContentClass()
          Returns the java class of the values described by this object.
 String getDescription()
          Returns a description of the values described by this object.
 int getElementSize()
          May indicate the size of a value element stored as the value of this info.
 String getName()
          Returns the name of this object.
 int[] getShape()
          Returns the shape associated with array value types.
 String getUCD()
          Returns the Unified Column Descriptor string applying to the values described by this object.
 String getUnitString()
          Returns a string representing the units of 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.
 Object unformatString(String rep)
          Returns an object of the sort described by this ValueInfo represented by the given string rep.
 

Method Detail

getName

public String getName()
Returns the name of this object.

Returns:
the name

getUnitString

public 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

public 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

getDescription

public 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

public 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

public 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

public 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

public 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

public 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

formatValue

public String formatValue(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

public Object unformatString(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)

getCellRenderer

public TableCellRenderer getCellRenderer()
Returns a renderer suitable for rendering values described by this object in a JTable cell. The renderer should ideally render objects in such a way that a long column of them looks tidy. A null value may be returned to indicate that smoe default renderer will be used, in which case the text of the rendered cell will be as provided by the formatValue(java.lang.Object, int) method.

Returns:
a custom table cell renderer, or null

Copyright © 2004 CLRC: Central Laboratory of the Research Councils. All rights reserved.