Integration Guides › ADL Reference Guide › Assembly Descriptor Syntax

Assembly Descriptor Syntax

This section contains the following topics:

The assembly descriptor contains one assembly entity, defining a new component that consists of several components, which can be either simple components or other assemblies. An assembly that is comprise of instantiable components (all residing in a catalog), is itself considered instantiable. If a singleton component appears anywhere in an assembly, the assembly itself is a singleton and cannot be moved into a catalog.

The assembly descriptor has the following structure:

assembly sname
   { 
   .category = text
   .description = " text " 
   .console = " subord-name " 

   input  sname
   output  sname
   ... 

   property  sname &nbsp[ : dflt = value ] 
   property  sname &nbsp[ : mandatory ] 
   ... 
   volume sname

   subordinate  sname
      { 
       .class = clsname
        attr = val
       ... 
      } 

   connections 
      [ 
       sub-name . trm-name => sub-name . trm-name
      .... 
      ] 
   visual 
      { 
      ... 
      } 
   }

The following attributes are defined for assemblies only. They have no meaning in simple components:

.console

The name of a subordinate component, which will serve as the default login target for this assembly. This makes it possible to define an assembly that behaves like a simple component in the sense of allowing the assembly to accept a login request the same way as a simple component that has support for a login console can. As not every component is required to have a login console (depends on the OS and the software installed on it), an assembly is not required to have one. If the assembly does not need a login console or does not have any component that can serve as one, this attribute can be omitted or set to the empty string. As a special exception, when the attribute is omitted (rather than set explicitly to the empty string), and the assembly has only one subordinate it is silently assumed that this subordinate is the default login target. The subordinate specified by the .console attribute (or assumed by default, for single-subordinate assemblies) can itself be an assembly.
It is not an error to specify a subordinate that does not support console login (either because it is a component that has no console, or because it is an assembly that has .console set to empty): The only outcome of such a setting will be that the resulting assembly will not support console login.

The following attributes are defined for an assembly. They have the same meaning as their counterparts for a simple component:

.category	An arbitrary string that defines the general category to which the component belongs. It is allowed by the ADL syntax, but is not interpreted in any way. It is intended for use by the CA AppLogic visual tools to organize components in component libraries (catalogs).
.description	A short description of the component. Similarly to .category, the value of this attribute is arbitrary and intended for documentation purposes only.

The order of entities in the assembly is not important and all sub-entities are optional, except that an assembly must have at least one subordinate entity.

Here is a summary of the sub-entities of the 'assembly' entity, followed by sub-sections defining each one in detail:

input, output	Define the assembly's terminals.
property	Defines a property of the assembly. Each property must be connected to at least one property of a subordinate component. See the subordinate entity.
volume	Defines a property of the assembly, similar to the property entity.
subordinate	Defines a subordinate component in the assembly.
connections	Defines the assembly's connection table. This is an array entity, each element corresponds to one connection.
visual	Indicates visual presentation data. ADL does not define the contents of this entity. It is intended for a GUI editor to store information related to how the assembly is displayed in the window of the Infrastructure Editor. (color, icon shape, layout of terminals, layout of subordinate components, routing of connections, and so on). The contents of this entity must conform to the general syntax rules of UDL, which were presented earlier in this document - in the Syntax Rules that Apply to All Descriptor Types section. Also, see the UDL specification for more details.

Input and Output Sub-entities

These sub-entities define the assembly's terminals.

The terminal entities support the mandatory and shared attributes. Specifying the mandatory attribute indicates that the terminal must be connected. Mandatory terminals will trigger a compilation error in an assembly that includes a component with such an unconnected terminal. Specifying the mandatory attribute for an assembly is not necessary if the subordinate component's terminal to which it is connected is already mandatory.

Specifying the shared attribute permits, but does not require, CA AppLogic to configure all terminals with this attribute and share the same virtual network device within the VM environment. Terminals that share the same virtual interface conserve system resources and permit operation in VM environments that have limits on the number of interfaces per VM, but has the disadvantage of merging the I/O statistics of all shared terminals when monitoring the appliance.

Important: Currently, shared terminals are not supported for Windows OS and should not be used with Windows-based appliances.

An assembly can have any number of terminals, except for the top-level assembly of an application, which should have no terminals.

Property Entity

The property entity defines a property of the assembly. Each property must be connected to at least one property of a subordinate component - see the subordinate entities below. A property may have a default value, identified by the dflt attribute. The default, if specified, overrides the default value in the subordinate components to which the property is connected. Alternatively, mandatory may be specified, requiring that the property be set from outside (such as in an outer assembly) even if the subordinate components to which it is connected have a default value for the property.

Volume Entity

This entity defines a property of the assembly, similar to the property entity. The property defined with the volume entity must be connected to at least one volume property on a subordinate component - see the subordinate entities below. The property defined by a volume entity may have the mandatory attribute specified, requiring it to be set, even if the components' volumes to which it is connected do not have the mandatory attribute set. Unlike regular properties, default= cannot be specified for a volume.

Subordinate Entity

The subordinate entity defines a subordinate component in the assembly. Each subordinate can have any number of attributes with each corresponding to a property (including volume properties) of the component that is overridden with the specified value.

In addition, the following pre-defined attributes with a special meaning exist for each subordinate, all having a name that begins with a '.' to distinguish them from regular properties:

