An adapter element defines an indirect object adapter. Refer to
Section 32.4 for more information on object adapters.
An optional nested description element provides free-form descriptive text.
<adapter name="MyAdapter"
endpoints="default"
id="MyAdapterId"
replica‑group="MyReplicaGroup">
<description>A description of the adapter.</description>
...
</adapter>
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 39.11.3 for more information on allocatable objects.
An application element defines an IceGrid application. Refer to
Section 39.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.
This element must be a child of an icegrid element. Only one
application element is permitted per file.
An optional nested description element provides free-form descriptive text.
<icegrid>
<application name="MyApplication"
import‑default‑templates="true">
<description>A description of the
application.</description>
...
</application>
</icegrid>
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 39.16.5). See
Chapter 40 for more information on Freeze.
An optional nested description element provides free-form descriptive text.
<dbenv name="MyEnv" home="/opt/data/db">
<description>A description of the
database environment.</description>
...
</dbenv>
A dbproperty element defines a BerkeleyDB configuration property. See
Chapter 40 for more information on Freeze.
<dbenv name="MyEnv" home="/opt/data/db">
<description>A description of the
database environment.</description>
<dbproperty name="set_cachesize" value="0 52428800 1"/>
</dbenv>
A description element specifies a description of its parent element.
This element may only appear as a child of the application,
replica-group,
node,
server,
service,
icebox,
adapter, and
dbenv elements.
<node name="localnode">
<description>Free form descriptive text for
localnode</description>
</node>
A directory element specifies a directory in a distribution. Refer to
Section 39.13 for more information on distribution descriptors.
A distrib element specifies the files to download from an IcePatch2 server as well as the server’s proxy. Refer to
Section 39.13 for more information on distribution descriptors.
<distrib icepatch="DemoIcePatch2/server:tcp ‑p 12345">
<directory>dir1</directory>
<directory>dir2/subdir</directory>
</distrib>
An icebox element defines an IceBox server to be deployed on a node. It typically contains at least one
service element (
Section 39.16.22), and may supply additional information such as command-line options (
Section 39.16.26), environment variables (
Section 39.16.27), configuration properties (
Section 39.16.17) and a server distribution (
Section 39.13).
The element may optionally contain a single adapter element (
Section 39.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 44 for more information on IceBox.
An optional nested description element provides free-form descriptive text.
<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>
The icegrid element is the top-level element for IceGrid descriptors in XML files. This elements supports no attributes.
A load-balancing element determines the load balancing policy used by a replica group. Refer to
Section 39.10 for details on load balancing.
<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>
39.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 39.14.2 for more information on log files.
<server id="MyServer" ...>
<log path="${server}.log" property="LogFile"/>
</server>
39.16.13 Node
A node element defines an IceGrid node. The servers that the node is responsible for managing are described in child elements.
This element may only appear as a child of an application element (
Section 39.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.
<node name="Node1" load‑factor="2.0">
<description>A description of this node.</description>
<server id="Server1" ...>
<property name="NodeName" value="${node}"/>
...
</server>
</node>
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 39.6 for more information on well-known objects.
<adapter name="MyAdapter" id="WellKnownAdapter" ...>
<object identity="WellKnownObject"
type="::Module::WellKnownInterface"/>
</adapter>
A parameter element defines a template parameter. Template parameters must be declared with this element to be used in template instantiation.
<server‑template id="MyServerTemplate">
<parameter name="index"/>
<parameter name="exepath" default="/opt/myapp/bin/server"/>
...
</server‑template>
The properties element is used in three situations:
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.
A named property set element may only be a child of an application element (
Section 39.16.3) or a
node (
Section 39.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.
<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>
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.
<server id="MyServer" ...>
<property name="Ice.ThreadPool.Server.SizeMax" value="10"/>
...
</server>
This property element adds the following definition to the server’s configuration file:
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 39.16.1) declares its membership in a group by identifying the desired replica group. The element may declare well-known objects (
Section 39.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 39.9 for more information on replication and
Section 39.10 for details on load balancing.
An optional nested description element provides free-form descriptive text.
<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.
A server element defines a server to be deployed on a node. It typically contains at least one
adapter element (
Section 39.16.1), and may supply additional information such as command-line options (
Section 39.16.26), environment variables (
Section 39.16.27), configuration properties (
Section 39.16.17), and a server distribution (
Section 39.13).
An optional nested description element provides free-form descriptive text.
<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>
A server-instance element deploys an instance of a
server-template element (
Section 39.16.21) on a node. Refer to
Section 39.7 for more information on templates.
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.
<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>
A server-template element defines a template for a
server element (
Section 39.16.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 39.16.20). Refer to
Section 39.7 for more information on templates.
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 39.17 for more information on parameter semantics.
<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>
A service element defines an IceBox service. It typically contains at least one
adapter element (
Section 39.16.1), and may supply additional information such as configuration properties (
Section 39.16.17).
Refer to Section 39.8 for more information on using IceBox services in IceGrid.
An optional nested description element provides free-form descriptive text.
<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>
A service-instance element creates an instance of a
service-template element in an IceBox server (see
Section 39.8). Refer to
Section 39.7 for more information on templates.
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.
<icebox id="IceBoxServer" ...>
<service‑instance template="ServiceTemplate" name="Service1"/>
</icebox>
A service-template element defines a template for a
service element (
Section 39.16.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 39.16.23). Refer to
Section 39.8.2 for more information on service templates.
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 39.17 for more information on parameter semantics.
<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>
A variable element defines a variable. See
Section 39.17 for more information on variable semantics.
<icegrid>
<application name="SampleApp">
<variable name="Var1" value="foo"/>
<variable name="Var2" value="${Var1}bar"/>
...
</application>
</icegrid>
Server descriptors (Section 39.16.19) and icebox descriptors (
Section 39.16.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.
<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>
Server descriptors (Section 39.16.19) and icebox descriptors (
Section 39.16.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.
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>
<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 substitution on
${PATH}. See
Section 39.17.1 for more information on escaping variables.
