35.16 XML Reference

This section provides a reference for the XML elements that define IceGrid descriptors, in alphabetical order.

35.16.1 Adapter

An adapter element defines an indirect object adapter. Refer to Section 28.4 for more information on object adapters.

Context

This element may only appear as a child of a server or service element.

Attributes

This element supports the attributes in Table 35.2.

Table 35.2. Attributes of the adapter element.

Attribute	Description	Required
endpoints	Specifies one or more endpoints for this object adapter. These endpoints typically do not specify a port. This attribute is translated into a definition of the adapter’s Endpoints configuration property (see Appendix C).	No
id	Specifies an object adapter identifier. The identifier must be unique among all adapters and replica groups in the registry. This attribute is translated into a definition of the adapter’s AdapterId configuration property (see Appendix C). If not defined, a default value is constructed from the adapter name and server id (and service name for an IceBox service).	Yes
name	The name of the object adapter as used in the server that creates it.	Yes
priority	Specifies the priority of the object adapter as an integer value. The object adapter priority is used by the Ordered replica group load balancing policy to determine the order of the endpoints returned by a locate request. Endpoints are ordered from the smallest priority value to the highest. If not defined, the value is 0. See Section 35.10.2 for more information.	No
register-process	This attribute is only valid if the enclosing server uses an Ice version prior to 3.3. In Ice 3.3 or later, this functionality is replaced by the administrative facility (see Section 35.21). If the value is true, this object adapter registers an object in the IceGrid registry that facilitates graceful shutdown of the server. Only one object adapter in a server should set this attribute to true. If not defined, the default value is false.	No
replica-group	Specifies a replica group identifier. A non-empty value signals that this object adapter is a member of the indicated replica group. This attribute is translated into a definition of the adapter’s RepliaGroupId configuration property (see Appendix C). See Section 35.9 for more information on replication. If not defined, the default value is an empty string.	No
server-lifetime	A value of true indicates that the lifetime of this object adapter is the same as the lifetime of its server. This information is used by the IceGrid node to determine the state of the server. Specifically, the server is considered activated (see Section 35.24) when all the object adapters with the server-lifetime attribute set to true are registered with the registry (the object adapter registers itself during activation). Furthermore, server deactivation is considered to begin as soon as one object adapter with the server-lifetime attribute set to true is unregistered with the registry (the object adapter unregisters itself during deactivation). If not defined, the default value is true.	No

An optional nested description element provides free-form descriptive text.

Example

<adapter name="MyAdapter"
    endpoints="default"
    id="MyAdapterId"
    replica‑group="MyReplicaGroup">
    <description>A description of the adapter.</description>
    ...
</adapter>

35.16.2 Allocatable

An allocatable element defines an allocatable object in the IceGrid registry. Clients can allocate this object using only its identity, or they can allocate objects of a specific type. Refer to Section 35.11.3 for more information on allocatable objects.

Context

This element may only appear as a child of an adapter element (Section 35.16.1).

Attributes

This element supports the attributes in Table 35.3.

Table 35.3. Attributes of the allocatable element.

Attribute	Description	Required
identity	Specifies the identity by which this allocatable object is known.	Yes
property	Specifies the name of a property to generate that contains the stringified identity of this allocatable.	No
type	An arbitrary string used to group allocatable objects. By convention, the string represents the most-derived Slice type of the object, but an application is free to use another convention.	No

35.16.3 Application

An application element defines an IceGrid application. Refer to Section 35.3 for more information. An application typically contains at least one node element, but it may also be used for other purposes such as defining server and service templates, default templates, replica groups and property sets.

Context

This element must be a child of an icegrid element. Only one application element is permitted per file.

Attributes

This element supports the attributes in Table 35.4.

Table 35.4. Attributes of the application element.

