Note
When referring to file and directory locations in this document, <install-home> is the directory where the Agent Controller package was unzipped.
The agent launch configuration file (agent.xml) contains static information that the Agent Controller needs to know in order to start and manage an agent. This static information includes the following:
The agent.xml file must be located beneath a directory that is named for the agent itself. The agent-named directory must be located within the directory specified by the Agent element within the serviceconfig.xml file. For example, an agent named org.eclipse.tptp.TimeCollector would have this configuration file located in <install-home>/agents/org.eclipse.tptp.TimeCollector/agent.xml. The Agent Controller uses the directory name to identify agents that are requested by name. The information within the agent.xml configuration file is the metadata for that agent.
Note that the Agent Controller reads the agent.xml files for all agents only once, when it starts up. Hence, modifying the contents of these files or adding new agent directories requires the Agent Controller to be restarted before they take effect.
Element: Agent
This is the root element of the agent configuration file. It defines the
metadata for an agent. An object can request the metadata for an agent, then use
that information as it wishes. The sub-elements listed below are used by the
Agent Controller for launching and managing the agent. Additional
sub-elements can be defined by agent developers needing to return additional
information as metadata. Metadata is useful to a client trying to make
run-time decisions regarding which agent to use for a particular task.
Sub-elements: Interface
SingleInstance
Bound
MaxControllers
MaxObservers
ConfigFile
LaunchConfigurationAttributes:
- Name
- This string value is the unique name for the agent. This value is expected to be the same as the name used by the agent when it registers itself with the Agent Controller. If these values differ, requests for an agent by name will have varying results depending on whether the agent is already running or not.
Element: Interface
The string value for this element is the name of an interface supported by this
agent. There can be zero or more Interface elements in an Agent element.
An interface is a unique name for a set of commands supported by an agent.
Used by: Agent
Element: SingleInstance
The integer value for this element is either 0 or 1. The 0 (false)
indicates that this agent can have multiple instances running concurrently. The
1 (true) indicates only a single instance of this agent is allowed. If set
to 1, the Agent Controller will deny requests for new instances of this agent if
one instance is already executing.
Used by: Agent
Element: Bound
The integer value for this element is either 0 or 1. The 0 (false)
indicates that this agent is not bound to an application. The 1 (true) indicates
the agent is bound to an application. An agent that is bound to an
application can only be launched by that application, therefore, the
Agent Controller will refuse to launch an agent if its Bound value is 1.
Used by: Agent
Element: MaxControllers
The integer value for this element is -1, 0, or a positive value. The -1
indicates "no limit". The Agent Controller will reject requests for controller
rights to this agent if the number of requests exceeds this value. The
rights of a controller are defined by the agent developer. The expected use is
to limit the number of objects that can request conflicting actions such as
starting and stopping the collection of data.
Used by: Agent
Element: MaxObservers
The integer value for this element is -1, 0, or a positive value. The -1
indicates "no limit". The Agent Controller will reject requests for observer
rights to this agent if the number of requests exceeds this value. The
rights of an observer are defined by the agent developer. The expected use is to
limit the number of objects which can request inquiry-type actions such as
providing data that is static or being collected (perhaps because of a request
by a controller).
Used by: Agent
Element: ConfigFile
The string value for this element specifies the full path and filename of an
additional configuration file containing dynamic configuration information
accessible to the agent. This is an optional file, the purpose and content
of which is defined by the agent developer. The expected use is for the agent to
read its own configuration information from this file either at startup or any
other time.
Used by: Agent
Element:
LaunchConfiguration
Identifies launch configuration parameters for this Agent.
Used by: Agent
Sub-elements: launchInfo
Element:
launchInfo
Encapsulates information used in launching an executable.
Used by: LaunchConfiguration
Sub-elements: Application
Element: Application
This Application element defines the information used in starting an
application. Its executable
attribute value may specify an application by its alias name (see
ApplicationAliases element in serviceconfig.xml) or the pathname of the actual
executable to launch. The value is first matched to the list of aliases
obtained from the serviceconfig.xml at startup by the Agent Controller. If
no match is found, the launch information contained within the Application
element is used as is. If a match is found, launch information defined for that
alias is used in conjunction with the information defined here, as described
below.
Used by:
LaunchConfiguration
Sub-elements: Variable
Parameter
Attributes:
- executable
This string value specifies the name of the application to be started. It can be either an alias name or the pathname of the actual executable to launch. If it is an alias name, the executable name is replaced with the path value specified in that alias.
- location
(optional) This string value specifies the directory from which the executable is to be launched, sometimes referred to as the working directory for the executable while it is running. If omitted and the executable did not match an alias, the application is executed from the directory in which the Agent Controller resides. If omitted and the executable does match an alias, the location specified for the alias is used.
Element: Variable
This Variable element defines an environment variable and how it should be
positioned within the existing environment. When located within an
Application element, it modifies the environment used when the application is
launched. There can be zero or more of these elements defined for an
Application. If the Application's
executable attribute specifies an alias, the alias's environment variable
settings are applied to the default environment and then the environment
variables defined here are applied on top of them.
Used by: Application
Attributes:
- name
This string value specifies the name of the environment variable.
- value
This string value specifies the value of the environment variable.
- position
(optional) This string value is one of "append", "prepend", or "replace", indicating where to place this environment relative to the current environment. If omitted, the variable is appended to the environment.
Element: Parameter
The Parameter element defines a command line argument to be given the
application when launched. There can be zero or more of these elements defined
for an Application. If the Application's
executable attribute specifies an alias, the alias's command line
arguments are used and then the command line arguments defined here are applied
on top of them.
Used by: Application
Attributes:
- value
This string value specifies a command line argument.
- position
(optional) This string value is one of "append", "prepend", or "replace" indicating where to place this argument relative to the existing command line arguments. If omitted, the argument is appended to the command line.
<Agent Name="org.eclipse.tptp.TimeCollector">
<Interface>org.eclipse.tptp.agent</Interface>
<Interface>org.eclipse.tptp.collector</Interface>
<SingleInstance>0</SingleInstance>
<Bound>0</Bound>
<MaxControllers>-1</MaxControllers>
<MaxObservers>-1</MaxObservers>
<ConfigFile>c:\tptp\agents\org.eclipse.tptp.TimeCollector\config\agentconfig.xml</ConfigFile>
<LaunchConfiguration>
<launchInfo>
<Application executable=".\TimeCollector.exe">
<Parameter value="-serviceconfig ..\config\serviceconfig.xml" />
</Application>
</launchInfo>
</LaunchConfiguration>
</Agent>
Related reference
Agent and Agent Controller Configuration Overview
Copyright (C) 2005, 2006 Intel Corporation.