38.17 XML Reference

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

IceGrid XML files must use UTF‑8 encoding.

38.17.1 Adapter

An adapter element defines an indirect object adapter. Refer to Section 32.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 38.2.

Table 38.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 D).	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 prop­erty (see Appendix D). 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 bal­ancing policy to determine the order of the endpoints returned by a locate request. End­points are ordered from the smallest priority value to the highest. If not defined, the value is 0. See Section 38.10.2 for more informa­tion.	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 38.22). If the value is true, this object adapter regis­ters 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 D). See Section 38.9 for more information on replication. If not defined, the default value is an empty string.	No
server-life­time	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 38.25) 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 consid­ered 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>

38.17.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 38.11.3 for more information on allocatable objects.

Context

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

Attributes

This element supports the attributes in Table 38.3.

Table 38.3. Attributes of the allocatable element.

Attribute	Description	Required
identity	Specifies the identity by which this allocat­able 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 conven­tion.	No

38.17.3 Application

An application element defines an IceGrid application. Refer to Section 38.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 38.4.

Table 38.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 avail­able for use within this application. See Section 38.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 regis­try. 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>

38.17.4 DbEnv

A dbenv element causes an IceGrid node to generate Freeze configuration prop­erties 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 38.17.5). See Chapter 39 for more information on Freeze.

Context

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

Attributes

This element supports the attributes in Table 38.5.

Table 38.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>

38.17.5 DbProperty

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

Context

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

Attributes

This element supports the attributes in Table 38.6.

Table 38.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>

38.17.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>

38.17.7 Directory

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

Context

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

Attributes

This element supports no attributes.

38.17.8 Distrib

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

Context

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

Attributes

This element supports the attributes in Table 38.7.

Table 38.7. Attributes of the distrib element.

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

Example

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

38.17.9 IceBox

An icebox element defines an IceBox server to be deployed on a node. It typi­cally contains at least one service element (Section 38.17.22), and may supply additional information such as command-line options (Section 38.17.26), environ­ment variables (Section 38.17.27), configuration properties (Section 38.17.17) and a server distribution (Section 38.13).

