thinwire.util
Class XOD

java.lang.Object
  thinwire.util.XOD

public final class XOD
extends java.lang.Object

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.

Constructor Summary

XOD()
Create a new XOD.

XOD(java.lang.String uri)
Create a new XOD.

Method Summary

void	execute(java.lang.String uri) Executes a XOD file, adding the created objects to the map and list.
java.util.Map<java.lang.String,java.lang.Class>	getAliasMap()
java.lang.String	getObjectId(java.lang.Object o) Gets the id that is associated to the specified object.
java.util.Map<java.lang.String,java.lang.Object>	getObjectMap() The object map contains references to previously defined objects identified by id.
java.util.List<java.lang.Object>	getObjects()
java.util.Map<java.lang.String,java.lang.String>	getPropertyMap()
java.util.List<java.lang.Object>	getRootObjects()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XOD

public XOD()

Create a new XOD.

XOD

public XOD(java.lang.String uri)

Create a new XOD.

Parameters:

uri - the name of the XML Object Document file to execute.

Method Detail

getAliasMap

public java.util.Map<java.lang.String,java.lang.Class> getAliasMap()

getPropertyMap

public java.util.Map<java.lang.String,java.lang.String> getPropertyMap()

getObjectMap

public java.util.Map<java.lang.String,java.lang.Object> getObjectMap()

The object map contains references to previously defined objects identified by id. Typically, it will map an ID found in the XOD to an object.

Returns:

the object Map

getObjects

public java.util.List<java.lang.Object> getObjects()

getRootObjects

public java.util.List<java.lang.Object> getRootObjects()

getObjectId

public java.lang.String getObjectId(java.lang.Object o)

Gets the id that is associated to the specified object. For this to succeed, the object must be in the object map.

Parameters:

o - the object to retrieve the id for.

Returns:

the id associated to the object, or null if the object is not in the object map.

execute

public void execute(java.lang.String uri)

Executes a XOD file, adding the created objects to the map and list.

Parameters:

uri - the name of the XML Object Document file.