| Xml Object Document (XOD) generates objects from the XML file, and associates them with a Map.
XODs can be used to create instances of plain old java objects (POJO). For example, a Dialog can be
created as follows:
Sample File
Sample File XML
<?xml version="1.0"?>
<xod>
<include file="classes.xml"/>
<Dialog id="dialog">
<title>XOD Demo File</title>
<width>300</width>
<height>200</height>
<children>
<TextField id="name">
<x>90</x>
<y>5</y>
<width>80</width>
<height>25</height>
</TextField>
<Label>
<text>Name:</text>
<labelFor>name</labelFor>
<alignX>RIGHT</alignX>
<x>5</x>
<y>5</y>
<width>80</width>
<height>25</height>
</Label>
</children>
</Dialog>
</xod>
Sample Java Code Using XOD
XOD xod = new XOD();
xod.execute("dialog.xml");
Dialog dialog = (Dialog)xod.getObjectMap().get("dialog");
dialog.setVisible(true);
Sample Alias XML File
The <alias> tag associates a short name with a class name. This content doesn't
have to be separate. Instead of using the <include> tag in the demo file displayed
above, the demo file could have included it directly.
<xod>
<alias name="Button" class="thinwire.ui.Button"/>
<alias name="CheckBox" class="thinwire.ui.CheckBox"/>
<alias name="Dialog" class="thinwire.ui.Dialog"/>
<alias name="Divider" class="thinwire.ui.Divider"/>
<alias name="DropDownGridBox" class="thinwire.ui.DropDownGridBox"/>
<alias name="Frame" class="thinwire.ui.Frame"/>
<alias name="GridBox" class="thinwire.ui.GridBox"/>
<alias name="Image" class="thinwire.ui.Image"/>
<alias name="Label" class="thinwire.ui.Label"/>
<alias name="Menu" class="thinwire.ui.Menu"/>
<alias name="Panel" class="thinwire.ui.Panel"/>
<alias name="RadioButton" class="thinwire.ui.RadioButton"/>
<alias name="RadioButton.Group" class="thinwire.ui.RadioButton$Group"/>
<alias name="TabFolder" class="thinwire.ui.TabFolder"/>
<alias name="TabSheet" class="thinwire.ui.TabSheet"/>
<alias name="TextArea" class="thinwire.ui.TextArea"/>
<alias name="TextField" class="thinwire.ui.TextField"/>
</xod>
Notes on the XOD Tags
<xod>
The <xod> tag is the top level tag. It occurs once and encloses all other
tags.
<include>
The <include> tag allows you to include other XOD XML files within an XOD file.
Use it to reduce duplication. E.g. You can use it to include an alias file like the
one shown above.
<alias>
Many of the tags in the demo listed above can be thought of as
instruction to construct plain old java objects. E.g. The <Button> tag can be thought of as
instruction to build a Button class instance.
In general, an XOD file can contain tags of the form
<com.mypackage.XXXX>
where XXXX is a class, and such a tag can be thought of as an
instruction to create an instance of the XXXX class.
But the full class names are long. To allow for shorter tags in your xod files, you can define an alias:
<alias name="Button" class="thinwire.ui.Button"/>
Once you've included this alias in your file, you can construct
an object using it:
<Button id="button_ok">
<text>OK</text>
<x>73</x>
<y>301</y>
<width>84</width>
<height>30</height>
</Button>
<ref>
Some objects need to be associated with other objects.
E.g. We need a means to indicate that the RadioButtons described in a
container are members of the RadioButton.Group.
We use the <ref> tag to accomplish this.
Object Class Tags
If there's a class with the name "com.mypackage.XXXX", you can include an
<com.mypackage.XXXX> element in your XOD definition. You can also
create an alias for that class and use it in place of the class name.
Component Property Tags - e.g. <width>, <text>, <x>
To specify properties - e.g. location, size, and text - for the components you wish
to build, add property tag elements. In general, if a UI component class has a "setXxxx" method,
you can include an <xxxx> property tag.
E.g. Since the thinwire.ui.Button class has a setText method,
you can specify the text for your button with a <text> element.
<Button id="button_ok">
....
<text>OK</text>
....
</Button>
Property Tag Values
The properties of objects have types. E.g. The text property of the
Button class is of type String, and the x property of the Button class is of type
int. Other standard types are Integer, double, Double, char, Character, long, Long,
boolean, Boolean, float, Float, byte, and Byte.
In the case of these standard types, the XOD class will make the appropriate conversion
while processing a xod file. E.g. When it comes across
<Button id="Search_btn">
.....
<x>73</x>
.....
</Button>
the XOD engine will convert "73" to an int and assign the x property of the
new Button that int value.
In the case of non-literal types, XOD has three special strategies.
First, it will check to see if the class type of the property you are assigning
to has a 'valueOf' method that returns the appropriate type. If it does, it
will call that method and assign the returned value to the property.
E.g. The Label class has an alignX property of type thinwire.ui.AlignX.
This class has a 'valueOf' method. When XOD processes the above demo file and comes across
<Label>
.....
<alignX>RIGHT</alignX>
.....
</Label>
it calls the static 'valueOf' on AlignX, which returns the appropriate constant AlignX.RIGHT.
Second, it will check to see if the class type has a static final field (i.e. constant) that
is named the same as the value specified in the property tag. If it finds a constant, it will
be assed to the property.
Third, it looks for an object defined elsewhere in the XOD, an object
whose id in the XOD matches the property value. If it finds one, it assigns
the object as a value for the property. E.g. When it comes across
<Label>
.....
<labelFor>name</labelFor>
.....
</Label>
then XOD engine discovers that there is a 'name' object defined previously, and it assigns
this object to the Label's labelFor property.
Collection Properties
A component may have a property with a Collection type. E.g. Dialogs have
a getChildren method, and a children property. The children of a Dialog form
a collection.
When an XML element represents a property with a Collection type, the content of
the element represents the members of the collection. E.g. When XOD comes
across
<children>
<Label>
....
</Label>
<Label>
....
</Label>
<Label>
....
</Label>
<Divider>
....
</Divider>
<Divider>
....
</Divider>
<TextField id="name">
....
</TextField>
....
</children>
it constructs Label, Divider, and TextField components and makes these
components children of the Dialog.
author:
Joshua J. Gertzen |
