EQUIP2 XML encoding

Chris Greenhalgh, 2006-04-07

Introduction

EQUIP2 uses Hessian as a standard (and default) binary encoding. This note describes an XML encoding which it will use by default for XML/textual renderings of object values. This format compromises self-description (e.g. explicit programming language types) for easier authoring by people and non-Java/EQUIP applications. This does however imply that the some knowledge of the programming language types must be known and/or a scripting framework with consistent coercions to/from strings be used.

Example

A representative example of a class encoded in the proposed encoding follows (from the Day of the Figurines 2 development work-in-progress):

<?xml version="1.0"?> 
<objects defaultPackage="dof2.db" [optional] >
  <Player [ie class name without package] package="dof2.db" [optional]>
    <ID [ie property name]>P1_nick</ID>
    <nickName>nick</nickName>
    <currentMissions [e.g. a set or list]>
      <set [or array or vector] 
           size="2" [may be required for arrays; definitely optional for sets] 
           elementjavatype="java.lang.String" [optional; required for array of primitives] >
        <item [i.e. a repeatable 'property' of the set/array]
              javatype="java.lang.String" [optional; defaults to string (coercion deals with most cases)]
              >M1_thing</item>
        <item>M2_thing</item>
      </set>
    </currentMissions>
    <fullName [NB value is the empty string, not null] />
    <someMapProperty>
      <map [i.e. hashtable]>
        <item>
          <entry [i.e the entry itself] >
            <key javatype="java.lang.String" [optional; see above] >123</key>
            <value javatype="java.lang.String" [optional; see above] >456</value>
          </entry>
        </item>
      </map>
    </someMapProperty>
    <someComplexProperty>
      <Person [another person...] >
        <!-- the usual XML comment(s) -->
      </Person>
    </someComplexProperty>
  </Player>
</objects>

Additional notes:

XML requires that <tag/> be equivalent to <tag></tag>, which for a string value is therefore the empty string, not null. So omit an element entirely (or if supported use xsi:nil) to indicate a null. Coercions to boxed primitive types may map the empty string to null, but support for coercions to non-boxed primitives may mean rather that it maps to a default value (or even an error!).
please avoid using the xsi:nil facility for now, since I am playing with a simple hand-crafter XML reader
there will probably also be some out-of-band mechanism for specifying default packages, and also for non-standard element name <-> class mappings.
missing elements => null or undefined.
the javatype attribute is only ever required if boxed primitive types are used in Object place-holders and the particular type (rather than String) is important. I.e. not usually.
there may be the option to encode simple single-valued properties as attributes; not sure, though, since it means people have to think which are valid as attributes and which as elements.
if we have to deal with binary data it will be base64 encoded (not nice to do by hand :-)) At present this will just be a normal array of the decimal values of the bytes, i.e. extremely inefficient!
restricted xml characters in text values will need to be escaped to character or other standard entity references (e.g. '<', '&'), or use CDATA sections.
i suppose that object references should be done using XML ID/IDREF attributes, but i'd rather avoid this altogether and so may well not support this.

Note: I think that this should work in J2ME aswell.

See sample program to read such a file: equip2.core.test.j2se.XmlReader

Known issues

floats and doubles!! not yet supported due to cross-platform (J2ME) implementation (also in Hessian and Array support!)

Change log

2006-04-18

change to array/set example; added nil, hashtable & complex property examples

2006-04-07

This document created