Developing Apama Applications > Using Apama Studio > File Definition Formats > Block definition file format > XML elements that define a block
XML elements that define a block
Here are the list of XML element needed to define a block, arranged to show the hierarchical ordering. The elements are described in the table that follows the list:
<block>
<version>
<id> </id>
<date> </date>
<author> </author>
<comments> </comments>
</version>
<description> </description>
<properties parallel-aware="false" deprecated="false">
<input-feeds>
<feed>
<description> </description>
<field>
<description> </description>
<validation> </validation>
</field>
</feed>
</input-feeds>
<output-feeds>
definition identical to fields in input feeds
</output-feeds>
<parameters>
<field>
definition identical to fields in input and output feeds
</field>
</parameters>
<operations>
<operation>
<description> </description>
</operation>
</operations>
</properties>
<code> </code>
</block>
The following table lists and describes the XML elements used to define a block:
Element
Description
<block>
The root element in any .bdf file. This element has a single text (CDATA) attribute, <name>, which must define the name of the block. This element must contain the <version>, <description>, <properties>, and <code> child elements.
<version>
The block’s version. This element must contain the <id>, <date>, <author>, and <comments> child elements.
<id>
From an XML point of view, this element can contain any character data (#PCDATA), but it should be set to indicate the version number of the block, for example, 1.0 or 1.1. The version number is used to distinguish different versions of the block in the catalog browser within the Event Modeler. This version number must be the same as that encoded within the .bdf filename itself. For this reason, if the block is generated by the Block Builder, the content of this element is automatically used to name the .bdf file, in conjunction with the <name> element; see the description of the <block> element. This element has no attributes.
<date>
The date when the block was authored. This information is just for the block author’s future reference. This element takes any character data (#PCDATA). It has no attributes.
<author>
The block’s author. This information is just for future reference. This element takes any character data (#PCDATA). It has no attributes.
<comments>
Describes any changes that have been made to the block in this version. This element takes any character data (#PCDATA). It has no attributes
<description> — child of <block>
Can contain any character data (#PCDATA) that informatively describes the purpose of this block. As this information is displayed within the block catalog browser in the Event Modeler, it is useful to provide a brief summary of the block’s functionality. It has no attributes.
<properties>
Describes the interface of the block. This element must contain the <input-feeds>, <output-feeds>, <parameters>, and <operations> child elements. This element can also contain the two Boolean attributes "parallel-aware" and "deprecated". When the parallel-aware attribute is set to true, the block can be used in a parallel scenario. When the deprecated attribute is set to true, the block has been deprecated.
<input-feeds>
List all the input feeds of this block. This element can include zero or more <feed> child elements within it. It has no attributes and cannot contain any text.
<feed>
Represents either an input feed or an output feed, depending on where it occurs within the XML document. <feed> has two attributes, id and name. id is optional. If supplied, it must be a unique string that distinguishes the feed from all other input or output feeds. The name attribute must also be unique, but only across input feeds or output feeds. The block definition in the EPL code defines an action type definition that corresponds to this feed and that takes an argument for each field in the feed.
This element must contain the <description> and <field> child elements.
<description> — child of <feed>
Describes the purpose and use of the feed and is displayed by the block catalog browser in the Event Modeler.
<field>
The <feed> element can include any number of <field> elements. Each represents a field within the feed in question. The action in the corresponding EPL code that updates according to an input feed or sends data to an output feed must accept an argument for each field in the feed. The arguments must be in the same order as the fields defined in the XML document. A <field> element has two attributes, id and name. It is highly recommended to include the id attribute, it is optional only for backwards compatibility. It must be a unique string that distinguishes the field from all other input or output fields. name, a string, must also be unique but only within the feed the field belongs to.
This element must contain the <description> and <validation> child elements.
<description> — child of <field>
Describes the purpose and use of the field and is displayed by the block catalog browser in the Event Modeler.
<validation>
Although the DTD indicates this element is optional, this is just for backwards compatibility with older blocks. This element is required, and will be added automatically with default values applied when the block is used in the Event Modeler if a <validation> is unspecified. This element defines the type of the field.
If the field is of the scenario type string, float, integer or boolean, then no child elements are required within the <validation> element, whereas if the field is of type enumeration, then an <enumeration> child element should be included. Note that the first four types correspond to the types of the same name in the EPL code, whereas enumeration is really a string in the EPL code.
<validation> includes nine attributes, whose relevance depends on the value entered for the first attribute, type. This can only take the values string, float, integer, enumeration or boolean, and is required.
The other attributes, which are all optional, are minlength, maxlength, minvalue, maxvalue, unique, mutability, stringcase, and trim.
Note that these constraints are not enforced in this version of Event Modeler and are therefore not documented.
<output-feeds>
Lists all the output feeds of this block. To do this, you can include zero or more <feed> child elements within it, in the same way as for <input-feeds>.This element has no attributes and cannot contain any text.
<parameters>
This element should list all the configuration parameters of the block. The functionality of a block should be configured primarily through parameters. Like the fields in input and output feeds, the whole set of parameters must correspond to an initialization event whose field parameters correspond to the block parameters, in the same order. Furthermore, for each parameter there must be an event which enables that parameter to be set independently of the others and after the initial configuration.
This element takes no attributes and contains zero or more <field> child elements, one for each block parameter.
<field> — child of <parameter>
Each <field> child element corresponds to an actual parameter of the block, and the XML definition is identical as that for fields in input or output feeds. As described elsewhere, each <field> further embeds a <validation> element, where the <type> attribute is the most relevant. The type used here must correspond to the equivalent type in the EPL code.
<operations>
Represents any operations implemented in the block. Operations are chunks of functionality written in EPL that could be invoked by a scenario. This element has no attributes, and contains zero or more <operation> child elements.
<operation>
Describes an operation defined in the block. There should be an instance of this element for each operation in the block. This element takes two attributes, id and name. Both attributes are XML CDATA elements. id is optional only for backwards compatibility reasons, and should be specified. If not supplied, id will automatically be added in a way that makes the operation element unique. name, the string name for the operation, should also be made unique across the set of operations. In addition, each <operation> element should contain a <description> child element. This element can contain any character data that constitutes a relevant description of the functionality that is being made available. Its description is displayed by the block catalog browser in the Event Modeler.
Note that the XML definition of an operation consists solely of a name and a description. If you wish to pass parameters to an operation, you should use the block parameter mechanism.
<code>
The actual EPL template code that implements the interface and functionality of the block. For XML validation purposes, any character data can be supplied here (#CDATA), although the content must in fact be very carefully written. The contents of this section, which can only partly be generated by Apama Studio, are discussed in detail in Creating Blocks.
Copyright © 2013 Software AG, Darmstadt, Germany and/or Software AG USA Inc., Reston, VA, USA, and/or Terracotta Inc., San Francisco, CA, USA, and/or Software AG (Canada) Inc., Cambridge, Ontario, Canada, and/or, Software AG (UK) Ltd., Derby, United Kingdom, and/or Software A.G. (Israel) Ltd., Or-Yehuda, Israel and/or their licensors.