Contents
Note
When referring to file and directory locations in this document, <install-home> is the directory where the Agent Controller package was unzipped.
The pluginconfig.xml file resides under <install-home>\plugins\<plugin-name>\config. It is the mechanism for extending the global environment and application aliases defined in serviceconfig.xml according to the needs of individually bundled applications. Extending the environment settings defined in serviceconfig.xml has an impact on all applications (including agents) launched by the Agent Controller, as they all inherit that environment. This allows a "plugin" to make its applications locatable by other processes started by the Agent Controller (e.g., by adding its path to the CLASSPATH environment variable). Extending the application alias list is the means for a new application to be launched if the Agent Controller is configured to restrict its launching services to only those in the list.
Thus, pluginconfig.xml provides a mechanism for packaging add-on components which are optional for the basic install of the Agent Controller. Since the serviceconfig.xml file itself is not modified, the removal of the add-ons is equally easy.
Agents may require both a pluginconfig.xml and an agent.xml. The agent.xml file is required to define an agent application if you want the new agent controller to when looking for available agents (i.e., be able to discover it). The pluginconfig.xml is required if the agent needs to extend the serviceconfig.xml environment or alias list. The use of the agent.xml file will replace the use of pluginconfig.xml in a future release.
Note
The term "plugin" used here is only a loose reference to an Eclipse plug-in. It came about because actual plug-ins were used initially. But now it is a misnomer, as this configuration file can refer to any application without its being wrapped up as a plug-in suitable for installation into the Eclipse workbench.
The pluginconfig.xml file contains the following main segments:
The hierarchy of the elements contained in the pluginconfig.xml file is shown below. The order of elements shown at the same level is unimportant. Hyperlinks in the hierarchy link to the formal element description in the Elements and Attributes section.
PluginConfiguration
AgentControllerEnvironment
Variable
Option
Application
Variable
Parameter
Agent
Option
Element: PluginConfiguration
Sub-elements: AgentControllerEnvironment
Option
Application
Agent
- requires
- (optional) This string value is a comma-separated list of plug-in name(s) which this configuration is dependent upon. As of TPTP 4.0, a version identifier suffix has been added to plug-in names. It consists of an underscore character followed by the version number for the release. For example: org.eclipse.tptp.platform.agentcontroller_4.0.0. To ensure plug-in compatibility for applications that have dependencies on plug-ins from earlier releases (plug-ins that do not have a version identifier suffix), you have the option of specifying the plug-in name for the "requires" attribute excluding the version identifier. In this case, the Agent Controller's configuration loader will first try to locate the full plug-in name including the version identifier suffix. If unsuccessful, the configuration loader then searches for the plug-in name excluding the version identifier suffix. If there is more than one plug-in with the same name, the first plug-in name returned by the operating system will be used.
Used by: PluginConfiguration
Sub-elements: Variable
This Variable element defines an environment variable and how it should be positioned within the existing environment to form the new default environment for all applications and agents launched. There can be zero or more of these elements defined for the AgentControllerEnvironment
Used by: AgentControllerEnvironment
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 existing default environment.
Element: Option
An Option as a top element in
PluginConfiguration is used to specify arbitrary configuration data that will be
passed to every agent that registers itself with the Agent Controller. This
information is included in the property information returned for every agent, to
a client. The agent can interpret this information (or not) as it sees fit.
Option information is only given to agents that are using the original API
(backwards compatibility layers) of the Agent Controller. Use the agent.xml
configuration file for providing configuration information to an agent using the
new API.
Element: ApplicationUsed by: Agent
Attributes:
- name
- This string value specifies the namespace for the option.
- type
- This string value specifies the name of the option.
- value
- This string specifies the value of the option.
Used by: PluginConfiguration
Sub-elements: Variable
- executable
- This string value specifies the alias name for the application executable specified in the path attribute. Clients must use this name to identify this application. If the extends attribute is also specified, the name given here should match a previously defined alias.
- path
- This string value specifies the full pathname of the application to launch. This is used in place of the alias name when launching the application executable.
The attribute is ignored if the extends attribute is specified.- 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.
- extends
- (optional) This string value specifies the configuration name for a previously defined application alias. However, configuration names are not supported so the value of this attribute should be set to "default". If extends is present (regardless of value), it indicates that the information contained in this Application should extend the launch information previously defined in the matching application alias. It is not allowed to change the path value (i.e., executable being launched). If no match to the executable name is found, this Application element has no effect.
Element: Variable
This Variable element defines an environment variable and how it should be
positioned within the existing environment when the application is launched.
There can be zero or more of these elements defined for an Application.
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 default environment.
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.
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.
Element: Agent
Provides configuration
information for a particular agent. Only used by agents that are using the
original
API (backwards compatibility layers) of the Agent Controller. Use the agent.xml
configuration file for providing configuration information to an agent using the
new API.
Used by: PluginConfiguration
Sub-elements: Option
Attributes:
- name
- This string value specifies the name of the agent to which this configuration information should be applied.
- type
- (optional) This string value specifies a type of agent.
- dataChannelSize
- (optional) This string value specifies the amount of shared memory to allocate for inter-process communication. The values take the form of a positive integer with the suffix M or K to indicate Megabyte or Kilobytes, respectively, or no suffix which indicates bytes. Example values: "16M", "8K", or "16000".
- logFile
- (optional) This string specifies a fully qualified pathname of a file. If specified, the data which would normally go through the data channel to the client will be written to this file instead.
- client
- (optional) This string specifies whether this agent is interacting with a client. The possible values are "DYNAMIC" or "HEADLESS". HEADLESS indicates there is no associated client. The default is DYNAMIC.
- extends
- (optional) This string value specifies the configuration name for a previously defined Agent. However, configuration names are not supported so the value of this attribute should be set to "default". If extends is present (regardless of value), it indicates that the information contained in this Agent should extend the configuration information previously defined in the matching Agent element. Used to expand the list of Options associated with a particular agent.
Element: Option
An Option
sub-element within an Agent element is used to specify arbitrary
configuration data that will be passed to the agent when it registers itself
with the Agent Controller. The agent can interpret this information (or
not) as it sees fit.
Used by: Agent
Attributes:
- name
- an arbitrary string naming the option (i.e. namespace)
- type
- an arbitrary string naming the type of the option (i.e. option name)
- value
- an arbitrary string value for the option
<PluginConfiguration requires="org.eclipse.tptp.platform.collection.framework">
<AgentControllerEnvironment>
<Variable name="CLASSPATH_MY_AGENTS"
position="append"
value="%PLUGINS_HOME%\org.eclipse.tptp.myagents\lib\coreagent.jar"
/>
</AgentControllerEnvironment>
<Application
executable="MyAgent"
location="%SYS_TEMP_DIR%"
path="%JAVA_PATH%">
<Variable name="CLASSPATH"
position="append"
value="%PLUGINS_HOME%\org.eclipse.tptp.myagents\jmx\lib\jmxagent.jar"
/>
<Variable name="CLASSPATH"
position="append"
value="%CLASSPATH_MY_AGENTS%"
/>
<Parameter position="append"
value="-Dapp_home=%MY_HOME%"
/>
<Parameter position="append"
value="-DagentXML=%PLUGINS_HOME%
\org.eclipse.tptp.myagents\jmx\agentXML\MyAgent.xml"
/>
</Application>
<Option name="org.eclipse.tptp.Myagents"
type="version" value="2.0"/>
</PluginConfiguration>
Related Reference
Agent and Agent Controller Configuration Overview
Copyright (C) 2006, 2007 Intel Corporation.