The XMLInstantiator was developed to instanciate Model Elements in a very convinient way from a XML document. Input for this instantiator is simply an XML file. From the XML nodes of this file the instantiator creates Elements, attributes of these nodes are copied to the elements' properties.

How does the XMLInstantiator map XML nodes to metaclasses?

For each node the XMLInstantiator tries to resolve a metaclass by the node's name and instantiates it. For any node that cannot be mapped to a specific metaclass the instantiator creates an instance of org.openarchitectureware.core.meta.xml.GenericModelElement.

How is the structure of a XML document mapped to metaclasses?

As you know XML documents are organized in a hierarchy. The XMLInstantiator creates a model that builds a hierarchy of elements. The elements use aggregation relations to build the structure. The aggregations can have 0..1 or 0..n multiplicity. Dependent on the kind of multiplicity metaclasses have to provide Setter (setXXX()) or Adder (addXXX()) methods.

Mapping XML nodes to metaclasses

To instantiate a specific metaclass by the name of a node there a simple mapping mechanism can be used. Metaclasses usually are defined in some package. To define in which packages metaclasses can be found Prefix objects are used. Besides the definition of the package name by the property classnamePrefix it is possible to supply a prefix string used that each metaclass has.

Suppose you want to create elements of type meta.MMMyNode from nodes named then you have to use a Prefix object as follows: new Prefix("meta", "MM")

How do metaclasses have to be implemented so that the XMLInstantiator can use them?

Like any other metaclass all classes have to extend Element. To apply the document's structure classes whose XML nodes can contain body information must have Setter (for to-one aggregations) or Adder methods (for to-many aggregations).

An Example

The following example is taken from the Unittest of class XMLReader, which is used by the XMLInstantiator.

The model is really simple:

<SomeRootElement>
	<ClassA id="1">
		<ClassB testprop="abcd" unknownprop="1234"/>
		<ClassB /> <!-- empty B -->
	</ClassA>
	<ClassA id="2">
	</ClassA>
</SomeRootElement>

The test knows two metaclasses MMClassA and MMClassB. Of course these match to the XML elements. The Root element has no matching metaclass and therefore is mapped to GenericModelElement.

In the example ClassA elements can aggregate ClassB elements. Therefore the metaclass MMClassA must define an Adder method (and a Getter of course, too):

public class MMClassA extends CustomModelElement {
   ...
	public void addClassB (MMClassB instance) { ... }
		public ElementSet ClassB () { ... }
	...
}

Release 3.0

As of release 4 some packages and properties changed. The following table shows what you have to replace by other strings.

Release 4.0	Release 3.0
org.openarchitectureware.core.meta.xml.GenericModelElement	genfwutil.generic.GenericModelElement