uk.ac.starlink.votable

## Class VOTableVersion

- java.lang.Object
- - uk.ac.starlink.votable.VOTableVersion

- All Implemented Interfaces:
    java.lang.Comparable<VOTableVersion>

      public abstract class VOTableVersion
      extends java.lang.Object
      implements java.lang.Comparable<VOTableVersion>

  Provides characteristics for a given version of the VOTable standard. An instance of this class is passed to a `VOTableWriter` to indicate what version of the standard should be followed when generating VOTable output.
  Since:
    15 Nov 2012

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `DEFAULT_VERSION_STRING` Default VOTable version number which output will conform to if not otherwise specified ("1.4").
    `static VOTableVersion` | `V10` VOTable 1.0.
    `static VOTableVersion` | `V11` VOTable 1.1.
    `static VOTableVersion` | `V12` VOTable 1.2.
    `static VOTableVersion` | `V13` VOTable 1.3.
    `static VOTableVersion` | `V14` VOTable 1.4.
    `static VOTableVersion` | `V15` VOTable 1.5.
    `static VOTableVersion` | `V16` VOTable 1.6.
    `static java.lang.String` | `VOTABLE_VERSION_PROP` System property name whose value gives the default VOTable version written by instances of this class if no version is given explicitly.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `VOTableVersion(java.lang.String versionNumber)` Constructor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract boolean` | `allowBinary2()` Indicates whether the BINARY2 serialization format is defined by this version.
    `abstract boolean` | `allowCoosysRefposition()` Indicates whether the refposition attribute of the COOSYS element is supported in this version.
    `abstract boolean` | `allowEmptyTd()` Indicates whether this version permits an empty TD element to represent a null value for all data types.
    `abstract boolean` | `allowInfo()` Indicates whether this version supports the INFO element.
    `abstract boolean` | `allowTimesys()` Indicates whether the TIMESYS element is supported in this version.
    `abstract boolean` | `allowXtype()` Indicates whether the xtype attribute is permitted on FIELD elements etc in this version.
    `int` | `compareTo(VOTableVersion other)`
    `abstract boolean` | `forbidArraysize1()` Indicates whether this version of VOTable deprecates/forbids the use of the arraysize attribute on FIELD/PARAM elements with a value of "1".
    `static VOTableVersion` | `getDefaultVersion()` Returns the version instance used by default for output in this JVM.
    `abstract java.lang.String` | `getDoctypeDeclaration()` Returns the text of the DOCTYPE XML declaration for this version.
    `java.lang.String` | `getDraftIdentifier()` Returns a draft-version identifier for VOTable versions that are not yet in their final form.
    `abstract java.net.URL` | `getDtdUrl()` Returns a URL from which the DTD can be retrieved.
    `static java.util.Map<java.lang.String,VOTableVersion>` | `getKnownVersions()` Returns a number->version map for all known versions.
    `abstract javax.xml.validation.Schema` | `getSchema()` Returns a schema which may be used to validate document instances of this VOTable version.
    `abstract java.lang.String` | `getSchemaLocation()` Returns the URL of the VOTable schema corresponding to this version.
    `java.lang.String` | `getVersionNumber()` Returns the version number for this version.
    `abstract java.lang.String` | `getXmlNamespace()` Returns the XML namespace in which the VOTable elements reside.
    `abstract boolean` | `isCharUnicode()` Indicates whether the char datatype contains UTF-8 bytes.
    `abstract boolean` | `isVOUnitSyntax()` Indicates whether this version of VOTable is supposed to use the VOUnit standard for the content of unit attributes.
    `java.lang.String` | `toString()` Returns version number.
    `static VOTableVersion` | `valueOf(java.lang.String txt)` Converts a string representation to an instance of this class.

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

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

- - ### Field Detail

    - #### V10

          public static final VOTableVersion V10

      VOTable 1.0.

    - #### V11

          public static final VOTableVersion V11

      VOTable 1.1.

    - #### V12

          public static final VOTableVersion V12

      VOTable 1.2.

    - #### V13

          public static final VOTableVersion V13

      VOTable 1.3.

    - #### V14

          public static final VOTableVersion V14

      VOTable 1.4.

    - #### V15

          public static final VOTableVersion V15

      VOTable 1.5.

    - #### V16

          public static final VOTableVersion V16

      VOTable 1.6.

    - #### DEFAULT_VERSION_STRING

          public static final java.lang.String DEFAULT_VERSION_STRING

      Default VOTable version number which output will conform to if not otherwise specified ("1.4").
      See Also:
        Constant Field Values

    - #### VOTABLE_VERSION_PROP

          public static final java.lang.String VOTABLE_VERSION_PROP

      System property name whose value gives the default VOTable version written by instances of this class if no version is given explicitly. The property is named "votable.version" and if it is not supplied the version defaults to the value of `DEFAULT_VERSION_STRING` (="1.4").
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### VOTableVersion

          protected VOTableVersion(java.lang.String versionNumber)

      Constructor.
      Parameters:
        `versionNumber` - the number (like "1.1") identifying this version

  - ### Method Detail

    - #### getVersionNumber

          public java.lang.String getVersionNumber()

      Returns the version number for this version.
      Returns:
        version number (like "1.1")

    - #### getXmlNamespace

          public abstract java.lang.String getXmlNamespace()

      Returns the XML namespace in which the VOTable elements reside.
      Returns:
        VOTable XML namespace, or null

    - #### getSchemaLocation

          public abstract java.lang.String getSchemaLocation()

      Returns the URL of the VOTable schema corresponding to this version.
      Returns:
        VOTable schema, or null

    - #### getSchema

          public abstract javax.xml.validation.Schema getSchema()

      Returns a schema which may be used to validate document instances of this VOTable version. Will return non-null iff `getSchemaLocation()` returns non-null.
      Returns:
        validation schema, or null

    - #### getDoctypeDeclaration

          public abstract java.lang.String getDoctypeDeclaration()

      Returns the text of the DOCTYPE XML declaration for this version.
      Returns:
        doctype declaration, or null

    - #### getDtdUrl

          public abstract java.net.URL getDtdUrl()

      Returns a URL from which the DTD can be retrieved. This is not the canonical DTD url, but a pointer to a local resource. Will return non-null iff `getDoctypeDeclaration()` returns non-null.
      Returns:
        local URL from which the DTD can be retrieved, or null

    - #### getDraftIdentifier

          public java.lang.String getDraftIdentifier()

      Returns a draft-version identifier for VOTable versions that are not yet in their final form.

      If the standard to which this version applies is still subject to change, a version-specific document identifier of the form XX-VOTable-A.B-YYYYMMD should be returned, as described in the IVOA DocStd document. XX will presumably be WD or PR.

      For final (REC-status) documents, null is returned.

      Returns:
        version identifier for non-REC VOTable versions, null for REC-status versions
      See Also:
        DocStd v2.0 sec 1.2

    - #### compareTo

          public int compareTo(VOTableVersion other)

      Specified by:
        `compareTo` in interface `java.lang.Comparable<VOTableVersion>`

    - #### toString

          public java.lang.String toString()

      Returns version number.
      Overrides:
        `toString` in class `java.lang.Object`

    - #### allowInfo

          public abstract boolean allowInfo()

      Indicates whether this version supports the INFO element.
      Returns:
        true iff the INFO element exists

    - #### allowEmptyTd

          public abstract boolean allowEmptyTd()

      Indicates whether this version permits an empty TD element to represent a null value for all data types.
      Returns:
        true iff empty TD elements are always permitted

    - #### allowBinary2

          public abstract boolean allowBinary2()

      Indicates whether the BINARY2 serialization format is defined by this version.
      Returns:
        true iff BINARY2 is allowed

    - #### allowXtype

          public abstract boolean allowXtype()

      Indicates whether the xtype attribute is permitted on FIELD elements etc in this version.
      Returns:
        true iff xtype attribute is allowed

    - #### allowTimesys

          public abstract boolean allowTimesys()

      Indicates whether the TIMESYS element is supported in this version.
      Returns:
        true iff TIMESYS is allowed

    - #### allowCoosysRefposition

          public abstract boolean allowCoosysRefposition()

      Indicates whether the refposition attribute of the COOSYS element is supported in this version.
      Returns:
        true iff COOSYS/@refposition attribute is supported

    - #### isVOUnitSyntax

          public abstract boolean isVOUnitSyntax()

      Indicates whether this version of VOTable is supposed to use the VOUnit standard for the content of unit attributes.
      Returns:
        true if VOUnits are supposed to be used
      See Also:
        VOUnits

    - #### forbidArraysize1

          public abstract boolean forbidArraysize1()

      Indicates whether this version of VOTable deprecates/forbids the use of the arraysize attribute on FIELD/PARAM elements with a value of "1". See VOTable 1.3 Erratum #3.
      Returns:
        true if arraysize="1" should be suppressed

    - #### isCharUnicode

          public abstract boolean isCharUnicode()

      Indicates whether the char datatype contains UTF-8 bytes.

      If true, the `char` datatype holds Unicode, encoded as UTF-8 in the BINARY/BINARY2 serializations. if false, they are 7-bit ASCII characters. If true, the unicodeChar datatype is deprecated.

      Returns:
        true iff the char datatype holds Unicode characters

    - #### getKnownVersions

          public static java.util.Map<java.lang.String,VOTableVersion> getKnownVersions()

      Returns a number->version map for all known versions. The map keys are version number strings like "1.1". The order of entries in this map is in ascending order of version number.
      Returns:
        version map

    - #### valueOf

          public static VOTableVersion valueOf(java.lang.String txt)

      Converts a string representation to an instance of this class.
      Parameters:
        `txt` - name of version
      Returns:
        version instance or null if not recognised
      See Also:
        `BeanConfig`

    - #### getDefaultVersion

          public static VOTableVersion getDefaultVersion()

      Returns the version instance used by default for output in this JVM. By default this is determined by the value of the `DEFAULT_VERSION_STRING` constant, but it can be overridden by use of the `VOTABLE_VERSION_PROP` ("votable.version") system property.
      Returns:
        default VOTable version for output