Dashboard > Appistry EAF v3.8 > Documentation > Component Definition XML
Log In   View a printable version of the current page.  

Overview

A component definition enables Fabric developers to use their existing Java classes (POJOs) or Spring beans in the Fabric with no code changes. Developers can either call these components remotely using Fabric Spring remoting, or reference these components from process flow states to define the activity to be executed by the Fabric. The methods available to the Fabric can be explicitly defined or automatically discovered by reflection. Component definitions are a great alternative to Task definitions, but can only define Java objects.

Example component definition file

<?xml version="1.0"?>
<java-components xmlns="http://www.appistry.com/ns/component"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xsi:schemaLocation="http://www.appistry.com/ns/component eaf-component.xsd">
    <component name="pojo_component">
        <class name="PlainOldJavaObject"/>
        <method name="helloWorld"/>
        <method name="addIntegers">
            <signature>
                <argument type="int"/>
                <argument type="int"/>
            </signature>
        </method>
        <method name="appendStrings">
            <signature>
                <argument type="java.lang.String"/>
                <argument type="java.lang.String"/>
            </signature>
        </method>
        <method name="modifyStringBuilder"/>
    </component>
</java-components>

Refer to the following table for details on all supported attributes and elements for component definition.

Element Description
java-components This is the root element for the components definition file. It has no attributes and defines only one child element:
Element Cardinality Description
component 1..n This element defines a fabric component, which is the Fabric's representation of a Java class or Spring bean.

component This element defines a fabric component, which is the fabric's representation of a Java class or Spring bean. It defines a series of methods, security options for those methods, and the class or Spring bean that defines the actual runnable code. The component element has the following attributes:
Attribute Use Description
name required Name of the component. This name can consist of alpha-numeric characters , the hyphen '-' or the underscore '_'
default-retries optional Number of retries that will be attempted by default for all methods on the component. This can be overwritten by the method-level retries attribute.
default-timeout optional Defines the default timeout period for component methods in seconds. This can be overwritten by the method-level timeout attribute.

The component also defines the following child-elements:
Element Cardinality Description
method 0..n This defines a runnable method on the component, corresponding to a method on the Java class or Spring bean.
security 0..1 This defines component-wide security attributes.
class 0..1 This defines the Java class associated with the component. This element, and the spring-bean element are mutually exclusive and one of the two is required.
spring-bean 0..1 This defines the Spring bean associated with the component. This element, and the class element are mutually exclusive and one of the two is required.
exclusive 0..1 This element defines the component as exclusive, where only a specified number of methods from the component may be run at a time. This can be defined per worker or per cpu.
limited 0..1 This element defines the component as limited, where only a specified number of fabric workers will be able to run methods on the component.


The easiest way to configure components is through reflection. Public methods in the component's class will be discovered via reflection, and will automatically be made available if not declared with a method element. Methods are made available for use by remote Fabric Spring proxy calls and in process flows.

In the example below, a component named "reflected_pojo_component" will be defined with all the component methods. 
<?xml version="1.0"?>
<java-components>
    <component name="reflected_pojo_component">
        <class name="PlainOldJavaObject"/>
    </component>
</java-components>


Additionally, components can be configured explicitly:
<?xml version="1.0"?>
<java-components>
    <component name="pojo_component">
        <class name="PlainOldJavaObject"/>
        <method name="helloWorld"/>
        <method name="addIntegers">
            <signature>
                <argument type="int"/>
                <argument type="int"/>
            </signature>
        </method>
        <method name="appendStrings">
            <signature>
                <argument type="java.lang.String"/>
                <argument type="java.lang.String"/>
            </signature>
        </method>
        <method name="modifyStringBuilder"/>
    </component>
</java-components>
class This element defines the Java class that is to be represented by the fabric component. This element and the spring-bean element are mutually exclusive. The class must exist either in a Jar file listed in the application xml's java-libs section, or be part of a separately deployed far file, also listed in its java-libs section. In the latter case, the far must be referenced in the application xml's fars section.
Attribute Use Description
name required The name of the Java class. Can be short hand or fully qualified.

spring-bean This element defines the Spring bean that is to be represented by the fabric component. This element, and the class element are mutually exclusive, and one of the two must be defined for a component. The spring bean element only has a single attribute:
Attribute Use Description
name required The name of the Spring bean to be used.

