1. What Are Custom Types?
2. Type Definition Structure
3. Properties Definition
4. Target Templates
5. Type Inheritance
Each Component specifies its Type. A Type is similar to a class, while a component is its instance. Invicta contains a few built-in Types (JAR, WAR, Libraries, etc.). These Types are simply XML files consisting of code that will be used in the dumping process. Invicta's framework allows easily creating your own additional types, either by extending existing ones (using the inheritance mechanism) or by developing new ones from scratch.
Types are mainly ANT build script templates that consist of ANT targets. The template allows inserting project or component-specific information by accessing the data structures of the information processed from the project definition.
Custom Types' XML files can be stored at any location; its location (file name or directory) simply needs to be added to Invicta's list of Type locations.The XML files that define the Types have to comply with a DTD. To view the DTD defining the structure, click here.
XML structure:
invictaType - A single required root element.
Attributes:
name - the name of the the type. Must match the file name, e.g. if the name is JAR, then the file name must be JAR.xml. This is a required attribute.
initTarget, buildTarget, cleanTarget, distTarget - these are the names of the ANT targets defined in this type that performs building, cleaning or distribution. They are all required.
extends - a comma-separated list of names of Types that this type extends (inherits from). See Type Inheritance below.
removeTarget - A list of target names to remove from one of the Types that this Type extends. See Type Inheritance below.
Elements:
defineProperty - all properties used in this Type. The templates cannot use properties without first defining them. Properties are equivalent to class members. This element is optional and multiple. See Properties Definition below for more details.
targetTemplate - a definition of a target template. This is an ANT target, which in this case is equivalent to a class method. This element is also optional and multiple.
3. Properties Definition
Each Type may define multiple properties that act as class members. Target Templates may refer to the defined properties.
Attributes:
name - the named of the property. This attribute is required and unique.
type - the property's type, can be Component, Project, General, or local. This is a required attribute.
defaultValue - a default value for the defined property (instead of requiring a component or a project to define its value). Note: A General property must have a default value.
valueTemplate - The actual value template to use in the component. Useful for referencing other properties, as well as for general properties. Usage handlers as in target templates. A special %{value} tag is available as a reference to the default (or specific) value of the property.
There are 4 types of properties:
component - a property whose value may be defined by each Component using the property element of a Component's definition in Project Definition Files. If a default value was specified, then it is an optional property for the component; otherwise a component of this type must define a property with this name.
Example:
<defineProperty type="component" name="compilation.debug"/>
project - A property whose value may be defined by a specific project using the property element of projectSettings in Project Definition Files. If a default value was specified, then it's an optional property for the project; otherwise a project that has at least one component of this type must define a property with this name. In ANT run-time there will be a property for the component (comp_name.propertyname) that by default points to the project value (project.propertyname).
Example:
<defineProperty type="project" name="dist.dir" defaultValue="dist."/>
general - a general property that this type uses. Instead of being hard-coded, allows customization. For example: src.java.dir. Multiple Types may define the same general property, but all must have the same defaultValue (although not necessarily valueTemplate). Similarly to project properties, a component property points to a general property (allows customization in 2 different granularities).
Examples:
<defineProperty type="general" name="src.dir" valueTemplate="%{componentDir}/%{value}" defaultValue="src"/>
<defineProperty type="general" name="src.java.dir" valueTemplate="%{property;src.dir}/%{value}" defaultValue="java"/>
local - a 'private' property of a type. Its actual value is used in Invicta processing time. A local property will not be defined or available for customization in ANT run-time.
Target Templates have the same definition structure of standard ANT targets, except having the body as a Template instead of an actual ANT build script code, and having type inheritance mode attributes. Target Templates are equivalent to class methods.
Attributes:
Standard ANT target attributes (see ANT documentation):
name - the name of the target, for example: compile. In the generated build.xml, the name of the component will be added as a prefix to this name. This is a required attribute.
description - a descriptive text regarding the target to be displayed when using 'ant -projecthelp'.
if - a condition property for running this target.
unless - a condition property for disabling the running of this target.
depends - a comma-separated list of targets to depend on. Each name in the list can either be a name of a target in the same Type (component name will be added as a prefix automatically), or a call to a Template Handler (%{....}).
Inheritance mode attributes:
mode - how this target is defined in case this Type extends other Types that contain a target with the same name. Can be one of the following: replace|rename|addBefore|addAfter|addBeforeAll|addAfterAll. The default is replace. See Inheritance Mechanism below for more details.
Body - ANT build script code of this target. May contain any valid ANT code. In addition, may contain calls to Template Handlers with parameters. The generated build.xml will contain a valid build script after the tags of Handlers were replaced with logical information.
Target Template example:
<targetTemplate name="compile" depends="init"><![CDATA[
<echo message="Compiling '%{componentName}'..." />
<javac destdir="%{property;build.classes.dir}">
<src path="%{property;src.java.dir}"/>
<include name="%{property;src.java.filter}"/>
</javac>
]]></targetTemplate>
5. Type Inheritance (Type Extension)
A Type may extend one or more existing types. This inheritance is similar to standard class inheritance (including multiple inheritance).
Specifying the Type or Types to extend is done using the attribute extends of the invictaType element. This attribute contains a comma-separated list of type names. For example: <invictaType name="MyType" extends="JAR, Test" ...>When extending Types, conflicts may occur: properties with the same name but different values, targetTemplate with the same name but different content or settings.
Solving property conflicts: define in the new type a property with the conflicting name.
Solving targetTemplate conflicts:
Remove targets: use the removeTargets attribute of invictaType. It contains a comma-separated list of full target names of parents to remove. For example, if MyType has JAR and Test as parents and both contain the targets compile and pack, and you prefer the JAR ones, then use
<invictaType name="MyType" extends="JAR, Test" rempoveTargets="Test.compile, Test.pack" ...>Define a new target with the conflict in the new Type and set its inheritance mode using the mode attribute of a targetTemplate definition. In this case a target with this name will be defined in the new Type with the settings (if, else, depends, etc.) that are specified in the definition of the new Type and the behavior is one of the following:
replace - override the target with this name in the parent (or parents) with a the new targetTemplate definition.
rename - rename the targets of the parents to have a full name. For example, rename compile of JAR and Test to be JAR.compile and Test.compile. Enables the new Type to define a new target with this name and depend on the targets of the parent Types.
addBefore - define a new target with a template string while adding this new template string before the template string of the parent Type's target with this name (simple string concatenation).
addAfter - similar to addBefore, but adds the new template string after the parent's string.
addBeforeAll - similar to addBefore, but performs the concatenation in a chain of all parent Types according to their order in the extends list.
addAfterAll - similar to addBeforeAll, but adds the new template string before all parents' strings.