Instantiating an element

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 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
}

The definition of this element is:

<myPackage.SimpleElement id="aSimpleElement" fieldA="valueA" fieldB="valueB" fieldC="valueC" />

<myPackage.SimpleElement id="aSimpleElement" Instantiate="default" fieldA="valueA" fieldB="valueB" fieldC="valueC" />

To instantiate an element by default constructor, you do not need to define the attribute Instantiate or specify the value of attribute as default.

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:

<myPackage.SimpleElement id="aSimpleElement" Instantiate="constructor">
<arguments CreateParent="constructor">
<string ArgumentType="java.lang.String" value="valueA"/>
<integer ArgumentType="int" value="12345"/>
<string ArgumentType="java.lang.String" value="valueC"/>
</arguments>
</myPackage.SimpleElement>

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).

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 can define your element instance as follows:

<mypackage.Product id="productA" Instantiate="staticFactory"
                   FactoryClass="mypackage.MyStaticFactory">
  <arguments CreateParent="createProduct">
    <string ArgumentType="java.lang.String"
            value="This is productA"/>
  </arguments>
</mypackage.Product>

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.

You can also define your element as follows:

<mypackage.MyProduct id="productA" Instantiate="staticFactory"
FactoryClass="mypackage.MyStaticFactory">
  <arguments CreateParent="createProduct">
    <string ArgumentType="java.lang.String" value="This is productA"/>
  </arguments>
</mypackage.MyProduct>

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.

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 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;
  }
}

You can define your element in the following way:

<mypackage.MyProduct id="aProduct"
Instantiate="factoryElement"
FactoryClass="mypackage.MyFactory">
<string Injection="content" value="abcdefg"/>
</mypackage.MyProduct>

In this way, you must specify the attribute Instantiate="factoryElement", and the FactoryClass ="mypackage.MyFactory" must implement interface com.ibm.btt.element.FactoryElement.