Example: 
<?xml version="1.0"?>
<java-components>
    <component name="pojo_component">
        <spring-bean name="PlainOldJavaObject"/>
    </component>
</java-components>
limited Defining this element defines the component as limited, which will allow only a limited number of workers to run methods on the component at a time, specified in the min, max or percent attributes. Also see limited tasks.
Attribute Use Description
min optional The minimum number of fabric workers allowed to run the component methods at a given time. This is not required if percent is set.
max optional The maximum number of fabric workers allowed to run the component methods at a given time. This is not required if percent is set.
percent optional A percentage of the total workers in the fabric that are allowed to run the component methods at a given time. This is not required if min and max are set.

Example: 
<?xml version="1.0"?>
<java-components>
    <component name="spring_pojo_component">
        <class name="PlainOldJavaObject"/>
        <limited min="10" max="12"/>
    </component>
</java-components>
exclusive Defines all methods of the component as exclusive. For more information on exclusivity, see exclusive tasks. This element has no attributes.
Example: 
<?xml version="1.0"?>
<java-components>
    <component name="pojo_component">
        <class name="PlainOldJavaObject"/>
        <exclusive/>
    </component>
</java-components>
security This element defines security attributes for the component. It defines a single child element and has no attributes. This element, and the method level security element define groups of users who are allowed to run process flows that execute component methods. See Application Security for more information on fabric security configuration.
Element Cardinality Description
group-access 1 This element defines a set of groups which have access to run methods on the component.

method This element defines a runnable method on the component, which can point to either a method in the backing Java class or Spring bean. These methods can be invoked either by remote Fabric Spring proxy calls (for Spring beans only), or by states in a process-flow. The method element has the following attributes:
Attribute Use Description
name required The name of the method. Must match the name of a method defined in in the class or Spring bean referenced by the class element or spring-bean element.
alias optional A unique short-hand name for the method. If defined, the alias will be used as the handle for the method instead of the name attribute. This attribute is required if the named method is overloaded in the class or Spring bean.
retries optional The number of retry attempts allowed for the method in case of failure. This overwrites the default-retries attribute on the component.
timeout optional The timeout period for the method in seconds. This value overwrites the default-timeout attribute on the component.

The method element defines the following child elements.
Element Cardinality Description
signature 0..1 The method signature, required if overloading.
security 0..1 Defines security attributes for the method.

The default form for method definition is as follows: 

<?xml version="1.0"?>
<java-components>
    <component name="pojo_component">
        <class name="PlainOldJavaObject"/>
        <method name="add"/>
    </component>
</java-components>

To support overloading, the signature of the component method needs to be provided explicitly, so that the Fabric knows which version of the method to invoke.
<?xml version="1.0"?>
<java-components>
    <component name="pojo_component">
        <class name="PlainOldJavaObject"/>
        <method name="add" alias="add_integers">
            <signature>
                <argument type="int"/>
                <argument type="int"/>
            </signature>
        </method>
        <method name="add" alias="add_strings">
            <signature>
                <argument type="java.lang.String"/>
                <argument type="java.lang.String"/>
            </signature>
        </method>
    </component>
</java-components>
group-access This element defines a set of groups allowed access to the containing element, which is either a component or method. Group-access can be defined on individual methods or for the whole component. In the case that group-access is defined for both the component and method, the user attempting to run a component method must first be authorized to use the component, and then must be authorized to access the method. Authorization is determined by whether or not the user is a member of one of the groups listed in the group access list. If no group-access element is present, the parent element will be considered open and will have no security attributes. For more information, see Application Security.
The group-access element has no attributes and defines one child element:
Element Cardinality Description
group 1..n This element declares a group that has access to the component or method.

group This element declares a fabric user group which is allowed access to the component or method with the parent group access defined. For more information, see Application Security
Attribute Use Description
name required The name of the fabric user group that is to gain access.

signature This element defines a method signature for a component method. This signature must match the signature of a class or bean method defined in the component's class or spring-bean. The signature element is necessary if the method is overloaded, and can be omitted if it is not. The method signatures are expressed as follows:
Element Cardinality Description
argument 1..n A single method parameter type, listed in the order they would occur in Java.

