The agent.xml File

Introduction

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:

· Interfaces supported by this agent. An interface name represents a set of commands which are supported by the agent. Agent developers define the command set and give it a unique name.

· Number of instances of this agent that can be running simultaneously.

· Whether or not an agent is bound to an application.

· Maximum number of objects allowed to have control rights for the agent.

· Maximum number of objects allowed to have observer rights for the agent.

· The location of the agent’s configuration file.

· Information on how to launch the agent executable.

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.

Note

When referring to file and directory locations in this document, <install-home> is the directory where the Agent Controller package was unzipped.

Elements and Attributes

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
                            LaunchConfiguration

Attributes:

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 it’s 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.

Example agent.xml File

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

</Application>

</launchInfo>
</LaunchConfiguration>
</Agent>

Related reference

Agent and Agent Controller Configuration Overview