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 can contain an optional <comment> element describing the transaction to be committed, and a collection of <object> elements which specify the objects to be created, edited, inactivated, or deleted. | |
Parent(s) | Children |
ganymede |
<comment>, <object> |
Attributes | |
None |
The <ganydata> element can contain an optional <comment> element containing text describing the purpose of the transaction to be committed by the Ganymede server on successful processing of the <object> elements. The text in the <comment> element will be included in all email generated by the Ganymede server in response to the transaction, and will be included in all logging related to the transaction.
<comment> | |
The optional <comment> element contains a text string describing the transaction to be performed. Any text contained by this element will be included in all email and logging generated for the transaction committed in response to the processing of the <ganydata> element. The <comment> element will never be generated when dumping data with xmlclient. It is only meaningful when submitting change requests to the Ganymede server. If the <comment> element contains anything other than character data, the contents of the <comment> element will be disregarded. You may not include HTML or other XML-formatted text within the <comment> element. |
|
Parent(s) | Children |
<ganydata> | Character data. |
Attributes | |
None | |
Example | |
<comment>This server was decommissioned three years back, but never removed from Ganymede.</comment> |
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. | |
Parent(s) | Children |
<ganydata> | Various field elements, each with a unique tag name based on the name of the corresponding server field |
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 ten 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 ten 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. | |
Parent(s) | Children |
Various, based on the names of fields in an <object> | None |
Attributes | |
|
|
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. |
|
Parent(s) | Children |
Various, based on the names of fields in an <object> | None |
Attributes | |
|
|
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. |
|
Parent(s) | Children |
Various, based on the names of fields in an <object> | None |
Attributes | |
|
|
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. | |
Parent(s) | Children |
Various, based on the names of fields in an <object> | None |
Attributes | |
|
|
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. | |
Parent(s) | Children |
Various, based on the names of fields in an <object> | None |
Attributes | |
|
|
Example | |
<ip val="127.0.0.1"/> , <ip val="::1"/> , <ip val="::FFFF:127.0.0.1"/>
All of these examples encode a loopback address, in either IPv4 or IPv6 form. |
<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. | |
Parent(s) | Children |
Various, based on the names of fields in an <object> | None |
Attributes | |
|
|
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 eight optional attributes: plaintext, crypt, md5crypt, apachemd5crypt, lanman, ntmd4, ssha, shaUnixCrypt, and bCrypt. If the plaintext attribute is present, all other hashes will be ignored when the client submits a <password> element, 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. If the plaintext attribute is not present but one or more of the hash attributes are, Ganymede will replace any previous information held in this field with information for the hashes you specified. If a Ganymede build process requires hash information that you did not provide when you submitted this <password> element, you may have problems. In general, it is best to pass plaintext information to Ganymede when you want to tell Ganymede about a password change, but you can provide pre-hashed password data to Ganymede if you are comfortable about the limitations you might run into. |
|
Parent(s) | Children |
Various, based on the names of fields in an <object> | None |
Attributes | |
|
|
Example | |
<password md5crypt="$1$o8/.....$f398vnq51gnzf" shaUnixCrypt="$5$saltstring$5B8vYYiY.CVt1RlTTf8KbXBH3hsxY/GNooZaBBGWEc5"/> |
<options> | |
The <options> element is similar to the <permmatrix> element, in that it provides a mapping for object and field types defined in the Ganymede server. While <permmatrix> provides a set of permission bits for each object or field for a Ganymede Role, the <options> element simply provides option strings for each object type and/or field. The main purpose of these option strings is to control what data triggers a Sync Channel, and what data is written out to an XML queue when a Sync Channel build is triggered. Note that the <options> element was introduced in Ganymede 2.0, and is only acceptable in a Ganymede XML file with a version of at least
|
|
Parent(s) | Children |
Various, based on the names of fields in an <object> | Various, based on the names of object and field types defined |
Attributes | |
None | |
Example | |
<options>
This simple example controls synchronization for User objects in a specific Sync Channel. An options element can contain elements for each object type defined in the server's schema, which in turn can contain nested elements for each custom field defined in that object's schema definition. Both the elements corresponding to object types and the elements corresponding to individual field definitions will have a single attribute, option, containing 0, 1, or (in the case of a field element) 2. These values correspond to the NEVER, WHENCHANGED, and ALWAYS elements in the SyncPrefEnum enum class. 0 stands for NEVER, and means that objects of the given type (or fields in an object type's definition) will never be synchronized to the enclosing Sync Channel. 1 stands for WHENCHANGED, and means that the object or field will be synchronized to the Sync Channel if the object or field was changed by a transaction. 2 stands for ALWAYS, which is only applicable for field elements. A field that is configured with a value of 2 will always be included when the containing object is modified by a transaction, whether or not that field was itself changed by the transaction. See the Ganymede 2.0 Sync Guide for more details on the configuration and operation of a Ganymede Sync Channel. Remember, as always with Ganymede object type and field names in XML, any spaces in an object type name or field name will be replaced by underscores when used as an element name in XML dumps and loads. In the above example, <Home_Group> refers to the "Home Group" field in the User object type. |
<permmatrix> | |
The <permmatrix> element contains a mapping of permission values for object and field types defined in the Ganymede server. The <permmatrix> element is present in the Ganymede Role object, and defines what objects and fields a given Role allows access to. As Permission Matrix fields are scalar in Ganymede, only one <permmatrix> element at a time may be contained in a field element. The <permmatrix> element is designed to contain elements for each object type and field that permissions are set for. | |
Parent(s) | Children |
Various, based on the names of fields in an <object> | Various, based on the names of object and field types defined |
Attributes | |
None | |
Example | |
<permmatrix>
This simple example sets permission bits on the User object itself, along with the Username and UID fields defined as part of the User object type. Object and field names contained within a <permmatrix> element are required to have a The reason that the D flag is not enabled for fields is that there is no discrete notion of 'deletion' that applies to fields. Deleting an object is a distinct operation from editing it, but deleting a field and editing a field to set its contents to empty or null amounts to the same thing in Ganymede, so we don't bother tracking delete permissions for fields. Remember, as always with Ganymede object type and field names in XML, any spaces in an object type name or field name will be replaced by underscores when used as an element name in XML dumps and loads. In the above example, <Home_Group> refers to the "Home Group" field in the User object type. |
<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. | |
Parent(s) | Children |
Various, based on the names of fields in an <object> | None |
Attributes | |
|
|
Example | |
<invid type="User" id="broccol"/> |
Embedded Objects |
In addition to the ten field types listed above, there is one unique case, and that is the case of embedded objects. I need to write about this in exhaustive detail.
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"> <Username>broccol</Username> <UID>12003</UID> <Password><password crypt="j8hgwcyw232Jo"/></Password> <Account_Category><invid type="User_Category" id="normal"/></Account_Category> <Full_Name>Jonathan Abbey</Full_Name> <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>