..                                    ######
.. class:: OctetStream

   A series of 8-bit bytes which combined together form a digital object.
   *OctetStream* is used to transfer object bytes such as the response to
   :func:`MNRead.get`.



..                                    ######
.. class:: Integer

   A simple integer. The range of expected values should be described with the
   accompanying API call.

   The Integer type is serialized over XML using the predefined XMLSchema
   `integer`_ type, the value space of which is the infinite series
   {...,-2,-1,0,1,2,...}.

.. _integer: http://www.w3.org/TR/xmlschema-2/#integer



..                                    ######
.. class:: Boolean

   A boolean response is commonly used in the DataONE service APIs to indicate
   success or otherwise of an operation. For operations that are called
   through the service interfaces, a positive boolean response (i.e. True) is
   indicated by returning a HTTP response with a status code of "200". The
   body of the message may contain additional content, but this should be
   ignored by the receiver.

   A False or failure response must return an appropriate Error message and
   must set the appropriate HTTP status code on the response to indicate a
   failure.

   The Boolean type is serialized over XML using the predefined XMLSchema
   `boolean`_ type, an instance of which can have the following legal literals
   {true, false, 1, 0}.

.. _boolean: http://www.w3.org/TR/xmlschema-2/#boolean


..                                    ######
.. class:: DateTime

  A string that completely identifies a specific date and time. When *DateTime*
  values are used within fields in request and response messages, and as
  URL-encoded values for parameters, all *DateTime* values will be typed using
  the XML Schema Datatypes definition (see `XMLSchema dateTime`_) for the
  datetime serialization syntax (*xs:dateTime*). This syntax represents a
  subset of the ISO 8601 standard notation, and so standard ISO 8601 parsing
  libraries can be used to parse the values (see libraries used below). In
  addition, within DataONE, these values MUST be expressed with a timezone
  designation in UTC/GMT time only; local times are not permitted.

  - Must include date and time
  - The time zone must be 0, i.e. GMT

  Valid representations include:

  - `YYYY-MM-DDTHH:MM:SS.mmm`
  - `YYYY-MM-DDTHH:MM:SS.mmm+00:00`

  The milliseconds may be left off if that precision is not available.

  In addition, in any methods that use date time values in HTTP headers, the
  serialization will follow the `HTTP Full Date`_ standard (RFC 1123), e.g::

    Sun, 06 Nov 1994 08:49:37 GMT

  In Java, code against `java.util.Date`_, though serialization and
  deserialization will be performed with `org.joda.DateTime`_ to ensure
  millisecond precision is correct.

  In Python, we use `datetime.datetime`_ to represent datetimes internally and
  a library called iso8601 to serialize and deserialize to Types.DateTime and
  Pyxb_ for the XML representation.

  See also the `XMLSchema dateTime`_ type which is used for serializing DateTime
  values in XML transmitted between DataONE components.

.. _HTTP Full Date: http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.3.1

.. _XMLSchema dateTime: http://www.w3.org/TR/xmlschema-2/#dateTime

.. _java.util.Date: http://download.oracle.com/javase/6/docs/api/java/util/Date.html

.. _org.joda.DateTime: http://joda-time.sourceforge.net/

.. _datetime.datetime: http://docs.python.org/library/datetime.html

.. _Pyxb: http://pyxb.sourceforge.net/api/pyxb.binding.datatypes.dateTime-class.html



..                                    ######
.. class:: DescribeResponse

  The :func:`MNRead.describe` method provides a low cost hint about the type,
  size and state of an object.

  The *DescribeResponse* is returned from the server in a HTTP HEAD response,
  and hence the values must be represented in the HTTP response headers. There
  is no XML serialization of a *DescribeResponse*.

  .. image:: images/class_describeresponse.png

  ..
    @startuml images/class_describeresponse.png
    class DescribeResponse {
      +DataONE-formatId : ObjectFormatIdentifier
      +Content-Length : integer
      +Last-Modified : DateTime
      +DataONE-Checksum : Checksum
      +DataONE-SerialVersion: unsignedLong
    }
    DescribeResponse -- ObjectFormatIdentifier
    DescribeResponse -- Checksum
    DescribeResponse -- DateTime
    DescribeResponse -- unsignedLong
    @enduml

  .. attribute:: DataONE-formatId

     The value of the :attr:`SystemMetadata.formatId` entry available in the
     :class:`SystemMetadata`.

  .. attribute:: Content-Length

     Size of the object in bytes, the value of :attr:`SystemMetadata.size`
     from :class:`SystemMetadata`.

  .. attribute:: Last-Modified

     A :class:`DateTime` value that indicates when the :term:`system metadata`
     associated with the object was last modified, i.e. the value of
     :attr:`SystemMetadata.dateSysMetadataModified` for the object.

  .. attribute:: DataONE-Checksum

     The *checksumAlgorithm* and *checksum* value of the object being
     examined. The algorithm and checksum values are separated by a single
     comma with the algorithm first.

  .. attribute:: DataONE-SerialVersion

     The *serialVersion* value of the :term:`system metadata` for the object
     as reported by the Node responding to the describe request.


  Example of a HEAD response on object "ABC123"::

    curl -I http://mn1.dataone.org/mn/v1/object/ABC123

    HTTP/1.1 200 OK
    Last-Modified: Wed, 16 Dec 2009 13:58:34 GMT
    Content-Length: 10400
    Content-Type: application/octet-stream
    DataONE-formatId: eml://ecoinformatics.org/eml-2.0.1
    DataONE-Checksum: SHA-1,2e01e17467891f7c933dbaa00e1459d23db3fe4f
    DataONE-SerialVersion: 1234