Ganymede Object Data Import/Export Definition in XML

While the Ganymede server is capable of expressing its schema definition information in the <ganyschema> section of its XML file, this aspect of Ganymede's XML support is bound to be much less used than the data dumping and loading support. This section discusses the <ganydata> element that may be present in the Ganymede XML file format.

<ganydata>
The <ganydata> element is a container for object data to be updated on the server. When exported, the <ganydata> element contains a complete dump of the server's data state. When imported, the <ganydata> element contains a collection of <object> elements which specify objects to be created, edited, inactivated, or deleted. [Example] , [Top]
Parent(s) Children
NONE <object>
Attributes

NONE
 

The <ganydata> element contains a series of <object> elements, each one corresponding to an object in the Ganymede database. The <object> element itself may contain one element for each field in the object. The open tag for the object element as exported contains possibly four attributes, those being type (required), id, num, and action.

<object>
The <object> element contains data for a single object. When exported, the <object> element contains a complete dump of the object's state, minus the historical fields (last modification data, etc.).When imported, the <object> element contains a collection of field elements whose contents are to be transmitted to the server to update the object identified by the <object>'s attributes. [Example] , [Top]
Parent(s) Children
<ganydata> Various field elements, each with a unique tag name based on the name of the corresponding server field
Attributes

type
The name of the type this object belongs to. This string is case sensitive and must match the name attribute for the type's <objectdef> element, which is the object's type name with underscores substituted for spaces.
id
An optional identifier string for this object, unique among objects of this type within the <ganydata> element in this XML file. If this string is not present, the num attribute becomes mandatory. The id attribute is used for two purposes; the first is to identify an object on the server to be edited, inactivated or deleted if the action attribute specifies these actions. This may only be done if objects of this type on the server have unique and determinable labels. The second is to act as a target for <invid> elements within the XML file to use to refer to <object> elements that are created during the XML file processing.
num
An optional object number for this object, unique among objects of this type on the server. If this number is not present, the id attribute becomes mandatory. If both the id and num attributes are present, the id attribute takes precedent. The number contained in this attribute corresponds to the Invid object number for the object designated by this <object> element. The num attribute is used to select pre-existing objects on the server for editing, inactivation, or deletion. If this <object> has an action attribute value that would cause a new object to be created on the Ganymede server, the num attribute is simply ignored.
action
The action attribute is optional, and plays a role only in XML data importing. If the action attribute is present, it may contain one of four strings:
  • create
  • edit
  • inactivate
  • delete

If there is no action attribute specified at import time, the <object> element will be created if there is no object already on the server that matches the id or num object identifying attributes. Otherwise, the pre-existing object on the Ganymede server matching the identifying attributes will be checked out for editing.

If the action attribute is present and contains "create", the <object> element will cause the Ganymede xmlclient to create a new object, even if an object of the same type that matches the given id attribute already exists on the server. In addition, in such cases all <invid> elements in the XML file with matching type and id attributes will be interpreted to be referring to the newly created <object> element and not any pre-existing object on the server that might match those identifying attributes.

If the action attribute is present and contains "edit", the <object> element will cause the Ganymede xmlclient to seek to check the object out for editing from the server. If no object exists on the server matching the id attribute, an error will be displayed and xmlclient will abort the transaction.

In the unspecified, "create", and "edit" cases, the object element will typically contain a set of field elements. In the "inactivate" and "delete" cases, the <object> element must be empty, and the xmlclient will simply attempt to inactivate or delete the object identified by the id or num attributes.

Aside from the special case of object inactivation or deletion, all <object> elements in a <ganydata> section will contain a set of elements that correspond to fields in the object to be created or edited on the server. The elements for these fields have no fixed tag name. Instead, each field element will start with an open tag that is named according to the name of the field, with spaces transformed into underscores.

For instance, a record to change the values of the "Room", "Groups", "Home Group" and "Email Aliases" fields in a pre-existing object on the server would be represented in the XML file as:

  <object type="User" id="broccol" action="edit">
    <Room>S321</Room>
    <Groups>
        <invid type="Group" id="omssys"/>
        <invid type="Group" id="omsnet"/>
    </Groups>
    <Home_Group><invid type="Group" id="omssys"/></Home_Group>
    <Email_Aliases>
        <string val="abbey"/>
        <string val="jonabbey"/>
    </Email_Aliases>
  </object>