Attribute	Description	Required
import-default-templates	If true, the default templates configured for the IceGrid registry are imported and available for use within this application. See Section 35.7.4 for more information on default templates. If not specified, the default value is false.	No
name	The name of the application. This name must be unique among all applications in the registry. Within the application, child elements can refer to its name using the reserved variable ${application}.	Yes

An optional nested description element provides free-form descriptive text.

Example

<icegrid>
    <application name="MyApplication"
        import‑default‑templates="true">
        <description>A description of the
            application.</description>
        ...
    </application>
</icegrid>

35.16.4 DbEnv

A dbenv element causes an IceGrid node to generate Freeze configuration properties for the server or service in which it is defined, and may cause the node to create a database environment directory if necessary. This element may contain dbproperty elements (Section 35.16.5). See Chapter 36 for more information on Freeze.

Context

This element may only appear as a child of a server element (Section 35.16.19) or a service element (Section 35.16.22).

Attributes

This element supports the attributes in Table 35.5.

Table 35.5. Attributes of the dbenv element.

Attribute	Description	Required
home	Specifies the directory to use as the database environment. If not defined, a subdirectory within the node’s data directory is used.	No
name	The name of the database environment.	Yes

The values of the name and home attributes are used to define the configuration property shown below:

Freeze.DbEnv.name.DbHome=home

An optional nested description element provides free-form descriptive text.

Example

<dbenv name="MyEnv" home="/opt/data/db">
    <description>A description of the
        database environment.</description>
    ...
</dbenv>

35.16.5 DbProperty

A dbproperty element defines a BerkeleyDB configuration property. See Chapter 36 for more information on Freeze.

Context

This element may only appear as a child of a dbenv element (Section 35.16.4).

Attributes

This element supports the attributes in Table 35.6.

Table 35.6. Attributes of the dbproperty element.

Attribute	Description	Required
name	The name of the configuration property.	Yes
value	The value of the configuration property. If not defined, the value is an empty string.	No

Example

<dbenv name="MyEnv" home="/opt/data/db">
    <description>A description of the
        database environment.</description>
    <dbproperty name="set_cachesize" value="0 52428800 1"/>
</dbenv>

35.16.6 Description

A description element specifies a description of its parent element.

Context

This element may only appear as a child of the application, replica-group, node, server, service, icebox, adapter, and dbenv elements.

Attributes

This element supports no attributes.

Example

<node name="localnode">
    <description>Free form descriptive text for
    localnode</description>
</node>

35.16.7 Directory

A directory element specifies a directory in a distribution. Refer to Section 35.13 for more information on distribution descriptors.

Context

This element may only appear as a child of the distrib element (Section 35.16.8).

Attributes

This element supports no attributes.

35.16.8 Distrib

A distrib element specifies the files to download from an IcePatch2 server as well as the server’s proxy. Refer to Section 35.13 for more information on distribution descriptors.

Context

This element may only appear as a child of an application element (Section 35.16.3) or a server element (Section 35.16.19).

Attributes

This element supports the attributes in Table 35.7.

Table 35.7. Attributes of the distrib element.

Attribute	Description	Required
icepatch	Specifies the proxy of the IcePatch2 server. If not defined, the default value is ${application}.IcePatch2/server.	No

Example

<distrib icepatch="DemoIcePatch2/server:tcp ‑p 12345">  
    <directory>dir1</directory> 
    <directory>dir2/subdir</directory> 
</distrib>

35.16.9 IceBox

An icebox element defines an IceBox server to be deployed on a node. It typically contains at least one service element (Section 35.16.22), and may supply additional information such as command-line options (Section 35.16.26), environment variables (Section 35.16.27), configuration properties (Section 35.16.17) and a server distribution (Section 35.13).

The element may optionally contain a single adapter element (Section 35.16.1) that configures the IceBox service manager’s object adapter and must have the name IceBox.ServiceManager. If no such element is defined, the service manager’s object adapter is disabled. Note however that the service manager’s functionality remains available as an administrative facet even when its object adapter is disabled. See Chapter 40 for more information on IceBox.

