Decision Guide for Adopting New Technology Agent Controller

Introduction

Starting with TPTP 4.2 there are two Agent Controller API's (i.e. the original Agent Controller, and the new technology Agent Controller). While some developers may want or need to continue using the original Agent Controller, there are good reasons why most developers should begin migrating to the new technology Agent Controller. This guide defines the differences between the two Agent Controller versions, and gives developers decision criteria for when to migrate to the new technology Agent Controller.

Change Taking Place in Agent Controllers

In TPTP release 4.2 the new technology Agent Controller replaces its predecessor on the Windows IA32, IPF, and EM64T platforms. The roadmap plans for the migration of all platforms to the new Agent Controller in coming releases. Once this is accomplished, the original Agent Controller will become obsolete.

The new technology Agent Controller includes a backwards compatibility layer that allows existing clients and agents to communicate with it in the same way they did with its predecessor. Anyone familiar with the previous agent controller can install a package with the new agent controller in it and continue to use it as they did before. Thus, while different platforms will contain different implementations of the agent controller while the migration is taking place, all platforms can continue to use the agent controller in the same fashion (when using the old interfaces).

The new technology Agent Controller implements a new API that is richer and easier to use. In addition to its remote application launching and file transfer services, it provides the ability to dynamically discover agents (such as data collectors), allows multiple instances of the agent controller to run, and allows extensions of the command set using XML fragments. Using the new API, a client application can dynamically discover which agents are installed on the system where the Agent Controller is running. It can therefore adjust the services it offers to a user according to what is available on the system the user chooses to connect to. The new API is available in both C++ and Java implementations.

Feature Comparison

The new technology Agent Controller design is a significantly different evolution of its predecessor. While it includes a compatibility layer that maintains the old APIs, adopters interested in additional functionality and performance improvements in the future should be using the new APIs and removing any dependence on the compatibility layer.

The new technology Agent Controller provides the same basic functionality for launching applications, locally or remotely, as its predecessor. It performs the platform-specific work of starting collector or service agents and setting up command and data channels so that a client can communicate with the agents. The goal of the redesign is to make the agent controller flexible so that it can be easily extended to meet more needs. One such change was replacing the use of binary and custom commands for exchanges between clients, agent controller, and agents to standardizing on the use of XML fragments for all commands. Agent writers can easily define their own command set without impact to the agent controller and clients can create and send all commands in a uniform fashion. Another change towards flexibility was implementing the communication layers as replaceable units so that others can drop in their own version to meet a particular platform or performance need.

With the new technology Agent Controller comes new programming interfaces for both client and agent writers. These API’s are available in both C++ and Java, whereas only Java was available in the past. The concept of agents and collectors (specialized agents with the purpose of collecting data) have been formalized into classes of objects with base implementations that do the standard tasks expected of an agent or collector agent, so that the focus of development is on the unique purpose of the agent.

There are differences in the services available through the old and new agent controller APIs in the 4.2 release. Those features that are currently only available through the old API are expected to be added to the new API in coming releases. ( For information on features going into a particular release, please refer to the release plans which are developed and posted on the TPTP home page http://www.eclipse.org/tptp).

Additional functionality available through the new APIs:

Runtime Discoverable Agents – Using the new API a client application can obtain a list of all the agents installed on the system that the new Agent Controller is executing on. The Agent Controller will automatically launch an agent that is not running, if the client wants its services.
Extensible Agent and Client APIs – Client and agent applications can be developed using either the C++ or Java versions of the APIs. The boiler plate code has already been provided as a foundation on which to build custom applications.
Specialized, Bi-directional Communication Channels – Commands and data flow over distinct channels, so a command can interrupt the flow of data or not – as the agent writer chooses. Also, both commands and data can flow either direction. An agent can notify the client of some event without it being a reply to a command. Additionally, going through firewalls is improved as known ports can be used and multiplexing of commands and data on the same channel is not required.
Concurrent Agent Controller Execution - By providing unique configuration information for the communication (transport) layers for each, multiple Agent Controllers can run at the same time.

Functionality only available through the old APIs:

Extended File Transfer Services - The file transfer services offered through the old API are richer, including support for a progress monitor among others. The new file transfer agent supports just the basic put, get, and delete of files at this time.
Secure Connection with Agent Controller – When connecting with the Agent Controller using the old API there is a configuration option that requires authentication before the Agent Controller can be used.
Dynamic Discovery of Peer Agent Controller – This is a rather specialized functionality that allows an agent to request that it be monitored by an Agent Controller that is different from the one that started it.

Choosing An Agent Controller Interface

If you are implementing an agent application that will interact with the Agent Controller, you have a choice of using the new API or the old API. Following are the things to consider when making that choice.

Platform Coverage – In TPTP 4.2, the new API is available on Windows IA32/EM64T/IPF and Linux IA32/EM64T/IPF platforms. The old API is available on Windows IA32/EM64T/IPF, AIX PPC, HPUX RISC, Linux IA32/PPC64/ZSeries, OS/400 ISeries, Solaris SPARC, and Z/OS Sseries. If the new API is available on all the platforms you require, then we recommend you use the new API. Be sure to check the TPTP published release plans (http://www.eclipse.org/tptp) to see if a missing platform is expected to have support in the timeframe you need. If you don’t see the coverage you need with the new API, you’ll need to use the old API. Note that the old API is not available on Linux EM64T/IPF in TPTP 4.2, but is under consideration for inclusion in TPTP 4.3 release targeted for October, 2006. [Note: The old API is not deprecated at this time, but may be deprecated once new API platform coverage is equivalent or better compared to old API.]
Integration with TPTP Tools, Analysis and UI Frameworks: In 4.2, the TPTP tools and higher level frameworks are integrated with the old API. If you intend to use these frameworks, then you will need to use the old Agent Controller API [or plan on doing substantial changes to adapt these frameworks to use the new API]. In the future, we expect to extend the new API on the client side to support agents using either old API or new API. If you are writing a new client application that does not rely on the existing framework then using the new API is the better choice, but you still need to consider the agents it will communicate with. Clients that use the new API that want to work with an agent that uses the old API need to be constructed with care (start by seeking advice from the Data Communication and Collections team). Communication channels for old agents and new agents can co-exist, so it is possible to write a single client to do both as long as the client uses appropriately formatted commands for each.
Integrated Agent Controller: TPTP 4.2 includes a version of the Agent Controller which runs in the same process as the Eclipse Workbench rather than in its own separate process. It is more convenient to use when there is no need for launching agents and applications on remote systems. This version of the Agent Controller uses only the old API at this time, so an agent that wants to work with it would need to use the old API. Adding support for the new API is expected in the TPTP 4.3 timeframe.

If you are limited by platform support of the old or new API, check the TPTP roadmap or published plan for the upcoming release (http://www.eclipse.org/tptp) to find out when the new Agent Controller will be available on the platforms of interest, before choosing to write to the old interface. You can influence the order in which platforms are supported by submitting enhancement requests to bugzilla naming the platforms of interest and time frame needed, or simply voting for the enhancement of interest if a bugzilla already exists.

SDKs

SDKs for each platform are available from the Downloads page at http://www.eclipse.org/tptp/home/downloads/downloads.html .

Reference documents

C++ and Java reference specifications for the new API can be accessed through the TPTP Data Collection Framework document. Refer to the Extending the Agent Controller and Integrated Agent Controller document to find the Java reference specification for the old API.