A XML tag node in the element definition represents an element instance. The tag name is the class name of the element, and attributes whose name starts with lowercase character define the field value of the element instance. Attributes whose name starts with uppercase character define the relationship between the tag and its parent tag. For the naming rules, see Attribute naming rules.
There is a special attribute id. It only makes sense to the root tag of one element definition. You can get the element instance by calling the method Element getElement(String id). The subtag represents an internal element instance of its parent tag node, and you cannot get it from id directly. It makes no sense if you define the attribute id to the subtags.
Each XML tag node represents an element instance. This section describes how the BasicElementFactory creates the element instance from XML definition: by default constructor, by constructor, by static factory and by instance factory.
BasicElementFactory uses the attribute Instantiate to determine the way to create element instance.
Default constructor
Default constructor is provided to instantiate an element. For example, following is an element:
public class SimpleElement { private String fieldA; private String fieldB; private String fieldC; //getters and setters here }
To instantiate an element by default constructor, you do not need to define the attribute Instantiate or specify the value of attribute as default.
Constructor
Sometimes, you need to create an element instance using a constructor with some arguments. For example, following is an element:
public class SimpleElement { private String fieldA; private int fieldB; private String fieldC; public SimpleElement(String a, int b, String c) { //Some logic here } }
The definition for its element instance is as follows:
If you want to instantiate an element by constructor, you need to set the value of the attribute Instantiate to constructor, and define a child tag arguments with the attribute CreateParent="constructor". The children of arguments specify the arguments type and value (the element in argument can be any type of element, not only the simple type in this sample).
Static factory
You can also create an element instance from static factory. For example, following is an element:
public interface ProductInterface { //Some logic here } public class MyProduct { public MyProduct(String content) { //Some logic here } //Some logic here }
Its factory is as follows:
public class MyStaticFactory { public static Product createProduct(String content) { return new MyProduct(content); } }
You need to specify the value of the attribute Instantiate to staticFactory and define an attribute FactoryClass to tell the BasicElementFactory what factory class is. Then, you need to define a tag arguments as its subtag, whose attribute value of CreateParent is the name of the static factory method in the factory class.
In this example, you specified the implementation class name as the tag name of the element. If the element created from the static factory is not an instance of the implementation class mypackage.MyProduct, the BasicElementFactory will throw out an exception.
Instance factory
The factory may be an instance of some class rather than a static method in a class. You can also create an element instance through instance factory.
For example, following is an element:
public interface ProductInterface { //Some logic here } public class MyProduct { public MyProduct(String content) { //Some logic here } //Some logic here }
Its factory is as follows:
public class MyFactory { private String content public Product createProduct() { return new MyProduct(content); } public void setContent(String content) { this.content = content } }
You can define your element as follows:
<mypackage.Product id="aProduct" Instantiate="instanceFactory"> <mypackage.MyFactory CreateParent="FactoryInstance" content="This is my product"/> <arguments CreateParent="createProduct"/> </mypackage.Product>
In this way, you need to specify the value of the attribute Instantiate to instanceFactory. You also need to define a subtag that represents the instance of factory with the attribute CreateParent = "FactoryInstance". You need to define another subtag arguments, whose attribute value of CreateParent is the name of the factory method.
You can define your element in the following way:
<mypackage.MyProduct id="aProduct" Instantiate="instanceFactory"> <mypackage.MyFactory CreateParent="FactoryInstance" content="This is my product"/> <arguments CreateParent="createProduct"/> </mypackage.MyProduct>
But if the element instance created from the factory is not an instance of mypackage.MyProduct, the BasicElement Factory will throw out an exception.
FactoryElement
FactoryElement is to customize the creation of Element from Tag.
For example, following is an element:
public class MyProduct { public MyProduct(String content) { //Some logic here } //Some logic here }
Its factory is as follows:
public class MyFactory implements FactoryElement { private String content; public Object getElement() { return new MyProduct(content); } public String getContent() { return content; } public void setContent(String content) { this.content = content; } }
In this way, you must specify the attribute Instantiate="factoryElement", and the FactoryClass ="mypackage.MyFactory" must implement interface com.ibm.btt.element.FactoryElement.
Most of the elements can be created in one of the approaches listed in Instantiating an element. However, sub type elements are not created in those ways:
Arguments
The tag name arguments is reserved for ElementFactory. When you want to invoke a method against something, you need to define arguments as the input for the method.
For example, in order to call constructor method of SimpleElement public SimpleElement(String a, int b, String c), you need to define the arguments as follows:
For each element in the arguments, you need to define an attribute ArgumentType, which is the type of argument in the method declaration; and the sub-elements needs to be exactly in the sequence of the arguments in the method declaration. This principle also applies to instantiating element by static factory and instance factory.
Entry
The element entry is used to define entries in a java.util.Map. The tag name entry is also reserved. See Defining collections.
Simple elements
There are some built-in data types in Java language that cannot be instantiated by default constructor, constructor, static factory or instance factory. They are treated as simple elements and the ElementFactory can handle them.
The following table lists all the supported simple elements and the sample definitions.