Hydrate Cookbook

   Home
   Getting Started
   Download
   Documentation
   API Docs
   Reference
   FAQ
  EJB 3.0 Support
  Contact
   Viewpoint

XML Definition File Reference

The file that defines the object model and on which all generated code is based is in XML format. In the following sections, the heading relates to the name of the element in the definition file. If the element is itself a sub-element of other elements, those elements are shown in brackets before the element name. The tables that follow show the attributes (of the element) that are valid with a description of the meaning of each and an indication as to what the default value (if any) is and whether the attribute can be overridden in from 'Include'd documents. Where there is no default value (<no default> specified), you must specify a value for this attribute.

Family

The family element is the top level element of the XML definition document. It declares a set of classes, relationships, enumerations and XML schema definitions that make up the domain data model of the system to be modelled.

Attribute	Description	Default	Can Ovr
name	The name of the family of classes (or UML diagram). Conventionally this starts with a capital letter.	<no default>	No
namespace	The namespace of this family. This follows Java package name conventions - and Java classes will be generated into a package with this name.	<no default>	Yes
tablespace	The name of a partition in the database where data for this table should be stored. This may be important for some database architectures, e.g. DB2.

(Family).Include

The Include element indicates another XML definition document that this document is overriding. You can include several documents into the same overriding document. You can also have several levels of included document.

Attribute	Description	Default	Can Ovr
file	The name of the file to be included relative to the directory of this file. The content of the given file will be overridden by the content of this file.	<no default>	N/A

(Family).Class

This Element declares a class within the UML class diagram. It defines the name of the class, its relationship to other classes as part of an inheritance hierarchy, a list of its scalar attributes and their types (but not its references to other objects), a list of methods that it should support and a list of keys that can be used to index it.

Attribute	Description	Default	Can Ovr
name	The name of the UML class. Conventionally this starts with a capital letter	<no default>	No
extends	The name of the class that this class extends in the UML class model. This name must match the name of another class in the family.	<none>	Yes
discriminator	A short string that indicates that is used in the database to indicate instances of this class in the database. Since the same table can store instances or parts of instances of several possible classes in the class hierarchy this helps to determine which object should be constructed	<numeric value>	Yes
implements	A comma separated list of interface names that this class should implement. The generated bean interface will be declared as implementing this list of interfaces	<none>	Can add to list
tablespace	The name of a partition in the database where data for this table should be stored. This may be important for some database architectures, e.g. DB2. This overrides the value set in the family.	<none>	Yes
abstract	A Boolean attribute indicating whether this class should can be instantiated. A true value indicates that only classes derived from this may be instantiated	No	Yes
comment	Free form text describing the function of this class in the model. It is highly recommended that this attribute be supplied	<none>	Yes

(Family.Class).Attribute

The Attribute element defines a scalar attribute belonging to a class.

Attribute	Description	Default	Can Ovr
name	The name of the attribute. Conventionally this starts with a lower case letter and follows the camelCase convention.	<no default>	No
type	The type of the attribute. See the table below for a list of possible types	<no default>	No
mandatory	True if this attribute must always be provided for the model to be consistent. Optional parameters are useful for attributes that do not have a value in their normal domain for certain legal states of the object. An example might be an attribute "landed At" in an object representing an airline flight. Before the flight has landed, it is perfectly legal for this attribute not to be set and hence it is optional in the model. Note that this is different from the ability to not load selected attributes from the database. All attributes have the ability to have a not loaded state whether they are mandatory or optional.	mandatory	Yes
persistent	True if this attribute has a persistent representation in the database or false if it represents transient state or can be calculated from other values	No	Yes
size	Some attribute types (see table below) require an additional size parameter to be specified	<type-specific>	Yes
precision	Some attribute types (see table below) require an additional precision parameter to be specified	<type-specific>	Yes
comment	Free-form text describing the function of this attribute in the class. It is highly recommended that this attribute be supplied.	<none>	Yes

(Family.Class).Method

The Method element defines a method belonging to a class.

Attribute	Description	Default	Can Ovr
name	The name of the method. Conventionally this starts with a lower case letter and follows the camelCase convention.	<no default>	No
type	The return type of the method. See the table below for a list of possible types.	<no default>	No
abstract	True if this method should not be implemented in the generated implementations of the class. The method will be declared as abstract and an implementation must be supplied by the user in a derived class.	No	Yes
throws	A list of fully qualified exception names that this method can throw. The method signature in the bean interface as well as the generated method stub will all be written as throwing this list of exceptions.	<none>	Yes, adding to list
deprecated	This flag is set to true if the method is to be declared as being deprecated.	No	Yes
comment	Free-form text describing the function of this method in the class. It is highly recommended that this attribute be specified.	<none>	Yes

(Family.Class.Method).Parameter

The Parameter element defines a parameter of a method including its name and its type.

