The pluginconfig.xml File

Contents

 

Note

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

Introduction

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:

 

Plug-In Configuration

 

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

       

Elements and Attributes

 

Element: PluginConfiguration
This is the root element of the plug-in configuration. Only one occurrence of the  AgentControllerEnvironment is allowed. All the other elements (Option, Application, and Agent) allow multiple occurrences.  Any of the sub-elements may be omitted.

Sub-elements:     AgentControllerEnvironment

                            Option
                            Application
                            Agent
                           
Attributes:

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.

Element: AgentControllerEnvironment
The AgentControllerEnvironment element encloses one or more Variable elements which will extend the global environment variables defined in serviceconfig.xml.  These will become a part of the environment used in launching all applications.


Used by: PluginConfiguration

Sub-elements:     Variable

 

Element: 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.

Used 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.
Element: Application
The Application element defines or extends an alias name and launch information for an application. It may include environment settings that are only visible to this particular application when it is launched.  This application alias is added to the list defined within the ApplicationAliases element in serviceconfig.xml.


Used by: PluginConfiguration

Sub-elements:     Variable

                            Parameter

Attributes:

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.

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.

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

Example pluginconfig.xml File

 

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