An <object> element contains nothing but such field elements, all of which lack any sort of attributes. The field elements themselves, however, will contain a variety of kinds of elements, depending on the field type. In the above example, the "Room" field is a scalar String field, the "Groups" field is a vector Invid/object reference field, the "Home Group" field is a scalar Invid/object reference field, and the "Email Aliases" field is a vector String field.

In the above example, the Groups and Email_Aliases vector field elements both contain a couple of items. These items will be added to those fields if they are not already present, but the xmlclient will not remove any other items which may already be in those fields.

If you want to assure that after xmlclient finishes its work that there will only be a given list of items in a vector field, you need to do this:

  <object type="User" id="broccol" action="edit">
    <Room>S321</Room>
    <Groups>
        <set>
            <invid type="Group" id="omssys"/>
            <invid type="Group" id="omsnet"/>
        </set>
    </Groups>
  </object>

In this example, the <set> container element will force the xmlclient to set the Groups field to contain only the two items listed, adding or removing items as necessary.

You can also manually add or remove individual items, using <add>, <addIfNotPresent>, and <delete>:

  <object type="User" id="broccol" action="edit">
    <Room>S321</Room>
    <Groups>
        <add>
            <invid type="Group" id="omsovr"/>
        </add>
        <delete>
            <invid type="Group" id="omsnet"/>
        </delete>
    </Groups>
  </object>

This will cause the omsovr group to be added and the omsnet group to be removed. You can have as many <add>, <addIfNotPresent> and <delete> containers as you want within a vector field, but <add>, <addIfNotPresent> and <delete> are not compatible with <set>. If you use <set>, you may not use <add>, <addIfNotPresent> or <delete> as well.

If you don't specify <add>, <addIfNotPresent>, <delete>, or <set>, the xmlclient will treat the items as belonging to an <addIfNotPresent> container. For this reason, the following is not allowed:

  <object type="User" id="broccol" action="edit">
    <Room>S321</Room>
    <Groups>
        <invid type="Group" id="omsovr"/>
        <set>
            <invid type="Group" id="omssys"/>
            <invid type="Group" id="omsnet"/>
        </set>
    </Groups>
  </object>

because the omsovr element is considered to be in an <addIfNotPresent>, which may not co-exist with a <set> in a single field element.

There are presently nine different types of data fields supported by the Ganymede server, and each of these types has its own rules as to what kinds of elements are allowed within the field element and how they may be structured. For the most part, these rules are very similar for all field types, with just the value carrying element type differing. The following table shows the data carrying element types that correspond to the nine field types.

<string>
The <string> element contains data for Ganymede string fields, but is mandatory only for vector string fields. The <string> element is not necessary for scalar string fields, which support simply placing the content to be placed in the string field directly between the field element's open and close tags. If the <string> element is used for string field content, it must be empty. [Example] , [Top]
Parent(s) Children
<object> NONE
Attributes
val
The contents of the mandatory val attribute actually holds the string value corresponding to this <string> element. As with all XML attributes, double quote characters must be replaced by '&quot;', naked ampersands must be replaced by '&amp;', and anything goes otherwise, including embedded newlines.
Example
<string val="broccol"/>
<boolean>

The <boolean> element is an optional data element for Ganymede boolean fields. Since Ganymede boolean fields are always scalar, you can simply place true, t, false or f (of whatever capitalization) between the field's start and end tags. If you do use the older <boolean> element as a data container, the <boolean> element must be empty.

[Example] , [Top]
Parent(s) Children
<object> NONE
Attributes
val
The contents of the mandatory val attribute holds a string corresponding to the value of this <boolean> element. "1", "true", "t", "yes", and "y", of whatever capitalization, all correspond to a true value. Any other value corresponds to a false value. Note that this is a looser standard than is allowed if you use a text string to represent the true or false value outside of the <boolean> element's val val attribute. In that case, you must use true, t, false, or f, of whatever capitalization.
Example
<boolean val="true"/>
<int>

The <int> element is an optional data element for Ganymede numeric fields. Since Ganymede numeric fields are always scalar, you can simply place a 32 bit signed integer value between the containing field's start and end tags. If you do use the older <int> element as a data container, the <int> element must be empty.