Context

This element may only appear as a child of a node element (Section 35.16.13) or a server-template element (Section 35.16.21).

Attributes

This element supports the same attributes as the server element (see Table 35.16).

The IceGrid node on which this server is deployed generates the following configuration property for the server:

IceBox.InstanceName=${server}

An optional nested description element provides free-form descriptive text.

Example

<icebox id="MyIceBox"
    activation="on‑demand"
    activation‑timeout="60"
    application‑distrib="false"
    deactivation‑timeout="60"
    exe="/opt/Ice/bin/icebox"
    pwd="/">
    <option>‑‑Ice.Trace.Network=1</option>
    <env>PATH=/opt/Ice/bin:$PATH</env>
    <property name="IceBox.UseSharedCommunicator.Service1"
        value="1"/>
    <service name="Service1".../>
    <service‑instance template="ServiceTemplate" name="Service2"/>
</icebox>

35.16.10 IceGrid

The icegrid element is the top-level element for IceGrid descriptors in XML files. This elements supports no attributes.

35.16.11 Load Balancing

A load-balancing element determines the load balancing policy used by a replica group. Refer to Section 35.10 for details on load balancing.

Context

This element may only appear as a child of a replica-group element (Section 35.16.18).

Attributes

This element supports the attributes in Table 35.8.

Table 35.8. Attributes of the load-balancing element.

Attribute	Description	Required
load-sample	Specifies the load sample to use for the adaptive load balancing policy. It can only be defined if type is set to adaptive. Legal values are 1, 5 and 15. If not specified, the load sample default value is 1.	No
n-replicas	Specifies the maximum number of replicas used to compute the endpoints of the replica group. If not specified, the default value is 1.	No
type	Specifies the type of load balancing. Legal values are adaptive, ordered, round-robin and random.	Yes

Example

<application name="MyApp">
    <replica‑group id="ReplicatedAdapter">
        <load‑balancing type="adaptive" load‑sample="15"
            n‑replicas="3"/>
        <description>A description of this
            replica group.</description>
        <object identity="WellKnownObject" .../>
    </replica‑group>
    ...
</application>

35.16.12 Log

A log element specifies the name of a log file for a server or service. A log element must be defined for each log file that can be accessed remotely by an administrative tool. Note that it is not necessary to define a log element for the values of the Ice.StdErr and Ice.StdOut properties.

See Section 35.14.2 for more information on log files.

Context

This element may only appear as a child of a server element (Section 35.16.19) or a service element (Section 35.16.22).

Attributes

This element supports the attributes in Table 35.9.

Table 35.9. Attributes of the log element.

Attribute	Description	Required
path	The path name of the log file. If a relative path is specified, it is relative to the current working directory of the node. The node must have sufficient access privileges to read the file.	Yes
property	Specifies the name of a property in which to store the path name of the log file as given in the path attribute.	No

Example

<server id="MyServer" ...>
    <log path="${server}.log" property="LogFile"/>
</server>

35.16.13 Node

A node element defines an IceGrid node. The servers that the node is responsible for managing are described in child elements.

Context

This element may only appear as a child of an application element (Section 35.16.3). Multiple node elements having the same name may appear in an application. Their contents are merged and the last definition of load-factor has precedence.

Attributes

This element supports the attributes in Table 35.10.

Table 35.10. Attributes of the node element.

Attribute	Description	Required
load-factor	A floating point value defining the factor that is multiplied with the node’s load average. The load average is used by the adaptive load balancing policy to figure out which node is the least loaded (see Section 35.10.2). The default is 1.0 on Unix platforms and 1/NCPUS on Windows (where NCPUS is the number of CPUs in the node’s computer). Note that, if Unix and Windows machines are part of a replica group, the Unix and Windows figures are not directly comparable, but the registry still makes an attempt to pick the least-loaded node.	No
name	Specifies the name of this node. The name must be unique among all nodes in the registry. Within the node, child elements can refer to its name using the reserved variable ${node}. An icegridnode process representing this node must be started on the desired computer and its configuration property IceGrid.Node.Name must match this attribute (see Section 35.20.2).	Yes

