38.20 XML Features

IceGrid provides some convenient features to simplify the task of defining descriptors in XML.

38.20.1 Targets

An IceGrid XML file may contain optional definitions that are deployed only when specifically requested. These definitions are called targets and must be defined within a target element. The elements that may legally appear within a target element are determined by its enclosing element. For example, a node element is legal inside a target element of an application element, but not inside a target element of a server element. Each target element must define a value for the name attribute, but names are not required to be unique. Rather, targets should be considered as optional components or features of an application that are deployed in certain circumstances.

The example below defines targets named debug that, if requested during deployment, configure their servers with an additional property:

<icegrid>
    <application name="MyApp">
        <node name="Node">
            <server id="Server1" ...>
                <target name="debug">
                    <property name="Ice.Trace.Network" value="2"/>
                </target>
                ...
            </server>
            <server id="Server2" ...>
                <target name="debug">
                    <property name="Ice.Trace.Network" value="2"/>
                </target>
                ...
            </server>
        </node>
    </application>
</icegrid>

Target names specified in an icegridadmin command (see Section 38.24.1) can be unqualified names like debug, in which case every target with that name is deployed, regardless of the target’s nesting level. If you want to deploy targets more selectively, you can specify a fully-qualified name instead. A fully-qualified target name consists of its unqualified name prefaced by the names or identifiers of each enclosing element. For instance, a fully-qualified target name from the example above is MyApp.Node.Server1.debug.

38.20.2 Including Files

You can include the contents of another XML file into the current file using the include element, which is replaced with the contents of the included file. The elements in the included file must be enclosed in an icegrid element, as shown in the following example:

<!‑‑ File: A.xml ‑‑>
<icegrid>
    <server‑template id="ServerTemplate">
        <parameter name="id"/>
        ...
    </server‑template>
</icegrid>

<!‑‑ File: B.xml ‑‑>
<icegrid>
    <application name="MyApp">
        <include file="A.xml"/>
        <node name="Node">
            <server‑instance template="ServerTemplate" .../>
        </node>
    </application>
</icegrid>

In B.xml, the include element identifies the name of the file to include using the file attribute. The top-level icegrid element is discarded from A.xml and its contents are inserted at the position of the include element in B.xml.

Note that the file name of an included file is relative to the application descriptor, not relative to the working directory.

You can include specific targets (see Section 38.20.1) from a file by speci­fying their names in the optional targets attribute. If multiple targets are included, their names must be separated by whitespace. The example below illus­trates the use of a target:

<!‑‑ File: A.xml ‑‑>
<icegrid>
    <server‑template id="ServerTemplate">
        <parameter name="id"/>
        ...
    </server‑template>
    <target name="targetA">
        <server‑template id="AnotherTemplate">
            ...
        </server‑template>
    </target>
</icegrid>

<!‑‑ File: B.xml ‑‑>
<icegrid>
    <application name="MyApp">
        <include file="A.xml" targets="targetA"/>
        <node name="Node">
            <server‑instance template="ServerTemplate" .../>
            <server‑instance template="AnotherTemplate" .../>
        </node>
    </application>
</icegrid>