[Example] , [Top]
Parent(s) Children
<object> NONE
Attributes
val
The contents of the mandatory val attribute actually holds the integer value corresponding to this <int> element. This attribute can hold integer values in the range -4294967296 to 4294967295. The only characters allowed in this attribute value are the numeric digits and the minus sign. This same range holds if you skip the <int> element and just place the numeric value between the start and end tags of the containing field element.
Example
<int val="12042"/>
<float>
The <float> element contains a 64 bit floating point value, corresponding to the IEEE 754-1985 specification, for use with Ganymede float fields. As float fields are scalar in Ganymede, only one <float> element at a time may be contained in a float field element. The <float> element must be empty. [Example] , [Top]
Parent(s) Children
<object> NONE
Attributes
val
The contents of the mandatory val attribute actually holds the 64 bit float value corresponding to this <float> element. This attribute can hold floating point values corresponding to the 64 bit floating point value specified by IEEE 754-1985 specification. The text of this attribute must conform to the rules specified in the java.lang.Double class, which generally corresponds to normal rules of ASCII floating point number representation, with support for numbers of the form 6.04E+25 in scientific notation for very large or very small numbers.
Example
<float val="3.141596254"/>
<ip>
The <ip> element contains an IPv4 or IPv6 address. IP fields may be scalar or vector in Ganymede. The <ip> element must be empty. [Example] , [Top]
Parent(s) Children
<object> NONE
Attributes
val
The contents of the mandatory val attribute holds an IPv4 string in standard dotted decimal form, or an IPv6 string, in any RFC 1884 format. The Ganymede server will decide, based on its configuration, whether an IPv6 address will be accepted. Even if IPv6 addresses are supported, IPv4 strings will always be accepted, given the compatibility engineering the IPv6 folks have carried forth.
Example
<ip val="127.0.0.1"/>
<date>
The <date> element contains a Java date value, which is effectively a 64 bit time stamp with millisecond resolution centered at Midnight, January 1, 1970, UTC. As date fields are scalar in Ganymede, only one <date> element at a time may be contained in a field element. The <date> element must be empty. [Example] , [Top]
Parent(s) Children
<object> NONE
Attributes
val
The contents of the val attribute contains a human readable representation of the time stamp held in this <date> element. The val attribute takes data strings of the form "Sun, 03 Dec 1995 00:00:00", in which case the date is interpreted in the local timezone of the machine running the xmlclient or "Sun, 03 Dec 1995 00:00:00 CDT", in which the date will be interpreted by the specified timezone. The standard UNIX date format "Tue Jul 11 01:18:21 CDT 2000" is also supported. The precise form of date val string that may be parsed by the xmlclient, in particular the characters of the date and month, may differ according to the default Java locale of the JVM running the xmlclient. To avoid any possibility for imprecision, it may be necessary to instead use the timecode attribute.
timecode
The contents of the timecode attribute contains a 64 bit signed integer, corresponding to the number of milliseconds before or after Midnight, January 1, 1970, UTC. In order to use a UNIX-style 32 bit timecode to fill in the timecode attribute, you can simply multiply a 32 bit timecode by 1,000.
Example
<date val="Wed 28 Jun 2000 13:13:02" timecode="962215982000"/>
<password>
The <password> element contains a Java password value. As password fields are scalar in Ganymede, only one <password> element at a time may be contained in a field element. The <password> element must be empty. The <password> element may contain any or all of the six optional attributes, plaintext, crypt, md5crypt, apachemd5crypt, lanman and ntmd4. If the plaintext attribute is present, all other hashes will be ignored, and the Ganymede server will generate new hashes as needed from the plaintext given. If none of the optional attributes are present, the password field will be cleared. All of these options are explained below. [Example] , [Top]
Parent(s) Children
<object> NONE
Attributes
plaintext
This attribute, if present, contains a password string in plain text. The client will transmit this password to the server, which will generate any needed hash formats according to the schema configuration for this field. If plaintext is specified, all other hash information in this element will be ignored.
crypt
This attribute, if present, contains a password string pre-hashed in UNIX crypt() format. The client will transmit this password to the server, and will clear any pre-existing plain text information stored in this field in the server.
md5crypt
This attribute, if present, contains a password string pre-hashed in FreeBSD-style md5Crypt() format. The client will transmit this password to the server, and will clear any pre-existing plain text information stored in this field in the server.
apachemd5crypt
This attribute, if present, contains a password string pre-hashed in Apache-style md5Crypt() format. The client will transmit this password to the server, and will clear any pre-existing plain text information stored in this field in the server.
lanman
This attribute, if present, contains a password string pre-hashed in the LANMAN encoding used by older versions of Windows networking. This hash format is one of the two password encryption formats used by the Samba password file. The client will transmit this password to the server, and will clear any pre-existing plain text information stored in this field in the server.
ntmd4
This attribute, if present, contains a password string pre-hashed in the Unicode-md4 encoding used by Windows NT and Windows 98 and later. This hash format is one of the two password encryption formats used by the Samba password file. The client will transmit this password to the server, and will clear any pre-existing plain text information stored in this field in the server.
Example
<password crypt="nxGots4NO.BJY" md5crypt="$1$o8/.....$f398vNQ51gnzf"/>
<invid>
The <invid> element contains a Ganymede object reference value, which is used to identify an object pointer in an invid field on the Ganymede server. The <invid> element must be empty. [Example] , [Top]
Parent(s) Children
<object> NONE
Attributes
type
This attribute is mandatory, and contains an XML-encoded (underscores for spaces) object type string, with proper capitalization, to identify the kind of object this <invid> element is pointing to.
id