The element may optionally contain a single adapter element (Section 38.17.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 43 for more information on IceBox.

Context

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

Attributes

This element supports the same attributes as the server element (see Table 38.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>

38.17.10 IceGrid

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

38.17.11 Load Balancing

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

Context

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

Attributes

This element supports the attributes in Table 38.8.

Table 38.8. Attributes of the load-balancing element.

Attribute	Description	Required
load-sample	Specifies the load sample to use for the adap­tive 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>

38.17.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 38.14.2 for more information on log files.

Context

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

Attributes

This element supports the attributes in Table 38.9.

Table 38.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>

38.17.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 38.17.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 38.10.

Table 38.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 38.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 Win­dows 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 regis­try. 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 prop­erty IceGrid.Node.Name must match this attribute (see Section 38.21.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>

38.17.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 38.6 for more information on well-known objects.

Context

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

Attributes

This element supports the attributes in Table 38.11.

Table 38.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 appli­cation 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.

38.17.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 38.17.21) or a service-template element (Section 38.17.24).

Attributes

This element supports the attributes in Table 38.12.

Table 38.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 instanti­ated.	No

Example

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

38.17.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 38.17.3) or a node (Section 38.17.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 38.13.

Table 38.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 prop­erty 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>
            <properties refid="Debug"/>
            <property name="AppProperty" value="1"/>
        </properties>
    </server>
</application>

38.17.17 Property

An IceGrid node generates a configuration file for each of its servers and services. This file generally should not be edited manually because any changes are lost the next time the node generates the file. The property element is the correct way to define additional properties in a configuration file.

Note that IceGrid administrative utilities can retrieve the configuration proper­ties of a server or service, as described in Section 38.22.4.

Context

This element may only appear as a child of a server element (Section 38.17.19), a service element (Section 38.17.22), an icebox element (Section 38.17.9) or a properties element (Section 38.17.16).

Attributes

This element supports the attributes in Table 38.14.

Table 38.14. Attributes of the property element.

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

Example

<server id="MyServer" ...>
    <property name="Ice.ThreadPool.Server.SizeMax" value="10"/>
    ...
</server>

This property element adds the following definition to the server’s configura­tion file:

Ice.ThreadPool.Server.SizeMax=10

38.17.18 Replica Group

A replica-group element creates a virtual object adapter in order to provide replication and load balancing for a collection of object adapters. An adapter element (Section 38.17.1) declares its membership in a group by identifying the desired replica group. The element may declare well-known objects (Section 38.6) that are available in all of the participating object adapters. A replica-group element may contain a load-balancing child element that specifies the load-balancing algorithm the registry should use when resolving locate requests. If not specified, the registry uses a random load balancing policy with the number of replicas set to 0.

Refer to Section 38.9 for more information on replication and Section 38.10 for details on load balancing.

Context

This element may only appear as a child of an application element (Section 38.17.3).

Attributes

This element supports the attributes in Table 38.15.

Table 38.15. Attributes of the replica-group element.

Attribute	Description	Required
id	Specifies the identifier of the replica group, which must be unique among all adapters and replica groups in the registry. This identifier can be used in indirect proxies in place of an adapter identifier.	Yes

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

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>

In this example, the proxy WellKnownObject is equivalent to the proxy WellKnownObject@ReplicatedAdapter.

38.17.19 Server

A server element defines a server to be deployed on a node. It typically contains at least one adapter element (Section 38.17.1), and may supply addi­tional information such as command-line options (Section 38.17.26), environment variables (Section 38.17.27), configuration properties (Section 38.17.17), and a server distribution (Section 38.13).

Context

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

Attributes

This element supports the attributes in Table 38.16.

Table 38.16. Attributes of the server element.

Attribute	Description	Required
activation	Specifies whether the server’s activation mode. Legal values are manual, on-demand, always and session. If not specified, manual activation is used by default. See Section 38.25 for more informa­tion.	No
activation-timeout	Defines the number of seconds a node will wait for the server to activate. If the timeout expires, a client waiting to receive the end­points of an object adapter in this server will receive an empty set of endpoints. If not defined, the default timeout is the value of the IceGrid.Node.WaitTime property con­figured for the server’s node.	No
allocatable	Specifies whether the server can be allocated. A server is allocated implicitly when one of its allocatable objects is allocated. The value of this attribute is ignored if the server activa­tion mode is session; a server with this activation mode is always allocatable. Other­wise, if not specified and the server activation mode is not session, the server is not allo­catable.	No
application-distrib	Specifies whether this server’s distribution is dependent on the application’s distribution. If the value is true, the server cannot be patched until the application has been patched. If not defined, the default value is true. See Section 38.13.3 for more informa­tion on distribution dependencies.	No
deactivation-timeout	Defines the number of seconds a node will wait for the server to deactivate. If the timeout expires, the node terminates the server process. If not defined, the default timeout is the value of the node’s configuration property IceGrid.Node.WaitTime.	No
exe	The pathname of the server executable.	Yes
ice-version	Specifies the Ice version in use by this server. If not defined, IceGrid assumes the server uses the same version that IceGrid itself uses. A server that uses an Ice version prior to 3.3 must define this attribute if its adapters use the register-process attribute (see Section 38.17.1). For example, a server using Ice 3.2.x should use 3.2 as the value of this attribute.	No
id	Specifies the identifier for this server. The identifier must be unique among all servers in the registry. Within the server, child elements can refer to its identifier using the reserved variable ${server}.	Yes
pwd	The default working directory for the server. If not defined, the server is started in the node’s current working directory.	No
user	Specifies the name of the user account under which the server is activated and run. If a user account mapper is configured for the node, the value of this attribute is used to find the corresponding account in the map. On Unix, the node must be running as root to be able to run servers under a different user account. On Windows, or if the node is not running as root on Unix, the only permissible value for this attribute is an empty string or the name of the user account under which the node is running. On Unix, if the node is running as root and this attribute is not specified, the server is run under the user ${session.id} if the server activation mode is session or under the user nobody if the activation mode is manual, on-demand or always.	No

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

Example

<server id="MyServer"
    activation="on‑demand"
    activation‑timeout="60"
    application‑distrib="false"
    deactivation‑timeout="60"
    exe="/opt/app/bin/myserver"
    pwd="/">
    <option>‑‑Ice.Trace.Network=1</option>
    <env>PATH=/opt/Ice/bin:$PATH</env>
    <property name="ServerId" value="${server}"/>
    <adapter name="Adapter1" .../>
</server>

38.17.20 Server Instance

A server-instance element deploys an instance of a server-template element (Section 38.17.21) on a node. Refer to Section 38.7 for more information on templates.

Context

This element may only appear as a child of a node element (Section 38.17.13).

Attributes

This element supports the attributes in Table 38.17.

Table 38.17. Attributes of the server-instance element.

Attribute	Description	Required
template	Identifies the server template.	Yes

All other attributes of the element must correspond to parameters declared by the template. The server-instance element must provide a value for each parameter that does not have a default value supplied by the template.

Example

<icegrid>
    <application name="SampleApp">
        <server‑template id="ServerTemplate">
            <parameter name="id"/>
            <server id="${id}" activation="manual" .../>
        </server‑template>
        <node name="Node1">
            <server‑instance template="ServerTemplate"
                id="TheServer"/>
        </node>
    </application>
</icegrid>

38.17.21 Server Template

A server-template element defines a template for a server element (Section 38.17.19), simplifying the task of deploying multiple instances of the same server definition. The template should contain a parameterized server element that is instantiated using a server-instance element (Section 38.17.20). Refer to Section 38.7 for more information on templates.

Context

This element may only appear as a child of an application element (Section 38.17.3).

Attributes

This element supports the attributes in Table 38.18.

Table 38.18. Attributes of the server-template element.

Attribute	Description	Required
id	Specifies the identifier for the server tem­plate. This identifier must be unique among all server templates in the application.	Yes

Parameters

A template may declare parameters that are used to instantiate the server element. You can define a default value for each parameter. Parameters without a default value are considered mandatory and values for them must be supplied by the server-instance element. See Section 38.18 for more information on parameter semantics.

Example

<icegrid>
    <application name="SampleApp">
        <server‑template id="ServerTemplate">
            <parameter name="id"/>
            <server id="${id}" activation="manual" .../>
        </server‑template>
        <node name="Node1">
            <server‑instance template="ServerTemplate"
                id="TheServer"/>
        </node>
    </application>
</icegrid>

38.17.22 Service

A service element defines an IceBox service. It typically contains at least one adapter element (Section 38.17.1), and may supply additional information such as configuration properties (Section 38.17.17).

Refer to Section 38.8 for more information on using IceBox services in IceGrid.

Context

This element may only appear as a child of an icebox element (Section 38.17.9) or a service-template element (Section 38.17.24).

Attributes

This element supports the attributes in Table 38.19.

Table 38.19. Attributes of the service element.

Attribute	Description	Required
entry	Specifies the entry point of this service.	Yes
name	Specifies the name of this service. Within the service, child elements can refer to its name using the reserved variable ${service}.	Yes

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

Example

<icebox id="MyIceBox" ...>
    <service name="Service1" entry="service1:Create">
        <description>A description of this service.</description>
        <property name="ServiceName" value="${service}"/>
        <adapter name="MyAdapter" id="${service}Adapter" .../>
    </service>
    <service name="Service2" entry="service2:Create"/>
</icebox>

38.17.23 Service Instance

A service-instance element creates an instance of a service-template element in an IceBox server (see Section 38.8). Refer to Section 38.7 for more information on templates.

Context

This element may only appear as a child of an icebox element (Section 38.17.9).

Attributes

This element supports the attributes in Table 38.20.

Table 38.20. Attributes of the service-instance element.

Attribute	Description	Required
template	Identifies the service template.	Yes

All other attributes of the element must correspond to parameters declared by the template. The service-instance element must provide a value for each parameter that does not have a default value supplied by the template.

Example

<icebox id="IceBoxServer" ...>
    <service‑instance template="ServiceTemplate" name="Service1"/>
</icebox>

38.17.24 Service Template

A service-template element defines a template for a service element (Section 38.17.22), simplifying the task of deploying multiple instances of the same service definition. The template should contain a parameterized service element that is instantiated using a service-instance element (Section 38.17.23). Refer to Section 38.8.2 for more information on service templates.

Context

This element may only appear as a child of an application element (Section 38.17.3).

Attributes

This element supports the attributes in Table 38.21.

Table 38.21. Attributes of the service-template element.

Attribute	Description	Required
id	Specifies the identifier for the service tem­plate. This identifier must be unique among all service templates in the application.	Yes

Parameters

A template may declare parameters that are used to instantiate the service element. You can define a default value for each parameter. Parameters without a default value are considered mandatory and values for them must be supplied by the service-instance element. See Section 38.18 for more information on parameter semantics.

Example

<icegrid>
    <application name="IceBoxApp">
        <service‑template id="ServiceTemplate">
            <parameter name="name"/>
            <service name="${name}" entry="DemoService:create">
                <adapter name="${service}" .../>
            </service>
        </service‑template>
        <node name="Node1">
            <icebox id="IceBoxServer" ...>
                <service‑instance template="ServiceTemplate"
                    name="Service1"/>
            </icebox>
        </node>
    </application>
</icegrid>

38.17.25 Variable

A variable element defines a variable. See Section 38.18 for more information on variable semantics.

Context

This element may only appear as a child of an application element (Section 38.17.3) or node element (Section 38.17.13).

Attributes

This element supports the attributes in Table 38.22.

Table 38.22. Attributes of the variable element.

Attribute	Description	Required
name	Specifies the variable name. The value of this variable is substituted whenever its name is used in variable syntax, as in ${name}.	Yes
value	Specifies the variable value. If not defined, the default value is an empty string.	No

Example

<icegrid>
    <application name="SampleApp">
        <variable name="Var1" value="foo"/>
        <variable name="Var2" value="${Var1}bar"/>
        ...
    </application>
</icegrid>

38.17.26 Command Line Options

Server descriptors (Section 38.17.19) and icebox descriptors (Section 38.17.9) may specify command-line options that the node will pass to the program at startup. As the node prepares to execute the server, it assembles the command by appending options to the server executable’s pathname.

In XML, you define a command-line option using the option element:

<server id="Server1" ...>
    <option>‑‑Ice.Trace.Protocol</option>
    ...
</server>

The node preserves the order of options, which is especially important for Java servers. For example, JVM options must appear before the class name, as shown below:

<server id="JavaServer" exe="java" ...>
    <option>‑Xnoclassgc</option>
    <option>ServerClassName</option>
    <option>‑‑Ice.Trace.Protocol</option>
    ...
</server>

The node translates these options into the following command:

java -Xnoclassgc ServerClassName --Ice.Trace.Protocol

38.17.27 Environment Variables

Server descriptors (Section 38.17.19) and icebox descriptors (Section 38.17.9) may specify environment variables that the node will define when starting a server. An environment variable definition uses the familiar name=value syntax, and you can also refer to other environment variables within the value. The exact syntax for variable references depends on the platform on which the server’s descriptor is deployed.

On a Unix platform, the Bourne shell syntax is required:

LD_LIBRARY_PATH=/opt/Ice/lib:$LD_LIBRARY_PATH

On a Windows platform, the syntax uses the conventional style:

PATH=C:\Ice\lib;%PATH%

In XML, the env element supplies a definition for an environment variable:

<node name="UnixBox">
    <server id="UnixServer" exe="/opt/app/bin/server" ...>
        <env>LD_LIBRARY_PATH=/opt/Ice/lib:$LD_LIBRARY_PATH</env>
        ...
    </server>
</node>
<node name="WindowsBox">
    <server id="WindowsServer" exe="C:/app/bin/server.exe" ...>
        <env>PATH=C:\Ice\lib;%PATH%</env>
        ...
    </server>
</node>

If a value refers to an environment variable that is not defined, the reference is substituted with an empty string.

Environment variable definitions may also refer to descriptor variables and template parameters:

<node name="UnixBox">
    <server id="UnixServer" exe="/opt/app/bin/server" ...>
        <env>PATH=${server.distrib}/bin:$PATH</env>
        ...
    </server>
</node>

On Unix, an environment variable VAR can be referenced as $VAR or ${VAR}. You must be careful when using the latter syntax because IceGrid assumes ${VAR} refers to a descriptor variable or parameter and will report an error if no match is found. If you prefer to use this style to refer to environment variables, you must escape these occurrences as shown in the example below:

<node name="UnixBox">
    <server id="UnixServer" exe="/opt/app/bin/server" ...>
        <env>PATH=${server.distrib}/bin:$${PATH}</env>
        ...
    </server>
</node>

IceGrid does not attempt to perform substitution on $${PATH}, but rather removes the leading $ character and then performs environment variable substitu­tion on ${PATH}. See Section 38.18.1 for more information on escaping vari­ables.