Sep 7 - AppLogic 2.1 has been officially released! See Component Descriptor Syntax
The component descriptor contains onecomponent entity, defining either a "singleton" component or an instantiable class of components. There is no difference between the definition of a singleton and a class, except that instantiable classes are required to reside in a library of components referred to as a 'catalog'. Also, either type of component can be used in an assembly, but a singleton can appear only once in the structure of an application, while an instantiable component can be used multiple times.
component name { volume sname : dev= pathname, [, ro] [, high_bw] resource cpu : min= val , max= val resource mem : min= val , max= val , abs= val resource bw : min= val , max= val (input|output) sname : protocol= name = [, mandatory][, alias = dnsname =] interface sname property sname : type=(string|integer|ip_addr) [, filter= regexp ] \ [,min= val ,max= val ] [, (mandatory| dflt= val) ] property sname : type=(string|integer) [, values= v1|v2|v3... ] \ [, (mandatory| dflt= val ) ] cfgfiles [ vol= sname , path= filename vol= sname , path= filename ... ] kernel: path= filename [, initrd = filename ] [, options = " string" ] visual { ... } } The
component entity has the following attributes defined:
.migrateable | If set, it allows the component to be moved from one CPU to another (provided that the component is running in a virtual machine and there is VM migration support). There is no need to specify this attribute in a component - the default, if not specified, is 1 (TRUE). This is a boolean attribute (valid values: 0,no,false,1,yes,true; also may be specified inline without value at all, meaning '1'). In the absence of this attribute, .migrateable=1 is assumed by default. Note that this is unlike most other boolean attributes defined in ADL - they usually default to 0. |
.server | If .migrateable is set to 0, defines the name of the server on which this component is to run. This attribute, along with the .migrateable attribute are usually set from an outer assembly, not in the component descriptor itself. The compiler will output a warning if this attribute is set in the component. |
.standby | If set, this means the component is not started automatically when the application is started. The .standby attribute is not meant to be set in a component descriptor directly. Normally, it is set from an assembly that contains the component or re-directed to the top-level assembly of an application to allow enabling/disabling parts of the application by modifying the application's properties (stored in the top assembly - see the Package Descriptor further on). This is a boolean attribute. |
.boot_tout | boot timeout, in seconds. If specified and set to a non-zero value, indicates the amount of time the application controller is to wait for the component to become active before assuming that it has failed to start. If this attribute is omitted or is set to zero, a default value that is configured for the AppLogic controller is used. |
.os_type | specifies the OS that this component uses. This information is necessary for support of multiple OS types running in virtual machines. The value provided is not interpreted by the ADL build system; together with the data in 'kernel' entity described below it is intended to be passed along to the VM boot loader. If not specified, 'linux' is assumed. |
.field_opt | a bitmask of options for enabling various debugging and troubleshooting support. Note that this attribute does not follow the normal rules for overriding property values from an assembly, which apply to all other pre-defined attributes - the .field_opt value specified for a component is kept as "class field options", while any setting of the same attribute for an instance of the component in an assembly is kept as "instance field options". |
.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 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. |
volume | defines a volume that contains a file system used by the component. At least one volume entity must appear in each component. |
resource | defines the requirements of the component towards the hardware resources that must be made available for it to run. |
input, output | these entities define "terminals" of the component, which are network interfaces intended for connection with other components in the same application. |
interface | used to enable and configure network interfaces that are not meant for connecting to other components (as the input and output terminals are) |
property | defines a configurable property of the component. |
cfgfiles | defines a list of configuration files that need to be checked for property markup and updated accordingly. |
kernel | This entity contains OS-specific boot information, its contents depend on the value of the .os_type attribute of the component. |
visual | 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 component is displayed in the editor's window (color, icon shape, layout of terminals, etc.). 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. |
volume
defines a volume that contains a file system used by the component. At least one volume entity must appear in each component. The volume entity has the following attributes: dev= | the device name, as it is seen by the host OS of the component. The physical device containing the filesystem (and which can be either local or remote) will be made available to the host OS under that name. This attribute must be specified for all volumes. No two volumes in the same component can have the same value for this attribute. |
class | If specified for an instantiable component that resides in a catalog, this attribute specifies that the volume data is common to this class of components and an image of the volume is present in the catalog. See also the 'type=' attribute below. If specified for a singleton component, the volume data is to become a common template image whenever the singleton component is converted to an instantiable component. If the 'class' attribute is not present, there is no common image for the volume and the name of an image for the volume must be configured for each instance of the component (this is usually done in the assembly that contains the component). |
type= | This attribute is mandatory for volumes that have the 'class' attribute set. It speficies how the common class image of the volume is to be provided to each instance of the class. It can have the following values:instantiable - the 'class' image is the initial data for each instance and a separate copy of it is provided to each instance. (It is assumed that each instance's actual data will not differ significantly form the initial image and that the 'copy' may be replaced by a logical equivalent thereof, i.e., only the modified portions of the data may be kept separately for the instance, using the common image for the unmodified data).template - This is similar to the 'instantiable' type, but a complete copy of the volume is made for each instance. This is useful for database templates.common - the 'class' image is accessed directly by each instance of the component. Volumes of this type cannot have configuration files that are writable by the ADL build system stored on them - i.e., entries in the cfgfiles table (described further on) for these volumes are invalid. The 'common' type also implicitly sets the 'ro' and 'shared' attributes (see below).blank - there is no image provided, each instance is to receive an empty un-initialized volume upon boot. 'null' is intended for specifying swap volumes. It also requires that the 'size=' attribute be specified. |
size= | Volume size, for volumes of type blank . This must be a non-zero integer value, specifying the size in bytes. K, M and G suffixes can be used, meaning Kbytes, Mbytes, etc. |
mandatory | this applies only to volumes that do not have the class attribute and indicates that the volume is required for the operation of the component. If mandatory is not set, the component must be prepared to work correctly even if the device (which is seen by the component's software as specified by the dev= attribute) is not present. |
ro | means the filesystem on the volume is not written to by the component. Specifying this attribute does not guarantee that the component itself will not attempt to write to the volume. However, the presense of this attribute may be used to prevent write operations from going through. Specifying 'ro' also implies 'shared' - see below. |
shared | this attribute, if present, means that the volume image can be shared among multiple instances of the same component, as well as with other components.This is mostly useful if the 'ro' attribute is also specified, or if the filesystem on the volume has a built-in mechanism for read/write sharing at block level. Note that 'shared' need not be specified for class volumes of type 'common' (see type= above). |
boot | marks the volume as an OS boot volume. Note that the file paths specified in the 'kernel' sub-entity are relative to the root directory of the boot volume. Exactly one volume in a component must have the boot attribute. |
high_bw | identifies a volume that is accessed frequently and/or large amounts of data are transferred to/from it. This is a hint used for resource allocation, making it preferable to use a local resource for this filesystem. |
local_only | if specified, this attribute means that the volume must reside on the same host as the component instance that uses it. |
property entity below. The mandatory attribute for such volumes works the same way as the mandatory attribute for properties. A 'volume' property should be set to the logical name of one of the application's volumes (as found in the application's package descriptor). Note that this means volumes and properties share namespace and one cannot define a volume and a property of the same name.
resource
The resource entities define the requirements of the component towards the hardware resources that must be made available for it to run. The name of a resource entitiy must be one of: cpu, mem or bw. The definition of these entities is as follows: cpu | The min and max attributes of this sub-entity define the CPU time needed by the component, relative to the CPU time of other components that are allocated on the same physical CPU expressed as a decimal fraction or as percentage value. The value may exceed 1 (or 100%), if the component requires 2 or more CPUs on an SMP system. |
mem | defines the amount of memory needed by the component; The three attributes of 'mem' are interpreted as follows: max - the maximum amount that should be allocated to the component (i.e., it will not benefit its operation if it had more memory), min - the minimum amount that should be allocated for the component to retain near-optimum functionality, abs - the minimum amount of memory necessary for the component, under which it will cease to be operational. The number may be suffixed by a scale modifier like K and M and G, with their usual meaning of Kbyte (1024), Mbyte (1048576), etc. |
bw | defines the minimum and maximum network bandwidth necessary for the component to operate, expressed in bits/sec (scale modifiers like K and M and G are allowed; unlike the memory units, these modifiers follow the networking tradition - they mean decimal orders of magnitude K=1000, M=1,000,000, etc., e.g., 1000M means 1 gigabit/s, same as 1G). |
input, output
These entities define "terminals" of the component, which are network interfaces intended for connection with other components in the same application. A "terminal" is a special kind of network interface - it is used only for one specific protocol and only in one direction ("direction" here refers to flow of control, not of data - i.e., an output terminal is an interface used by a protocol client; while an input terminal is for a server). The presence of a terminal entity automatically defines a host name that resolves to the remote side of the connection in which this terminal participates. The terminal entities have the following attributes: protocol | this is the name of the network protocol filter for this terminal. The protocol name corresponds either to a pre-defined protocol (e.g., http, nfs, etc.) or to a custom protocol that has filtering rules defined in the application's package descriptor. This attribute must be present for each input or output. If no protocol control is needed for the terminal, use 'protocol=any'. |
mandatory | if present, this binary attribute means that the terminal may not be left unconnected. Mandatory terminals will trigger a compilation error in an assembly that includes a component with such a terminal left unconnected. |
gateway | (for outputs only) - if present, identifies the terminal as the default gateway for the component. A gateway output, instead of being programmed for connection to a single input on the remote side, is configured as the interface through which all connections outside the local network should go. When it is connected in an assembly, the remote end of the connection becomes the default gateway in the IP routing table and it is also programmed as the DNS server. Usually, a gateway terminal would be connected to a NAT router with DNS forwarding (and/or cache) or something similar. |
alias | Output terminals can also have an alias attribute, defining an additional host name under which the remote side of the connection is known (in addition to the terminal name itself, which is always added to the 'hosts' file). |
interface
This entity type is used with one of two fixed names - 'external' and 'default'. It is used to enable and configure network interfaces that are not meant for connecting to other components (as the terminals are - see above) and have no restrictions on the type of connections that can be made. The syntax for the interface entities is as follows:interface external interface default
The 'interface external' entry enables the device named 'eth0' to be used as the external network interface of the component (accessible from outside the application). If enabled, eth0 is not used for terminals and its IP configuration is not set up automatically. Instead, it is expected that properties are defined to configure the network adapter.
The 'interface default' entry enables configuring an unused network interface for unrestricted use, with an automatically assigned IP address on the same subnet as the ones used for terminal connections. The assigned IP address is made available to the AppLogic controller as the IP address of the component; this can be used for maintenance logins.
property
The property entity defines a configurable property of the component. Any parameter that may need to be configured can be defined as a property. The values of properties are made available to the component's software in the following ways:- all properties are available for access by shell scripts and executables as environment variables defined in a shell file that is stored automatically on the component's boot volume and can be included by any script;
- also, any files named in a 'cfgfiles' entity (see below) are searched for special markup identifying a portion of the file as corresponding to a property value - all matching instances are automatically updated to reflect the property value as configured in the component's descriptor or as overridden by any assembly in which the component participates. There are several variants of "markup", which allow making it appear as comments to the software that uses the file, so it is completely transparent to the component's code. See the Property Markup Syntax section later in this document.
type= | defines the propety type, the value of this attribute must be one of: string, integer or ip_addr. If the 'type=' attribute is not specified, 'string' is assumed. |
filter= | A regular expression defining the set of valid values for the property. The expression must be coded in the syntax defined by Perl for regular expression pattern matching. The match is done on the entire property value - that is as if /^expression$/ was used in a Perl statement to check for a match (where expression is the value of the filter attribute. This attribute is optional. If not present, the value ".*" is assumed (match any string). |
values= | This attribute can be used as an alternative to the filter= attribute. It is treated exactly as the filter attribute by the ADL compiler, except that the use of values= expr instead of filter= expr is a hint to the GUI editor that the regular expression is a simple concatenation of strings to be matched, in the normal regular expression form "string1!string2!..." etc. This can be used to display a drop-down list of values in a property sheet instead of a free-text edit box. |
min= | Mininum and maximum values for an integer property. If the specified property type is 'integer', these optional attributes specify the limits of valid values. They are applied in addition to any regular expression pattern specified by the filter= attribute. The presence of a '-' or '+' sign in one of these values is taken to mean that the integer comparison against the limits is to be done as for signed integers. |
mandatory | If present, this attribute indicates a property with no default value. When the component is used in an assembly, a value for the property must be supplied in the assembly or it must be redirected to the assembly boundary; in the latter case, the corresponding property of the assembly also takes on the 'mandatory' attribute. If 'mandatory' is not specified, a default value for the property should be given with a 'dflt=' attribute (see below). |
dflt= | specifies a default value for the property. This attribute cannot be used together with 'mandatory'. |
lowercase | indicates that the property value is to be converted to lowercase before it is used to configure the component. This should be used for properties that need to appear as case-insensitive to the user, but provide the component a consistent value that can be compared using case-sensitive compare. Note that the lowercase conversion is done in the C locale. |
cfgfiles
defines the configuration files that need to be checked for property markup and updated accordingly. This entity is an array, each entry defines one configuration file and has these attributes:vol - names the volume on which the file is located (this should match one of the component's volumes, as defined by the volume entities). A value for this attribute must be specified for each cfgfiles array element.
path - this is the file name of the configuration file, relative to the volume on which it is located. Note that this may be different from the path where the application "sees" that file - depending on how the particular volume is mounted by the component. A value for this attribute must be specified for each cfgfiles array element.
quoting - defines the method for quoting meta-characters in the configuration file. A "meta-character" is any character that has a special meaning in the config file and must be quoted (or "escaped") in some manner in order to appear as a data character and not in its special-function role. The 'quoting' attribute can be set to one of the following strings:
conf - no quoting (default). | |
bash - data values that are enclosed by quotes are assumed to use \" to mean the quote character and \\ to mean the backslash. Backslashes that don't quote a " or \ character are left untouched, i.e., if the user sets a property value to "abc\def"ghi\n", the result written into the config file is "abc\\def\"ghi\n". Values that are not surrounded by quotes are limited to alphanumeric characters (an error is reported if such a property is set to a value with other characters, even if the filter for that property allows it). | |
perl, c - same as 'bash' | |
html - the characters that have significance in the HTML syntax (< > " and &) are encoded as < > " and &, e.g., abc&def<ghi becomes abc&def<ghi in the config file. |
kernel
This entity contains OS-specific boot information, its contents depend on the value of the .os_type attribute of the component. When.os_type=linux , the following attributes are defined for the 'kernel' entity:
path= filename - the name of the kernel image file, relative to the boot volume's root directory.
initrd= filename - the name of the ramdisk filesystem image to use during boot. The kernel image file and the ramdisk image file are typically produced as a result of building the Linux kernel.
options= "string" - other arguments to pass to the bootloader's 'kernel' command line.
| Topic AdvADLComponentDescriptor . { Edit | WYSIWYG | Attach | Backlinks: Web All webs | Printable | History: %REVISIONS% More } |
|
Copyright © 2005-2007 3tera, Inc. All Rights Reserved.
|