This attribute, if present, contains a string that is meant to uniquely identify a target object of type matching the value of the type attribute in this <invid> element on the Ganymede server. The targeted object may exist prior to XML file processing on the Ganymede server, or it may be created by processing of other <object> elements in the XML file by the xmlclient. If an <object> element of matching type with matching id is defined with an action attribute value of create, then all <invid> elements in the XML file with that type and id will point to the newly created object, and not any pre-existing object on the server that shared that type and id.

Not all types of objects on the server will have be addressable by id. Some types of objects, such as embedded objects within user or system objects, may not have a defined unique label field. This should be by far the exception rather than the rule, but for such cases, objects on the server may be addressed using the num attribute rather than the id attribute.

num
This attribute, if present, holds an object number on the Ganymede server, and is used to address a pre-existing object on the server. This attribute should only be used when you explicitly want to address an object on the server, regardless of whatever other activity the <ganydata> element in the XML file defines.
Example
<invid type="User" id="broccol"/>

Example

For example, a user object from the GASH schema kit might be represented in an XML file in the following fashion: 

      <object type="User" id="broccol" num="627">
        <Username>broccol</Username>
        <UID><int val="12003"/></UID>
        <Password><password crypt="j8hgwcyw232Jo"/></Password>
        <Account_Category><invid type="User_Category" id="normal"/></Account_Category>
        <Full_Name>Jonathan Abbey</Full_Name>
        <Social_Security>574743325</Social_Security>
        <Division>CSD</Division>
        <Room>S321</Room>
        <Office_Phone>3199</Office_Phone>
        <Home_Phone>335-7681</Home_Phone>
        <Groups>
          <invid type="Group" id="omsprl"/>
          <invid type="Group" id="omsovr"/>
          <invid type="Group" id="omssys"/>
          <invid type="Group" id="genweb"/>
          <invid type="Group" id="gendof"/>
          <invid type="Group" id="omsnet"/>
          <invid type="Group" id="ganycvs"/>
          <invid type="Group" id="omjrst"/>
        </Groups>
        <Home_Group><invid type="Group" id="omssys"/></Home_Group>
        <Login_Shell>/bin/tcsh</Login_Shell>
        <Home_Directory>/home/broccol</Home_Directory>
        <Admin_Personae>
          <invid type="Admin_Persona" id="broccol:GASH Admin"/>
          <invid type="Admin_Persona" id="broccol:supergash"/>
        </Admin_Personae>
        <Netgroups>
          <invid type="User_Netgroup" id="omg-u"/>
          <invid type="User_Netgroup" id="omguse-u"/>
          <invid type="User_Netgroup" id="supad1-u"/>
        </Netgroups>
        <Directory_Volume>
        <object type="Embedded_Automounter_Map_Entry" id="103" num="103">
          <Automounter_Map><invid type="Automounter_Map" id="2"/></Automounter_Map>
          <NFS_Volume><invid type="NFS_Volume" id="23"/></NFS_Volume>
        </object>
        </Directory_Volume>
        <Email_Aliases>
          <string val="jonabbey"/>
          <string val="abbey"/>
          <string val="rust-admin"/>
        </Email_Aliases>
        <Signature_Alias>jonabbey</Signature_Alias>
        <Email_target>
          <string val="broccol@arlut.utexas.edu"/>
          <string val="broccol@csdsun7.arlut.utexas.edu"/>
        </Email_target>
        <Owner_list>
          <invid type="Owner_Group" id="OMG"/>
        </Owner_list>
      </object>
Jonathan Abbey
Last modified: Thu Mar 28 22:23:59 CST 2002