Example

<node name="Node1" load‑factor="2.0">
    <description>A description of this node.</description>
    <server id="Server1" ...>
        <property name="NodeName" value="${node}"/>
        ...
    </server>
</node>

35.16.14 Object

An object element defines a well-known object in the IceGrid registry. Clients can refer to this object using only its identity, or they can search for well-known objects of a specific type. Refer to Section 35.6 for more information on well-known objects.

Context

This element may only appear as a child of an adapter element (Section 35.16.1) or a replica-group element (Section 35.16.18).

Attributes

This element supports the attributes in Table 35.11.

Table 35.11. Attributes of the object element.

Attribute	Description	Required
identity	Specifies the identity by which this object is known.	Yes
property	Specifies the name of a property to generate that contains the stringified identity of the object. This attribute is only allowed if this object element is a child of an adapter element.	No
type	An arbitrary string used to group objects. By convention, the string represents the most-derived Slice type of the object, but an application is free to use another convention.	No

Example

<adapter name="MyAdapter" id="WellKnownAdapter" ...>
    <object identity="WellKnownObject"
        type="::Module::WellKnownInterface"/>
</adapter>

In the configuration above, the object can be located via the equivalent proxies WellKnownObject and WellKnownObject@WellKnownAdapter.

35.16.15 Parameter

A parameter element defines a template parameter. Template parameters must be declared with this element to be used in template instantiation.

Context

This element may only appear as a child of a server-template element (Section 35.16.21) or a service-template element (Section 35.16.24).

Attributes

This element supports the attributes in Table 35.12.

Table 35.12. Attributes of the parameter element.

Attribute	Description	Required
name	The name of the parameter. For example, if index is used as the name of a parameter, it can be referenced using ${index} in the server or service template.	Yes
default	An optional default value for the parameter. This value is used if the parameter is not defined when a server or service is instantiated.	No

Example

<server‑template id="MyServerTemplate"> 
    <parameter name="index"/> 
    <parameter name="exepath" default="/opt/myapp/bin/server"/> 
    ...
</server‑template> 

35.16.16 Properties

The properties element is used in three situations:

• as a named property set if the id attribute is specified

• as a reference to a named property set if the refid attribute is specified

• as an unnamed property set if the id or refid attributes are not specified.

A property set is useful to define a set of properties (a named property set) in application or node descriptors. Named property sets can be included in named or unnamed property sets with property set references.

Context

A named property set element may only be a child of an application element (Section 35.16.3) or a node (Section 35.16.13) element. An unnamed property set element may only be a child of a server, icebox, service, server-instance or service-instance element. An unnamed property set element with the service attribute defined may only be a child of a server-instance element. A reference to a named property set can only be a child of a named or unnamed property set element.

Attributes

This element supports the attributes in Table 35.13.

Table 35.13. Attributes of the properties element.

Attribute	Description	Required
id	Defines a new named property set with the given identifier. The identifier must be unique among all named property sets defined in the same scope. If not specified, the properties element refers to an unnamed property set or a property set reference.	No
refid	Defines a reference to the named property set with the given identifier. If not specified, the element refers to an unnamed or named property set.	No
service	Specifies the name of a service that is defined in the enclosing server-instance descriptor. The server instance must be an IceBox server that includes a service with the given name. An unnamed property set with this attribute defined extends the properties of the service. If not specified, the unnamed property set extends the properties of the server instance.	No

Example

<application name="Simple">
   <properties id="Debug">
        <property name="Ice.Trace.Network" value="1"/>
   </properties>

    <server id="MyServer" exe="./server">
        <properties>
&