Attribute	Description	Default	Can Ovr
name	The name of the parameter. Conventionally this starts with a lower case letter and follows the camelCase convention.	<no default>	No
type	The type of the parameter. See the table below for a list of possible types.	<no default>	No
comment	Free-form text describing the function of this parameter in the method call. It is highly recommended that this attribute be specified.	<none>	Yes

(Family.Class).Key

A key defines a set of fields that can be used to uniquely identify an instance of its containing class.

Attribute	Description	Default	Can Ovr
name	The name of the key. This usually, but not always starts with the name of the class it is a key of. The key name <ClassName>PrKey is reserved for use by the code generator (unless a primary key is supplied). Conventionally this name starts with a capital letter.	<no default>	No
primary	This value is true if this is the primary key for the class. Up to one key in the class can be labelled as primary. If none is so labelled, a primary key will be generated.	<no default>	No
disabled	True if this key is disabled. This can be used to suppress keys from classes that were "included" into this model.	No	Yes
comment	Free-form text describing the function of this method in the class. It is highly recommended that this attribute be specified.	<none>	Yes

(Family.Class.Key).Member

This element defines the member of a key.

Attribute	Description	Default	Can Ovr
name	The name of the parameter. This name must match exactly one of the attributes or references declared to be part of the class in which this key is a member. Only -to-one references can be part of a key, but note that they are declared outside of this class in a separate Relationship declaration.	<no default>	No

(Family).Relationship

A Relationship represents a connection (one-to-many, many-to-many or one-to-one). Note that relationships are defined outside the scope of any class.

Attribute	Description	Default	Can Ovr
name	The name of the relationship. This must always be supplied and must be unique in the model. If in doubt, the concatenated names of the classes involved in the relationship is a good name, but you may need to include all or part of the reference names to make this unique.	<no default>	No
comment	Free-form text describing the function of this relationship in the model. It is highly recommended that this attribute be specified.	<no default>	Yes

(Family.Relationship).Reference

This element represents one direction of a relationship. There are always exactly two references as sub-elements of a Relationship, though one or other may not be navigable.

Attribute	Description	Default	Can Ovr
name	The name of the reference. Conventionally this starts with a lower case letter and follows the camelCase convention.	<no default>	No
toObject	The name of the object that this reference points to. This should be the name of a class that exists in this UML definition file. This also (implicitly) the object that the other reference comes from.	<no default>	No
owned	True if this reference owns the instance of the target object. This ownership affects the way that deletes are cascaded through the object model.	No	Yes
navigable	True if this reference is navigable. Getter and setter methods will be generated in the bean interface and object implementations for each navigable reference.	Yes, for to-one references, No, for to-many	Yes
multiplicity	This is one of the following text strings "1", "0..1" or "0..*". Combined with the multiplicity setting for the other reference in this relationship, it determines whether this is a one-to-one, one-to-many or many-to-many relationship and whether the to-one relationships are optional.	<no default>	Yes
key	This is the name of a key to use in the relationship, which must be a valid key name from this definition file. This is ignored where the multiplicity or this reference is "0..*" and is "1" or "0..1" on the other reference. In all other cases, it determines which primary key is used in the reference and therefore which foreign key is used in the referencing table (many-to-one) or keys are used in the linking table (many-to-many).	<the primary key of the object>	Yes

(Family).Enumeration

An enumeration represents a data type that may have one of an enumerated set of values.

Attribute	Description	Default	Can Ovr
name	The name of the enumeration. This name will become the name of the Java class used to represent the enumeration. By convention, this should start with a capital letter.	<no default>	No
type	The type of the enumeration - see table below. This is the type of the code value that is written to the database or to the XML document. This is usually a String or a PositiveInteger.	<none>	No
size	The number of characters in the String - required for String types.	<none>	Yes
comment	Free-form text describing the usage of this enumeration. It is highly recommended that this attribute be specified.	<none>	Yes

(Family.Enumeration).Option

This element represents one possible enumerated value.

Attribute	Description	Default	Can Ovr
code	The short code of the enumeration. This is the representation of the enumeration when it appears in the database or in an XML document. For example, for a "marital status" enumeration, this might be "M", "S", etc.	<no default>	No
display	The full name of the enumeration. This should be a brief, but description name for the enumeration value. There is no maximum length, but try to keep it below around 40 characters. For example for a "marital status" enumeration, this might be "Married", "Single", etc.	<no default>	Yes
comment	Free-form text describing the usage of this value. It is highly recommended that this attribute be specified.	<none>	Yes

(Family).XMLSchema

An XML schema definition declares a "route" through the object model that should be transformed into

Attribute	Description	Default	Can Ovr
name	The name of the XML schema. The Java file name and XSD schema name will have this name with XML appended. By convention, this should start with a capital letter.	<no default>	No
comment	Free-form text describing the usage of this XML schema. It is highly recommended that this attribute be specified.	<none>	Yes

(Family.XMLSchema).Element (1)

