IBM Agent Building Environment Developer's Toolkit
Refer to Chapter 1. "Building ABE-Related Components" for assistance in compiling and
linking with IAAgent and associated classes that are described below.
An IAAgent is the
Abstract agent interface object, from which all
concrete (application-specific) agents are derived.
IAAgent contains two categories of member functions:
- Service Functions: provided by the IBM Agent Building Environment Developer's Toolkit and used by concrete
agents to configure and control the components of
the agent. Concrete agents do not override these member functions.
- Callback Functions: defined as virtual functions in the IAAgent
class. The concrete agent that is derived from IAAgent overrides
and implements these functions. The IBM Agent Building Environment Developer's Toolkit calls functions in this
category to request actions such as alert handling.
This category includes the handleAlert() function.
#include <iatk/agent.h>
This class is abstract and cannot be instantiated.
An application builds an agent by deriving an application-specific
(concrete) agent class from IAAgent and invoking the concrete agent's
constructor.
C++: void addAdapter(const char *domain, const char *module,
void *parm, IAAdapterHandle &ahdl)
throw(IAError);
Java: void addAdapter(String domain, String module,
String parm, IAAdapterHandle ahdl)
throws IAError;
Adds a specific adapter into the agent configuration.
An application calls the agent's addAdapter() function to create and
initialize a concrete adapter and to add it to the agent's configuration.
- domain
- The name of the adapter's domain.
- module
- The name of the dll that contains the implementation of the adapter.
The addAdapter() function will load this dll.
Note that the dll extension should not be included as part of the
name.
- parm
- The parameter list that is input to the adapter's newAdapter() factory
function. See the specific adapter's newAdapter() interface for the content
and layout of the parameter list.
- ahdl
- An IAAdapterHandle into which the addAdapter() function will place
the handle for the resulting adapter. The handle is a token that is
used as an input parameter for other agent functions, and identifies
to those functions which concrete adapter to act upon.
Nothing.
- IA_E_WRONG_STATE
- The agent is in the wrong state for the addition of new adapters.
Adapters can only be added prior to invoking the agent's start() function.
C++: void addEngine(const char *kind, const char *module,
void *parm, IAEngineHandle &ehdl)
throw(IAError);
Java: String addEngine(String kind, String module,
void parm, IAEngineHandle ehdl)
throws IAError;
Adds a specific engine into the agent configuration.
An application calls the agent's addEngine() function to create and
initialize a concrete engine and to add it to the agent's configuration.
- kind
- The type or name of the engine.
- module
- The name of the dll that contains the implementation of the engine.
The addEngine() function will load this dll.
Note that the dll extension should not be included as part of the
name.
- parm
- The parameter list that is input to the engine's newEngine() factory
function. See the specific engine's newEngine() interface for the content and
layout of the parameter list.
- ehdl
- An IAEngineHandle into which the addEngine() function will place
the handle for the resulting engine. The handle is a token that is
used as an input parameter for other agent functions, and identifies
to those functions which concrete engine to act upon.
Nothing.
- IA_E_WRONG_STATE
- The agent is in the wrong state for the addition of new engines.
Engines can only be added prior to invoking the agent's start() function.
C++: void addLibrary(const char *map,
const char *topCollector, const char *ImplDllName,
const char *ImplType, int levels, IALibraryHandle &lhdl)
throw(IAError);
Java: void addLibrary(String map,
String topCollector, String ImplDllName,
String ImplType, int levels, IALibraryHandle lhdl)
throws IAError;
Adds a specific library into the agent configuration.
An application calls the agent's addLibrary() function to create and
initialize a library and to add it to the agent's configuration.
- map
- The information needed to find a top Collector in the
persistent storage implementation. For the current file-based Library
it is a path to (but not including) the directory in the file system that
represents the Library's top Collector. It is expressed as
C:\x\y\z\, for
example, where C: is the drive and
x, y, and z are directories in the path above the one
that is used to implement the top Collector. The slash delimiters
match the platform of the current implementation.
For UNIX it has no drive and uses forward slashes, e.g.
home/x/y/z/. The method internally appends the
string that you provide in this map parameter with the string that you
provide in the topCollector parameter (described below) to form the
path to the top Collector. For example, C:\x\y\z\libtop.
- The map to the library. For a file system, this would be the path
to the library.
addLibrary() passes this token to the IALibrary::attachImplementation()
function. See the IALibrary class for more information.
- topCollector
- The name of the top collector of the library.
addLibrary() passes this to the IALibrary::attachImplementation()
function. See the IALibrary class for more information.
This is the name that is assigned to the top Collector in
the selected Library. If this is a new Library, the current file
implementation requires that you have created an empty directory in the
file system, specify its name here, and the path to it via the map
parameter above.
- ImplDllName
- The name of the dll that contains the implementation of the library.
addLibrary() passes this token to the IALibrary::attachImplementation()
function, which will load the dll. See the IALibrary class for more information.
Note that the dll extension should not be included as part of the
name.
- ImplType
- The type of library implies a particular implementation.
Currently file is the only supported implementation.
addLibrary() passes this information to the IALibrary::attachImplementation()
function.
See the IALibrary class for more information.
- levels
- The number of collector levels contained in the library. In the
hierarchical library provided with the IBM Agent Building Environment Developer's Toolkit, the top collector is
level 1, collectors that are children of the top collector are level 2,
collectors that are grandchildren of the top collector are level 3, etc.
addLibrary() passes this token to the IALibrary::attachImplementation()
function. See the IALibrary class for more information.
- lhdl
- An IALibraryHandle into which the addLibrary() function will place
the handle of the resulting library. The handle is a token that is
used as an input parameter for other agent functions, and identifies
to those functions which library to act upon.
Nothing.
C++: void connect(const IAAdapterHandle &ahdl,
const IAEngineHandle &ehdl) throw(IAError);
Java: void connect(IAAdapterHandle ahdl,
IAEngineHandle ehdl) throws IAError;
Connects a specific concrete adapter to a specific concrete engine
in the agent configuration.
An application calls the agent's connect() function
to connect a concrete adapter to a concrete engine in the agent's
configuration.
This connection causes the specified adapter's events to be
delivered to the specified engine for processing.
- ahdl
- The IAAdapterHandle that was returned by the agent's addAdapter()
function. The handle tells the connect function which concrete
adapter to connect.
- ehdl
- The IAEngineHandle that was returned by the agent's addEngine()
function. The handle tells the connect function which concrete
engine to connect.
Nothing.
- IA_E_ADAPTER_HANDLE_BAD
- The IAAdapterHandle is invalid.
- IA_E_ENGINE_HANDLE_BAD
- The IAEngineHandle is invalid.
- IA_E_WRONG_STATE
- The agent is in the wrong state for the addition of adapter-engine
connections. Connections can only be made prior to invoking the
agent's start() function.
C++: long getEventsCompleted() const;
Java: int getEventsCompleted();
Returns the number of events that have been processed since the agent
was started.
None.
The number of events that have been processed since the agent
was started.
C++: void loadConductSet(const IALibraryHandle &lhdl,
const IAEngineHandle &ehdl,
const char *csname, const char *selector)
throw(IAError);
Java: void loadConductSet(IALibraryHandle lhdl,
IAEngineHandle ehdl,
String csname, String selector)
throws IAError;
Loads a conduct set from the library into the engine.
An application calls the loadConductSet() function to load a specific
conduct set into the engine. The engine will process the conduct set
when the next event occurs for the given selector.
Only rules with an "Active" state are loaded.
- lhdl
- The IALibraryHandle that was returned by the agent's addLibrary()
function. The handle tells the loadConductSet() function which library
to load the conduct set from.
- ehdl
- The IAEngineHandle that was returned by the agent's addEngine()
function. The handle tells the loadConductSet() function which concrete
engine to load the conduct set into.
- csname
- The name of the conduct set that is to be loaded.
If the conduct set is not in the top collector of the IALibrary,
then the name includes the path of collectors
(not including the top Collector itself)
that must be traversed to reach the conduct set. For example:
\collectorA\collectorB\conductSetName (OS/2, Windows)
/collectorA/collectorB/conductSetName (AIX)
- selector
- The selector that identifies the conduct set. This can be a userid
or a group name, and is used to associate related conduct sets. Only
events that contain this selector will cause processing of this conduct
set to occur.
Nothing.
C++: void reset(const char *selector) throw(IAError);
Java: void reset(String selector) throws IAError;
Requests that the agent discard all information for a particular selector.
An application calls the reset() function to cause the agent
to stop processing events for the specified selector, and
then to discard all information and state related to the specifed selector.
Generally, the intended effect of this call is that after it completes
the agent (including all adapters and engines) are in the same state as
if it had never processed any work on behalf of the given selector.
However, achieving this intent depends on the correct behavior of the
adapters and engines in their response to calls made to them.
The specific sequence of actions taken during the reset() call
is described below in the section "Reset Sequence".
- selector
- The selector whose agent-related information is to be discard.
Nothing.
- IA_E_WRONG_STATE
- The agent is in the wrong state for the reset() call.
Calls to the reset() function can be made while the agent is
in the running state; that is, after a call to the agent's start()
function returns, and before a call to the agent's stop() function
is made.
The processing of the reset() call comprises the following steps:
- The quiesce() function of each adapter is called to request that
the adapters stop generating events for the specified selector.
- Processing is delayed until all of the engines have completed
processing of any in-progress events for the specified selector.
- The reset() function of each engine is called to request that
the engines discard all rule sets associated with the specified
selector.
- The reset() function of each engine is called to request
that the adapters discard configuration and state information
associated with the selector.
C++: void start() throw(IAError);
Java: void start() throws IAError;
Start the agent.
An application calls the agent's start() function to start the agent and all
of it's configured adapters and engines.
None.
Nothing.
C++: void stop() throw(IAError);
Java: void stop() throws IAError;
Stops the agent.
An application calls the agent's stop() function to stop the agent and all
of it's configured adapters and engines.
None.
Nothing.
- IA_E_WRONG_STATE
- The agent is in the wrong state to be stopped. The agent can only be
stopped after having invoked the agent's start() function.
C++: void unloadConductSet(const IALibraryHandle &lhdl,
const IAEngineHandle &ehdl,
const char *csname, const char *selector)
throw(IAError);
Java: void unloadConductSet(IALibraryHandle lhdl,
IAEngineHandle ehdl,
String csname, String selector)
throws IAError;
Unloads a conduct set from an engine.
An application calls the agent's unloadConductSet() function to remove a specific
conduct set from the engine. The engine will unload the conduct set as soon
as all pending events for this conduct set have completed.
- lhdl
- The IALibraryHandle that was returned by the agent's addLibrary()
function. The handle tells the unloadConductSet() function which library
to obtain conduct set information from.
- ehdl
- The IAEngineHandle that was returned by the agent's addEngine()
function. The handle tells the unloadConductSet() function which concrete
engine to unload the conduct set from.
- csname
- The name of the conduct set that is to be unloaded. If the conduct
set is not in the top collector of the IALibrary, then the name includes the path of
collectors (not including the top Collector itself)
that must be traversed to reach the conduct set. For example:
\collectorA\collectorB\conductSetName (OS/2, Windows)
/collectorA/collectorB/conductSetName (AIX)
- selector
- The selector that identifies the conduct set. This should match
the selector that was used when this conduct set was originally loaded.
Nothing.
C++: void dbgInfo(ostream &o) const;
Java: void dbgInfo(OutputStream o);
Java: void dbgInfo(Writer o);
Prints a debugging representation of this agent.
- o
- The output stream to which the output is written.
Nothing.
C++: virtual void handleAlert(const char *id,
const IAAlertLevel sev,
IAFactSet &fset);
Java: void handleAlert(String id,
IATypes.IAAlertLevel sev,
IAFactSet fset)
This method gets control when a component of the agent (engine, adapter,
library, etc.) generates an alert. The alert could be a warning of some
potential problem, a notification that the component is disabled in some
way, or an indication that a fatal condition has caused the component to
cease all operations.
- *id
-
String containing an alert identifier, in the form of
component:domain:problemType.
- sev
- An IAAlertLevel indication of the severity of the alert.
Valid IAAlertLevel values are:
- (C++) IAWarning
-
- (Java) IATypes.IAAlertLevel.IAWarning
-
- Indicates that there is potential for a problem, and some action may be
required to prevent it from happening.
- (C++) IADegraded
-
- (Java) IATypes.IAAlertLevel.IADegraded
-
- Indicates that the component is working in a degraded mode. Generally,
the degradation would have a limited scope (i.e. broken for only a particular
selector, or only a particular function isn't working). This is more severe
than a warning, but the component is still able to 'limp along'.
- (C++) IAFatal
-
- (Java) IATypes.IAAlertLevel.IAFatal
-
- Indicates that the component is no longer functional.
- *fset
- Fact set containing facts that describe the error.
Standard facts that are included by the IBM Agent Building Environment Developer's Toolkit with every alert
(not necessarily in this order) are:
- FailingComponentType(String)
- FailingType(String)
- FailingDomain(String)
- FailingName(String)
The type, domain, and name are analogous to EventType, EventName
and EventDomain.
If the alert is related to the processing of a particular event, then
the following facts may also be included by the IBM Agent Building Environment Developer's Toolkit
(not necessarily in this order):
- FailingEventId(String)
- FailingEventType(String)
- FailingEventName(String)
- FailingEventDomain(String)
- FailingEventSelector(String)
- FailingEventTime(String String)
Any additional facts that may be included in the fact set are determined by
(and set by) the failing component, and should be documented by the component
(most likely in the documentation describing the component's generateAlert() method).
If the handleAlert() method is not implemented in the concrete adapter,
the default implementation will display an alert message, followed by the
alert id, the severity, and the facts
The default implementation takes additional action based on the severity
of the alert, as follows:
- IAWarning
- Agent continues running. No additional action is taken.
- IADegraded
- Agent continues running. No additional action is taken.
- IAFatal
- Agent shuts down.
The shutdown occurs on a separate thread to prevent deadlocks with the
calling component. Control is returned to the calling component immediately
after the shutdown thread is started. The shutdown is accomplished by calling
the concrete agent stop() method, and then exiting the process.
This method receives synchronous control directly from the reporting component.
The component may be in the middle of processing an event, and could be
delaying the event from completing. Therefore, if you implement any actions
that involve invoking any of the IBM Agent Building Environment Developer's Toolkit API's, you must implement those actions
on a separate thread, and return immediately on the handleAlert() thread. Otherwise,
your agent may experience a deadlock condition.
You do not need to start a new thread to loop through the input fact set
analyzing or printing the facts.
Nothing.
The synchronous interface allows the agent to throw an IAError back
to the adapter. The types of error are dependent on the specific agent's
implementation of handleAlert().
The default implementation of handleAlert() does not throw any
IAErrors.
An IAAdapterHandle is a token that is used to access the IAAgent's IAAdapter objects.
An agent program instantiates the handle, and then initializes it through the
IAAgent::addAdapter() function. The agent program then uses the IAAdapterHandle as an
input parameter to other IAAgent functions.
#include <iatk/handles.h>
C++: IAAdapterHandle()
Java: IAAdapterHandle()
Creates a new adapter handle object.
None.
C++: int operator ==(const IAAdapterHandle &rhs) const
This is the equality operator overload.
- rhs
- An adapter handle object
- true(1)
- the adapter handles are equal - both handles represent the same IAAdapter object.
- false(0)
- the adapter handles are not equal - the handles represent different IAAdapter objects.
C++: int operator !=(const IAAdapterHandle &rhs) const
This is the inequality operator overload.
- rhs
- An adapter handle object
- true(1)
- the adapter handles are not equal - the handles represent different IAAdapter objects
- false(0)
- the adapter handles are equal - both handles represent the same IAAdapter object.
C++: int isValid() const
The isValid() function checks to see whether the adapter handle object
is valid. The adapter handle object is valid if it has been associated
with a valid IAAdapter object. The IAAgent::addAdapter() function is one
method that sets up this valid association.
None.
- true(1)
- the adapter handle is valid - it is associated with an IAAdapter object.
- false(0)
- the adapter handle is not valid - it is not associated with any IAAdapter object.
An IAEngineHandle is a token that is used to access the IAAgent's IAEngine object.
An agent program instantiates the handle, and then initializes it through the
IAAgent::addEngine() function. The agent program then uses the IAEngineHandle as an
input parameter to other IAAgent functions.
#include <iatk/handles.h>
C++: IAEngineHandle()
Java: IAEngineHandle()
Creates a new engine handle object.
NONE.
C++: int operator ==(const IAEngineHandle &rhs) const
This is the equality operator overload.
- rhs
- An engine handle object
- true(1)
- the engine handles are equal - both handles represent the same
IAEngine object
- false(0)
- the engine handles are not equal - the handles represent different
IAEngine objects.
C++: int operator !=(const IAEngineHandle &rhs) const
This is the inequality operator overload.
- rhs
- An engine handle object
- true(1)
- the engine handles are not equal - the handles represent different
IAEngine objects.
- false(0)
- the engine handles are equal - both handles represent the same
IAEngine object.
An IALibraryHandle is a token that is used to access the IAAgent's IALibrary object.
An agent program instantiates the handle, and then initializes it through the
IAAgent::addLibrary() function. The agent program then uses the IALibraryHandle as an
input parameter to other IAAgent functions.
#include <iatk/handles.h>
C++: IALibraryHandle()
Java: IALibraryHandle()
Creates a new library handle object.
NONE.
C++: int operator ==(const IALibraryHandle &rhs) const
This is the equality operator overload.
- rhs
- A library handle object
- true(1)
- the library handles are equal - both handles represent the same
IALibrary object.
- false(0)
- the library handles are not equal - the handles represent different
IALibrary objects.
C++: int operator !=(const IALibraryHandle &rhs) const
This is the inequality operator overload.
- rhs
- A library handle object
- true(1)
- the library handles are not equal - the handles represent different
IALibrary objects.
- false(0)
- the library handles are equal - both handles represent the same
IALibrary object.
C++: int isValid() const
The isValid function checks to see whether the library handle object
is valid. The library handle object is valid if it has been associated
with a valid library object. The IAAgent::addLibrary() function is one
method that sets up this valid association.
None.
- true(1)
- the library handle is valid - it is associated with an
IALibrary object.
- false(0)
- the library handle is not valid - it is not associated with any
IALibrary object.
[ Top of Page | Previous Page | Next Page | Table of Contents ]