EQUIP2 XML encoding
Chris Greenhalgh, 2006-04-07
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.
A representative example of a class encoded in the proposed encoding
follows (from the Day of the Figurines 2 development work-in-progress):
<objects defaultPackage="dof2.db" [optional] >
<Player [ie class name without package] package="dof2.db" [optional]>
<ID [ie property name]>P1_nick</ID>
<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)]
<fullName [NB value is the empty string, not null] />
<map [i.e. hashtable]>
<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>
<Person [another person...] >
<!-- the usual XML comment(s) -->
- 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
- floats and doubles!! not yet supported due to cross-platform
(J2ME) implementation (also in Hessian and Array support!)
- change to array/set example; added nil, hashtable & complex