The following table shows attributes that are valid for the first element(s) nested inside XMLSchema.

Attribute	Description	Default	Can Ovr
asMember	This is the name of the element or elements at the first level of the XML document.	<no default>	No
collection	This method is true if this element may be repeated more than once (is a collection)	No	Yes
class	The name of the class in the model, instances of which can be written at this point in the XML document.	<no default>	No
key	The name of the key to use in uniquely defining this object. The members that are part of the key will appear as attributes of the object element. You can indicate that the element has no key by setting this to "", which is different from not specifying a value where it uses the primary key.	<primary key>	Yes
attributes	A list of attributes that should/should not be written to/read from the XML document. See below for attribute specifications.	"*"	Yes
keyOnly	True if we only want to write out the key of this object. Not valid if the key is not set or if this element has sub-elements.	No	Yes
failIfNot-Loaded	A list of attributes for which writing should fail with an error if they are not populated. See below for the format of this list. Attributes that are not in this list, which are not populated will result in no element being written (though see coerceToNotSet).	"+"	Yes
coerceTo-NotSet	This attribute is true not loaded values that are optional are to be written as not set values. Not loaded attributes do not result in an element being written for that attribute (or result in an exception being thrown if failIfNotLoaded is set for that attribute). Not set attributes write the element out as null - using the XSD "nillable" specification.	No	Yes
checkDb	This attribute should be set to true to have the XML reader check the database for objects before creating new ones. If you have a database cache of the data you are reading from XML, setting this value will cause this to be checked first for the object.	No	Yes

(Family.XMLSchema.Element<.Element>).Element (2)

The following table shows the attributes that are valid for subsequent elements nested inside other Elements.

Attribute	Description	Default	Can Ovr
asMember	This field is the name of the member that this element represents. This name must match one of the references in the class of the enclosing member. In the case that the enclosing member has an inheritance hierarchy underneath it, this name can be of the form <Class>.<name>, where <Class> is the name of one of the classes in that hierarchy and <name> is the name of a reference in that class.	<no default>	No
class	The names of the classes in the model, instances of which can be written at this point in the XML document. This attribute is optional as it can normally be determined from the asMember attribute however, if that asMember class has an inheritance hierarchy underneath it, you can use this member to specify the list of concrete classes that are valid at this point in the document.	<member's class, plus hierarchy below it>	No
key	The name of the key to use in uniquely defining this object. The members that are part of the key will appear as attributes of the object element. You can indicate that the element has no key by setting this to "", which is different from not specifying a value where it uses the primary key.	<primary key>	Yes
attributes	A list of attributes that should/should not be written to/read from the XML document. See below for attribute specifications.	"*"	Yes
keyOnly	True if we only want to write out the key of this object. Not valid if the key is not set, or if this element has sub-elements.	No	Yes
failIfNot-Loaded	A list of attributes for which writing should fail with an error if they are not populated. See below for the format of this list. Attributes that are not in this list, which are not populated will result in no element being written (though see coerceToNotSet).	"+"	Yes
coerceTo-NotSet	This attribute is true not loaded values that are optional are to be written as not set values. Normally, not loaded attributes do not result in an element being written for that attribute (or result in an exception being thrown if failIfNotLoaded is set for that attribute). Not set attributes write the element out as null - using the XSD "nillable" specification.	No	Yes
checkDb	This attribute should be set to true to have the XML reader check the database for objects before creating new ones. If you have a database cache of the data you are reading from XML, setting this value will cause this to be checked first for the object.	No	Yes
flatten	Set to true for non-collection members if you don"t want to put the data in its own element. For example, if you have an "AirlineFlight" object which has a to-one reference to "Aircraft", by specifying the Aircraft element as flattened, the attributes of Aircraft appear within and at the same level as the attributes of Airline flight	No	Yes

Attribute List Definition

An Attribute List Definition defines a comma separated list of attributes of an XML Schema definition member class. In essence, this is just a list of classes but there are a few special values:

A "*" means all attributes
A "+" means all mandatory attributes
A "-" in front of an attribute name excludes an attribute

So, for example:

failIfNotLoaded="+, landingTime, -name"

sets the "failIfNotLoaded" attribute so that failure occurs for all mandatory attributes, plus the attribute called "landingTime", but not including the attribute called "name".

Class List Definition

In the class attribute of the XML schema element, we sometimes need to specify more than one class where the class intended may be one of a set of classes in a hierarchy. In general specifying a single class name "MyClass" means this class and everything derived from it. You can also specify two classes "MyClass, MyOtherClass" provided they have a common base class. This notation means MyClass and everything derived from it and MyOtherClass and everything derived from it.

If you don"t want to pick up the entire class hierarchy, you can prefix the class name with an exclamation point "!". For example "!Person, Manager" means the Person class and the Manager class and everything below it i.e. none of the classes between Person and Manager (e.g. Employee) would be included.