.class	Specifies the class name of the subordinate component; this can be either the name of an instantiable class or the name of a singleton. This attribute is mandatory and cannot be omitted. The class name is specified either as a simple name or in the form catalog-name.class-name, where catalog-name is the name of a catalog. This is either a catalog that belongs to the application or a global catalog configured in the configuration file. The catalogs specified in the application package are looked up first. When no catalog name is given, the class-name is taken to be that of a component class residing in the same place as the assembly. For example, if the assembly is a catalog part, the subordinate is looked up in the same catalog. If the assembly belongs to an application, the subordinate is looked up in the application's package.
.start_order	Defines the order of starting this subordinate, relative to the other subordinates in the same assembly. Lower numbers are started first and those with a higher number are not started until all those with lower numbers have started successfully. Subordinates having the same start_order number can be started in any order and may have their startups overlap in time. The start order is local to the assembly and the same start order numbers can be reused in different assemblies. The relative order of starting subordinates in different assemblies depends on the start order numbers assigned to those assemblies. Subordinates with no .start_order attribute are started after all subordinates that do have the attribute.
.failover	Defines a failover group identifier. Components that have the same failover group ID in the application constitute a group of components that serve as backup for one another and therefore should never be scheduled on the same physical device. In the case of hardware failure, some of them remain alive. The failover group ID is global to the application. Components with the same group ID in different assemblies are considered to belong to the same group. Setting this attribute to the empty string is allowed and is treated as if the attribute is not set at all and there is no scheduling preference for this component.
.ignore	Defines a Boolean attribute that, if set to 1 (true), specifies that the subordinate's operation is not critical to the assembly and, if the subordinate fails to start, the application startup should proceed as normal. This attribute cannot be redirected to the assembly boundary. When setting this attribute, verify the other subordinates that have outputs connected to the one with .ignore set will work correctly if their outputs are unconnected.
.fieldopt	Sets the instance field-option value of the subordinate. Unlike the other pre-defined attributes of a component, such as .migrateable and .boot_tout which can be overridden by specifying the attribute of the same name in a subordinate entity in an assembly, the component's own .field_opt is not overridden. It is kept as the class field-option instead. See the .field_opt definition in the component descriptor syntax and also above where the assembly's attributes are explained.
.vlan	Defines the vlan tag for the component's external interface if one exists.This is an integer in the range 0..4095. It is applicable only for a subordinate component and cannot be set on a subordinate that is an assembly. If the component does not have an external interface, the setting is silently ignored.

All attribute names other than the pre-defined ones are considered to be property names of the subordinate component that need to be set to the specified value. This includes the predefined attributes of the subordinate component, such as .boot_tout, .migrateable, and .server, .standby, and the component-specific properties defined in it by the 'property' or the 'volume' entities. For additional information on component-specific properties, refer to the component descriptor syntax.

A special type of value is defined indicating that the property is connected to the assembly's boundary: $.name, where name is the name of one of the 'property' or 'volume' entities in the assembly.

If a property has to be set to a literal value that begins with the $. characters, the value must be quoted to ensure that it is not interpreted as a property connection. More than one subordinate property can be connected to the same boundary property and all such properties get the default value from the boundary property definition if none is provided in an outer-scope assembly. The $.name can be used for the pre-defined attributes of the subordinate too, making them regular properties on the assembly boundary.

The subordinate entity in an assembly also accepts the resource sub-entities, mem, cpu and bw, with the same attributes as defined in the Component Descriptor Syntax section.When applied to a subordinate that is a simple component, they override the resource settings in that component. The override must remain within the limits of the range defined in the component. The new range must no wider than the old one and must fit entirely into the old one.

When applied to a subordinate that is an assembly, the specified resources are distributed proportional, according to the relative weight of the resource requirements, in each of that assembly's subordinates. If a resource setting for a subordinate assembly causes a component to receive a resource setting that is outside of the min-max range defined for it, an error is reported by the ADL linker.

Connections Entity

The connections entity defines the assembly's connection table. The connections entity is an array entity and each array element is an association in the form x => y, where x and y identify two terminals to be connected. Each terminal identifier consists of a subordinate name and a terminal name separated by a '.' character.

Terminals that are to be exposed as terminals of the assembly itself (exterior connections) are also defined in in the same table, with the following syntax:

$. atrm-name => sub-name . strm-name, or 
sub-name . strm-name => $. atrm-name.

Both syntax variants are equivalent and mean that the terminal strm-name of subordinate sub-name is to be visible as atrm-name on the assembly. The atrm-name must correspond to an input or output entity defined in the assembly.

Because an input terminal is a network server and an output terminal is a client, the following rules apply:

An output can be connected to at most one input.
An input can be connected to any number of outputs. Subject only to limitations on the number of clients that the component supports for the specific service.
An input terminal on the assembly boundary must be redirected to exactly one input of a subordinate component.
Any number of subordinate component's outputs can be redirected to a single output on the assembly boundary.

In CA AppLogic 3.5 and later, with the introduction of connectable interfaces, the assembly definition can now contain interface entities in addition to terminals (inputs and outputs) in the following form:

interface <name> , [ mandatory ]

The entity connection table used for terminals (inputs and outputs) is also used for exposing an interface of a subordinate on the assembly boundary. The connection syntax for an interface is the same as that for terminals. You can connect interfaces only from component to boundary and only one connection can be made to either end point.

The following rules apply:

You cannot connect several component's interfaces to a single interface on the boundary.
You cannot connect several boundary interfaces to one component.
You cannot connect the interfaces of two components together.