org.jicengine.element
Class ElementImpl

java.lang.Object
  extended byorg.jicengine.element.AbstractElement
      extended byorg.jicengine.element.ElementImpl
All Implemented Interfaces:
Element

public class ElementImpl
extends AbstractElement

ElementImpl encapsulates the common properties and behaviour of an element.

Common Element Structure

An Element consists of:

Common processing procedures

ElementImpl defines the common procedures for processing these sub-components. The details of the processing can be tricky - an Element might or might not have a constructor, it might or might not have an element, etc.

Lack of the exact runtime-behaviour

the runtime-behaviour of an Element is defined by interfaces ValueElement and ActionElement. Whether an Element becomes an ValueElement or an ActionElement depends on the state of the Element.

ElementImpl can be initialized little-by-little, it is designed to be used together with ElementCompiler. because of this approach, the runtime-behaviour of the Element is known only when the Element is completely initialized.

After an ElementImpl-object is completely initialized, its runtime-version (ValueElement or ActionElement) can be obtained with method toRuntimeElement().

id binding

the object is added to the global-context only after it is created. this way, the child-elements that are constructor parameters are processed before the element has used its id-attribute. therefore, if a child has a same id than the parent, the duplicate-id-exceptions will blame the wrong element for the id - the parent.

Author:
.timo

Nested Class Summary
 class ElementImpl.ActionElementImpl
          ActionElement-version of an ElementImpl.
 class ElementImpl.ValueElementImpl
          ValueElement-version of an ElementImpl.
 
Field Summary
protected static int CHILD_TYPE_ACTION
           
protected static int CHILD_TYPE_ACTION_PARAM
           
protected static int CHILD_TYPE_CONSTRUCTOR_PARAM
           
 
Fields inherited from interface org.jicengine.element.Element
VARIABLE_NAME_CDATA, VARIABLE_NAME_ELEMENT_INSTANCE, VARIABLE_NAME_PARENT_INSTANCE
 
Constructor Summary
ElementImpl(java.lang.String name, Location location)
           
 
Method Summary
 void addChildElement(Element child)
          adds a child element into this element.
protected  java.lang.Object execute(Context globalContext, java.lang.Object parentInstance)
           executes this element. this includes: processing of all child elements, both value and action executing the constructor (if there is one) validating the instace (if there is one) handling the overriding-issues: instance not created and only action-parameter child-elements are executed if this element is overridden.
protected  BuildContext findBuildContextFrom(Context globalContext)
           
 Operation getAction()
           
 Operation getConstructor()
           
 java.lang.Class getInstanceClass()
           
 boolean isNeeded(ValueElement child)
           
protected  boolean isOverridden(Context globalContext)
           
 void setAction(Operation operation)
           
 void setConstructor(Operation operation)
           
 void setId(java.lang.String id)
          Sets the id of this element.
 void setInstanceClass(java.lang.Class instanceClass)
           
 void setOverridableBy(java.lang.String overridingId)
           
 Element toRuntimeElement()
           Returns the runtime-version of this Element.
 java.lang.String toString()
           
protected  void validateInstance(java.lang.Object instance, boolean isOverridingObject)
          validates the instance. an exception is thrown, if the instance is not valid.
 
Methods inherited from class org.jicengine.element.AbstractElement
getLocation, getName
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

CHILD_TYPE_CONSTRUCTOR_PARAM

protected static final int CHILD_TYPE_CONSTRUCTOR_PARAM
See Also:
Constant Field Values

CHILD_TYPE_ACTION_PARAM

protected static final int CHILD_TYPE_ACTION_PARAM
See Also:
Constant Field Values

CHILD_TYPE_ACTION

protected static final int CHILD_TYPE_ACTION
See Also:
Constant Field Values
Constructor Detail

ElementImpl

public ElementImpl(java.lang.String name,
                   Location location)
Method Detail

setConstructor

public void setConstructor(Operation operation)

setOverridableBy

public void setOverridableBy(java.lang.String overridingId)

setId

public void setId(java.lang.String id)
Sets the id of this element. Makes the value of this element available in the global-context

Parameters:
id - The new id value

setInstanceClass

public void setInstanceClass(java.lang.Class instanceClass)

setAction

public void setAction(Operation operation)
               throws ElementException
Throws:
ElementException

getConstructor

public Operation getConstructor()

getInstanceClass

public java.lang.Class getInstanceClass()

getAction

public Operation getAction()

isOverridden

protected boolean isOverridden(Context globalContext)

toRuntimeElement

public Element toRuntimeElement()
                         throws ElementException

Returns the runtime-version of this Element. Call this method after the Element is completely initialized.

Returns:
either an instance of ValueElement or ActionElement.
Throws:
ElementException - Description of the Exception

toString

public java.lang.String toString()

findBuildContextFrom

protected BuildContext findBuildContextFrom(Context globalContext)

isNeeded

public boolean isNeeded(ValueElement child)
Returns:
true if the child element is needed i.e. used by either the action or the constructor.

addChildElement

public void addChildElement(Element child)
                     throws ElementException
adds a child element into this element.

Throws:
ElementException - if the child is a ValueElement that is not needed by the action nor the constructor. unsused child elements without a purpose (without action) are not allowed because.. their value would be created and the result would be ignored.

validateInstance

protected void validateInstance(java.lang.Object instance,
                                boolean isOverridingObject)
                         throws ElementException
validates the instance. an exception is thrown, if the instance is not valid. currently, only the class of the instance is validated against the 'instanceClass'-property.

Parameters:
isOverridingObject - for more better error messages..
Throws:
java.lang.Exception - if the instance is not valid. since this method doesn't know where the instance came from, the caller must catch this exception and throw a new exception with a better error message.
ElementException

execute

protected java.lang.Object execute(Context globalContext,
                                   java.lang.Object parentInstance)
                            throws ElementException

executes this element. this includes:

Returns:
the instance of this element, if any, or null. the caller of this method should know whether the returned value is usable or not. if this element has an action, the returned value should not be used!! and note: the returned value won't be the result of the action. it will be the result of the constructor.
Throws:
ElementException