Example: 
<?xml version="1.0"?>
<java-components>
    <component name="pojo_component">
        <method name="add" alias="add_integers">
            <signature>
                <argument type="int"/>
                <argument type="int"/>
            </signature>
        </method>
        <method name="add" alias="add_strings">
            <signature>
                <argument type="java.lang.String"/>
                <argument type="java.lang.String"/>
            </signature>
        </method>
    </component>
</java-components>
argument This element defines the type of a single input parameter into a Java or Spring bean method. The parameter order is determined by the order in which these argument elements occur in the signature element.
Attribute Use Description
type required The Java type of the parameter. Can be expressed either as short-hand or a fully-qualified Java type name.

Component XML Schema

<?xml version="2.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:comp="http://www.appistry.com/ns/component"
           targetNamespace="http://www.appistry.com/ns/component"
           elementFormDefault="qualified"
           version="1.0">
    <xs:element name="java-components">
        <xs:complexType>
            <xs:sequence>
                <xs:element minOccurs="1" maxOccurs="unbounded" ref="comp:component"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
    <xs:element name="component">
        <xs:complexType>
            <xs:sequence>
                <xs:choice>
                    <xs:element ref="comp:class" minOccurs="0" maxOccurs="1"/>
                    <xs:element ref="comp:spring-bean" minOccurs="0" maxOccurs="1"/>
                </xs:choice>
                <xs:choice>
                    <xs:element ref="comp:limited" minOccurs="0" maxOccurs="1"/>
                    <xs:element ref="comp:exclusive" minOccurs="0" maxOccurs="1"/>
                </xs:choice>
                <xs:element ref="comp:security" minOccurs="0" maxOccurs="1"/>
                <xs:element ref="comp:method" minOccurs="0" maxOccurs="unbounded"/>
            </xs:sequence>
            <xs:attribute name="name" type="xs:string" use="required"/>
            <xs:attribute name="default-retries" type="xs:nonNegativeInteger" use="optional"/>
            <xs:attribute name="default-timeout" type="xs:string" use="optional"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="class">
        <xs:complexType>
            <xs:attribute name="name" type="xs:string" use="required"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="spring-bean">
        <xs:complexType>
            <xs:attribute name="name" type="xs:string" use="required"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="limited">
        <xs:complexType>
            <xs:attribute name="min" type="xs:nonNegativeInteger"/>
            <xs:attribute name="max" type="xs:nonNegativeInteger"/>
            <xs:attribute name="percent" type="percentType"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="exclusive"/>
    <xs:element name="security">
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="comp:group-access" minOccurs="1" maxOccurs="1"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
    <xs:element name="method">
        <xs:complexType>
            <xs:all>
                <xs:element ref="comp:signature" minOccurs="0" maxOccurs="1"/>
                <xs:element ref="comp:security" minOccurs="0" maxOccurs="1"/>
            </xs:all>
            <xs:attribute name="name" type="xs:string" use="required"/>
            <xs:attribute name="alias" type="xs:string" use="optional"/>
            <xs:attribute name="retries" type="xs:nonNegativeInteger" use="optional"/>
            <xs:attribute name="timeout" type="xs:string" use="optional"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="group-access">
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="comp:group" minOccurs="1" maxOccurs="unbounded"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
    <xs:element name="signature">
        <xs:complexType>
            <xs:sequence>
                <xs:element ref="comp:argument" minOccurs="0" maxOccurs="unbounded"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
    <xs:element name="group">
        <xs:complexType>
            <xs:attribute name="name" type="xs:string" use="required"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="argument">
        <xs:complexType>
            <xs:attribute name="type" type="xs:string" use="required"/>
        </xs:complexType>
    </xs:element>
    <xs:simpleType name="percentType">
        <xs:restriction base="xs:nonNegativeInteger">
            <xs:minInclusive value="0"/>
            <xs:maxInclusive value="100"/>
        </xs:restriction>
    </xs:simpleType>
    <xs:element name="resource-argument">
        <xs:complexType>
            <xs:attribute name="request-key" type="xs:string" use="optional"/>
        </xs:complexType>
    </xs:element>
    <xs:element name="rank-argument">
        <xs:complexType>
            <xs:attribute name="strategy" type="xs:string" use="optional"/>
        </xs:complexType>
    </xs:element>
</xs:schema>