IBM Agent Building Environment Developer's Toolkit


Chapter 3. Adapter Reference Material

Compiling and Linking with Adapter Classes

Refer to Chapter 1. "Building ABE-Related Components" for assistance in compiling and linking with the adapter classes that are described below.

Class IAAdapter

An IAAdapter is the Abstract adapter interface object, from which all concrete (domain-specific) adapters are derived.

IAAdapter contains two categories of member functions:

  1. Service Functions: provided by the IBM Agent Building Environment Developer's Toolkit and used by concrete adapters during initialization and for generating agent events. Concrete adapters do not override these member functions. This category includes the registerProcedure() and notify() member functions.

  2. Callback Functions: defined as virtual functions in the IAAdapter class. The concrete adapter that is derived from IAAdapter overrides and implements these functions. The IBM Agent Building Environment Developer's Toolkit calls functions in this category to request actions such as adapter self-identification, retrieval of additional facts regarding an in-progress event, and initiating actions which event processing has determined to be appropriate. This category includes the identify(), start(), stop(), shutdown(), answerQuery(), testCondition(), performAction(), eventComplete(), restart(), quiesce() and reset() functions.

Header File

#include <iatk/adapter.h>

Constructors

This class is abstract and cannot be instantiated.

An adapter is added to an agent by constructing an instance of a domain-specific (concrete) adapter class derived from IAAdapter. The domain-specific adapter class' constructor is invoked via the (global) newAdapter() "factory" function that must be included in each adapter module. See the description for newAdapter for the requirements on the implementation of newAdapter().

Service Functions

notify
   C++:  void notify(IATriggerEvent &event) throw(IAError);

   Java: void notify(IATriggerEvent event) throws IAError;

Begins processing of a new event by the agent.

A concrete adapter calls the notify() function to inform all observing engines of an event that should be processed using the header and facts contained within trigger event event.

The observing engines (always) process the event asynchronously, hence the call to notify() may (and usually does) return before event processing has completed or perhaps has even begun. Completion of all engine processing of the event is signaled by a call to the adapter's eventComplete() member function.

Each instance of an IATriggerEvent object can be used on at most one call to notify(). This requirement guarantees uniqueness of the event ids for events. The notify() function throws an exception if event is an IATriggerEvent that has been used on a previous notify() call.

The caller is free to destroy event immediately upon return from notify().

Threading and Locking Considerations:
The IBM Agent Building Environment Developer's Toolkit framework and/or observing engines may temporarily delay the return from the notify() call, for example, to control the rate at which events are queued at an engine. To allow such flow control to work without stalls, the notify() must not be issued on the thread on which an adapter callback function is running, ie. it must be issued from a thread owned by the adapter. Further, the adapter thread that calls notify() must not hold any locks (mutexes, semaphores, etc.) that would cause the adapter's answerQuery(), testCondition(), performAction() or eventComplete() functions to block.

Parameters:

event
The trigger event (IATriggerEvent) representing the event to be processed.

The event header (IAEventHeader) contained within the trigger event is completed by providing the domain name and event time stamp attributes. The modified trigger event is provided to each of the engines that are observing this adapter's events. A copy of the completed event header is supplied on other function calls related to this event (for example, answerQuery() and eventComplete() to identify the event).

The IAFactSet within the trigger event is not inspected or modified by notify(). Engines typically use the facts within this fact set as short-term facts that are inputs for the processing of this event.

Return:
Nothing.

If no exceptions occur, event processing was successfully initiated and the event was delivered to one or more engines. Event processing will occur, and eventComplete() will be called when processing is finished.

Exceptions (IAError):

IA_E_WRONG_STATE
A call to notify() is made before the adapter's start() function has been called, or after the adapter's stop() function has been called. This error prevented the delivery of the event to any engine. No event processing will occur; eventComplete() will not be called for this event.

IA_E_CANT_REUSE_EVENT
The input IATriggerEvent has been used on a previous notify(). This error prevented the delivery of the event to any engine. No event processing will occur; eventComplete() will not be called for this event.

IA_E_CANT_DELIVER_EVENT
The engine was unable or unwilling to accept delivery of the event. No event processing will occur; eventComplete() will not be called for this event.

IA_E_INTERNAL_ERROR
Notify() caught an unknown exception during processing.

Notes:

  1. The set of engines that is observing (processing) the events generated by an adapter is determined at the time the agent configuration is established, usually at agent startup. Once the agent configuration is established, it remains static.

  2. The adapter that initiates event processing will receive an eventComplete() call, as described above. Adapters to which answerQuery(), testCondition(), or performAction() calls are made during event processing will also receive eventComplete() calls. Each adapter receives at most one eventComplete() call.

registerProcedure
   C++:  void registerProcedure(const char *procName,
                                  IAProcType type, const char *signature,
                                  IAProcToken token)
                                  throw(IAError);

   Java: void registerProcedure(String procName, int type,
                                    String signature, IAProcToken token)
                                    throws IAError;

Registers a sensor or effector procedure with the agent.

Parameters:

procName
For C++, a pointer to a null-terminated string (for Java, a String) containing the domain-specific identifier for the sensor or effector procedure.

This identifier is part of the fully-qualified name for the procedure. The fully-qualified name for the procedure is formed by concatenating the domain name of the adapter making this call, a colon (:) and the identifier specified on this call. For example, the fully-qualified name of an NNTP procedure to obtain new news articles might be "NNTP:GetNewNews."

type
The type of procedure being registered as a value from the IAProcType enumeration: IABooleanSensorProc (boolean sensor procedure), IASensorProc (sensor procedure), IAEffectorProc (effector procedure).

signature
For C++, a pointer to a null-terminated string (for Java, a String) specifying the number and types of the terms that are expected in the atom that is provided as procedure's input. Specify this string as a blank- or comma-separated list of the following signature entries:

Integer
The term must be an integer value (bound term).

IntegerLVar
The term may be an integer logical variable (free term).

String
The term must be a null-terminated string value (bound term).

StringLVar
The term may be a string logical variable (free term).

Symbol
The term must be a symbol value (bound term).

SymbolLVar
The term may be a symbol logical variable (free term).

The signature entries can be specified in lower, upper or mixed case.

Signature entires that specify free terms (IntegerLVar, StringLVar, SymbolLVar) are allowed only in signatures for (non-boolean) sensor procedures, i.e. type is IASensorProc. Such signature entries indicate that the procedure is able to provide facts that supply bindings for the free terms. However, depending on the way in which an engine processes the event, it is permissible that the sensor be called with the terms provided as already-bound terms rather than logical variables. For example, in a particular call to answerQuery(), a term that was registered as StringLVar can instead be supplied as String.

For more information about free terms and bound terms, see Chapter 2. "Writing Rules and Understanding Rule Inferencing".

token
A token assigned by the adapter to represent the procedure. The token specified on this call is passed as an argument on calls to the adapter's testCondition(), answerQuery(), and performAction() methods to identify the sensor or effector procedure to be run.

The token is of type IAProcToken, which supports the use of either long integer or pointer values as token values.

It is the adapter's responsibility to assign tokens uniquely. The registerProcedure() function does not check the token values for uniqueness.

Return:
Nothing.

Exceptions (IAError):

IA_E_WRONG_STATE
A call to registerProcedure() is made before the adapter's identify() function has been called, or after that call has returned.

IA_E_PROC_NAME_BAD
Procedure name is null string or was not specified.

IA_E_PROC_SIGNATURE_BAD
Procedure signature was not specified.

IA_E_PROC_SIGNATURE_ITEM_BAD
The signature contains an invalid signature entry.

IA_E_PROC_SIGNATURE_HAS_VARS
The signature contains an entry for a free term but the procedure type is not IASensorProc.

IA_E_PROC_ALREADY_REGISTERED
Sensor or effector procedure name is the same as a previously registered procedure.

IA_E_INTERNAL_ERROR
registerProcedure() caught an unknown exception during processing.

generateAlert
   C++:  void generateAlert(const char *type,
                            const IAAlertLevel sev,
                            const IAFactSet *fset,
                            const IAEventHeader *evhdr = NULL)
                            const throw(IAError);

   Java: void generateAlert(String type,
                            IATypes.IAAlertLevel sev,
                            IAFactSet fset,
                            IAEventHeader evhdr) throws IAError

         void generateAlert(String type,
                            IATypes.IAAlertLevel sev,
                            IAFactSet fset) throws IAError

Informs the agent that an alert condition has occurred in the adapter, so that the agent can take actions to correct the problem as necessary.

A concrete adapter calls the generateAlert() function to inform the agent that a problem or unusual condition has occurred, or will occur if some corrective action is not taken. The agent will receive this alert via it's handleAlert() method, which can take appropriate action.

Threading and Locking Considerations:
The agent synchronously receives the alert notification on the same thread that generates it. Therefore, the agent's corrective action should be started on a new thread.

Parameters:

*type
A string containing an identifier for the type of error that occurred. The identifier is comparable to the EventType fact of an event.

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.

*evhdr
(Optional) Event header containing event that was being processed when the problem occurred.

Return:
Nothing.

Exceptions (IAError):

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

Adapter Control Callback Functions

identify
   C++:  virtual IABool identify() = 0;

   Java: boolean identify()

Solicits registration of sensor and effector procedures.

The Agent Building Environment Developer's Toolkit framework calls an adapter's identify() function during Agent initialization to request that the adapter register the sensor and effector procedures that it provides.

The adapter's processing of the identify() function should call registerProcedure() (zero or more times) to register the procedures provided by the adapter and then return a success or failure indication as the function result.

There is no implementation of this function in IAAdapter; the adapter class derived from IAAdapter must override and implement this function. If an adapter has no sensor or effector procedures, its implementation of identify() can simply return a success indication.

This function is called once for each adapter instance created by the adapter module's newAdapter() function.

Parameters

None.

Return (IABool/boolean):

The adapter's identify() function should return the following success or failure indication:

1 (true)
Sensor or effector procedure registered successfully.

0 (false)
Errors occurred during registration of procedures.

Agent initialization is aborted if any adapter returns false from its identify() function.

reset
   C++:  virtual IABool reset(const char* selector);

   Java: boolean reset(String selector);

Resets adapter data for the specified selector.

The Agent Building Environment Developer's Toolkit framework calls an adapter's reset() function during agent reset processing to request that the adapter discard state or configuration data that is associated with the specified selector. When reset() is called, the adapter has already been quiesced and all outstanding events for this selector have completed. Generally, the semantic effect of the reset() call should be to discard selector-related information so that afterwards the adapter is in the same state as if it had never seen or processed any calls for the given selector.

As a result, after this call the adapter should no longer be generating trigger events for the specified selector (until subsequent sensor or effector calls result in new selector-related work for the adapter).

The IAAdapter class provides a default implementation of this function that calls the adapter's start() function.

Parameters:

selector
The selector for which the adapter is to reset

Return (IABool/boolean):

The adapter's reset() function should return the following success or failure indication:

1 (true)
Reset of adapter processing was successful.

0 (false)
Errors occurred during reset of the adapter.

Notes

  1. Since the adapter should no longer be generating events for the specified selector once the reset() call completes, the call to an adapter's reset() function is not followed by a call to its restart() function.

restart
   C++:  virtual IABool restart(const char* selector);

   Java: boolean restart(String selector);

Re-starts adapter processing for the specified selector.

The Agent Building Environment Developer's Toolkit framework calls an adapter's restart() function after a conduct set has been dynamically loaded into or unloaded from the configuration.

When restart() is called, all conduct sets for this selector have completed inferencing on the AGENT:CSCHANGE event.

Once an adapter's restart() function is called, it is valid for the adapter to start generating events for this selector. This event generation can continue until the adapter's stop() or quiesce() function is called and the call to stop() or quiesce() returns.

The IAAdapter class provides a default implementation of this function that invokes the adapter's start() function. This means that the adapter's start() function must be prepared to be invoked more than once if it does not implement the restart() function.

Parameters:

selector
The selector for which the adapter is to re-start.

Return (IABool/boolean):

The adapter's restart() function should return the following success or failure indication:

1 (true)
Restart of adapter processing was successful.

0 (false)
Errors occurred during restart of the adapter.

shutdown
   C++:  virtual void shutdown();

   Java: void shutdown();

Terminates an adapter.

The Agent Building Environment Developer's Toolkit framework calls an adapter's shutdown() function during the agent shutdown sequence to request that the adapter perform an orderly shutdown.

An adapter's shutdown() function is called after that adapter's stop() function has been called and returns and after after all event processing within the agent has been completed. No more calls to the adapter's event-related functions (answerQuery(), testCondition(), performAction(), and eventComplete()) will occur once shutdown() has been called.

The IAAdapter class provides a default implementation of this function that simply returns.

Parameters

None.

Return:
Nothing.

start
   C++:  virtual IABool start();

   Java: boolean start();

Begins active adapter processing.

The Agent Building Environment Developer's Toolkit framework calls an adapter's start() function during the agent startup sequence to request that the adapter begin active processing.

When start() is called, the agent's configuration of adapters and engines has been established, engines have been started, and processing of the automatically-generated AGENT:CONFIG and AGENT:STARTING events has been completed.

Once an adapter's start() function is called, it is valid for the adapter to generate new events for processing by calling the notify() function. This event generation can continue until the adapter's stop() function is called and the call to stop() returns.

The IAAdapter class provides a default implementation of this function that simply returns true.

Parameters:

None.

Return (IABool/boolean):

The adapter's start() function should return the following success or failure indication:

1 (true)
Startup of adapter processing was successful.

0 (false)
Errors occurred during startup of the adapter.

Agent startup is aborted if any adapter returns false from its start() function.

Notes:

  1. The functions performed in the adapter's start() function are highly dependent on the nature of the adapter. For an adapter that automatically monitors some external conditions, the start() function will often include the creation of monitoring and event-generating threads.

  2. An adapter may be designed to allow for "rules-based" configuration by providing effector (or sensor) procedures that pass configuration information to the adapter. Since this configuration information is usually required before the adapter can begin processing, such adapters usually require that their configuration sensor or effector procedures be called during processing of the automatically-generated AGENT:CONFIG or AGENT:STARTING events. This is accomplished by having appropriate rules defined in the agent's active rule set.

    Because the processing of the AGENT:CONFIG and AGENT:STARTING events is completed before the call to an adapter's start() function is made, it is reasonable for the processing in the start() function to verify the configuration information it already has, and refuse to start (return false) if insufficient configuration is present.

  3. The AGENT:CONFIG and AGENT:STARTING events are designed to have slightly different uses when configuring an agent's adapters in a multi-user agent.

    The AGENT:CONFIG event is intended to be used to configure adapters with configuration information that has a per-agent, rather than per-user scope. For example, this event could be used to establish the HTTP proxy server that the HTTP adapter will use for all user's HTTP requests, or the news server that the NNTP adapter will use for all users. Because of this intent, the AGENT:CONFIG event is associated with the normal (i.e. not broadcast) rule-set selector of AGENT_CONFIG. The AGENT:CONFIG event will be run only on those rule sets that are specifically associated with the AGENT_CONFIG selector.

    In contrast, the AGENT:STARTING event is intended to be used to configure adapters with configuration information that is user specific. For example, this event could be used to establish the set of news groups that are interesting to a particular user. Because of this intent, the AGENT:STARTING event is associated with the special broadcast rule-set selector of AGENT. Thus, the AGENT:STARTING event will be run on all of the rule sets loaded in the engine. This permits each user's rule set to have AGENT:STARTING rules that configure the agent's adapters according to that particular user's needs.

stop
   C++:  virtual IABool stop();

   Java: boolean stop();

Stops active adapter processing.

The IBM Agent Building Environment Developer's Toolkit framework calls an adapter's stop() function during the agent shutdown sequence to request that the adapter end active processing. In particular, this call is a request that the adapter stop generating new events via calls to notify().

Before returning from stop(), the adapter should make arrangements to prevent new notify() calls from occurring. If an adapter calls notify() after returning from a call to stop(), that call to notify() may result in an error or exception and in all cases will be ignored.

Even though the adapter should cease generating new events, it should remain prepared for sensor and effector calls for in-progress events until its shutdown() function is called.

Parameters:

None.

Return (IABool/boolean):

The adapter's stop() function should return the following success or failure indication:

1 (true)
Adapter processing was stopped successfully.

0 (false)
Errors occurred that prevented stopping of processing.

Orderly shutdown of the agent may be aborted if any adapter returns false from its stop() function. Instead, the agent exits immediately, without calling the shutdown() function of any adapter.

quiesce
   C++:  virtual IABool quiesce(const char* selector);

   Java: boolean quiesce(String selector);

Tells the adapter to stop generating new events for this selector.

The Agent Building Environment Developer's Toolkit framework calls an adapter's quiesce() function when it is about to dynamically load or unload a conduct set for this selector, or when it is about to reset the agent for this selector.

When quiesce() is called, the adapter must stop generating events for this selector. However, the adapter must continue to process any requests for events that were generated prior to the invocation of the quiesce() function.

The IAAdapter class provides a default implementation of this function that call the adapter's stop() function.

Parameters:

selector
The selector for which the adapter is to stop generating events.

Return (IABool/boolean):

The adapter's quiesce() function should return the following success or failure indication:

1 (true)
Quiesce of the adapter was successful.

0 (false)
Errors occurred during quiesce of the adapter.

Notes

  1. A call to an adapter's quiesce() function for a particular selector is ordinarily matched with a subsequent call to either the adapter's reset() function, or its restart() function for the same selector. The quiesce() call will be followed by a restart() call when the quiesce() is due to a conduct set load or unload operation. The quiesce() call will be followed by a reset() call when the quiesce() is due to an agent reset operation.

Event-Related Callback Functions

eventComplete
   C++:  virtual void eventComplete(const IAEventHeader &hdr)

   Java: void eventComplete(IAEventHeader hdr)

Informs the adapter of event completion.

The Agent Building Environment Developer's Toolkit framework calls an adapter's eventComplete() function at the completion of the processing of an agent event.

When the eventComplete() call is made, all sensor and effector calls that were triggered during processing of the event have been completed. However, asynchronous actions initiated by some adapter's effector procedures may still be outstanding.

For all events other than the AGENT:CONFIG event, the eventComplete() function is called on the Adapter that initiated processing of the event via notify(), and also on all Adapters on which answerQuery(), performAction() or testCondition() calls were made during processing of the event. The eventComplete() function is called at only once for each such Adapter.

In the case of the AGENT:CONFIG event, the eventComplete() function is called once on all Adapters in the agent configuration, regardless of whether they that participated in the procesisng of the AGENT:CONFIG event or not.

Parameters:

hdr
A copy of the completed event header (IAEventHeader) identifying the event for which completion is being signaled.

Return:

Nothing.

Notes:

  1. An adapter can use the eventComplete() call as an indication that it is appropriate to discard event-related information that the adapter is retaining.

  2. The eventComplete() function is always called on all adapters at the completion of the AGENT:CONFIG event so that an adapter can rely on this call as an indication that this phase of agent configuration has ended.

testCondition
   C++:  virtual IABool testCondition(IAProcToken token,
                                      const IAEventHeader &hdr,
                                      const char *atom)

   Java: boolean testCondition(IAProcToken token,
                               IAEventHeader hdr,
                               String atom)

Runs a boolean sensor procedure.

The Agent Building Environment Developer's Toolkit framework calls an adapter's testCondition() function when an engine wishes to employ a boolean sensor to ascertain the truth or falsity of a condition (predicate) relative to a particular set of arguments (terms). If true, the condition results in an additional short-term fact that the engine uses during processing of the event.

The boolean sensor being run (and hence, the condition being tested) is identified by the procedure token token. The parameters for which the condition should be tested are defined by the terms of the atom atom. Because the sensor procedure is a boolean sensor, all of the terms of atom are always bound terms.

The processing required to evaluate the condition, and the use of the atom in performing that evaluation are entirely adapter specific.

Processing of the event identified by hdr is suspended until this call returns.

Parameters:

token
Token identifying the boolean sensor procedure to be run. This token is a copy of the token assigned to the procedure on a registerProcedure() call.

hdr
A copy of the (completed) event header (IAEventHeader) identifying the event being processed.

atom
An atom, in the form of a null-terminated KIF string (a String, in Java), the terms of which represent the arguments for the boolean sensor procedure. The terms of the atom can be parsed and analyzed through the use of the IAAtom class.

Return (IABool/boolean):

The adapter's testCondition() function should return the following truth value:

1 (true)
The condition represented by the input atom/fact is true.

0 (false)
The condition represented by the input atom is false.

answerQuery
   C++:  virtual IAFactSet answerQuery(IAProcToken token,
                                       const IAEventHeader &hdr,
                                       const char *atom)

   Java: IAFactSet answerQuery(IAProcToken token,
                               IAEventHeader hdr,
                               String atom)

Runs a sensor procedure.

The Agent Building Environment Developer's Toolkit framework calls an adapter's answerQuery() function when an engine wishes to employ a sensor to obtain additional information for event processing. The sensor call represents a query relative to a particular set of arguments (terms). The results of the query are expressed as a set of additional short-term facts the engine uses during processing of the event.

The sensor being run (and hence, the query being evaluated) is identified by the procedure token token. The parameters for which the query should be evaluated are defined by the terms of the atom atom.

The adapter's sensor procedure should evaluate the query using the bound terms of atom as inputs to the query. It should return the results of the query as a fact set (IAFactSet) in which each fact has the same bound terms as atom, and has all unbound terms replaced by a corresponding (same type) bound term for which the query is true. Each fact in the set should provide a different combination of values for the unbound terms. That is, each fact provides one of the set of answers to the query. The sensor should return an empty fact set if there are no values of the unbound terms for which the query is true.

The processing required to evaluate the query, and the use of the atom in performing that evaluation are entirely adapter specific.

Parameters:

token
Token identifying the boolean sensor procedure to be run. This token is a copy of the token assigned to the procedure on a registerProcedure() call.

hdr
A copy of the (completed) event header (IAEventHeader) idendifying the event being processed.

atom
An atom, in the form of a null-terminated KIF string (a String, in Java), the terms of which represent the arguments for the boolean sensor procedure. The terms of the atom can be parsed and analyzed through the use of the IAAtom class.

Return:

A fact set (IAFactSet) containing the results of the sensor procedure, as described above.

performAction
   C++:  virtual void performAction(IAProcToken token,
                                    const IAEventHeader &hdr,
                                    const char *atom)

   Java: void performAction(IAProcToken token,
                            IAEventHeader hdr,
                            String atom)

Runs an effector procedure.

The Agent Building Environment Developer's Toolkit framework calls an adapter's performAction() function when an engine wishes to perform an action that is deemed appropriate as a result of event processing.

The effector being run (and hence, the action being performed) is identified by the procedure token token. The parameters for which the action should be performed are defined by the terms of the atom atom.

The processing required to perform the action, and the use of the atom in performing that action are entirely adapter specific.

Logically, the requested action is performed asynchronously to the Engine's continued processing of the event. Because of this asynchronous nature, this function has been defined to return void. However, to allow efficient processing of short-running actions (by avoiding unnecessary thread creations), the Engine may be suspended until this call returns (because the call is made on the Engine's processing thread). The Adapter should execute the action on the invoking thread only if it can be completed quickly. If not, the Adapter should defer the execution of the action to another thread so that a prompt return from this call can be made.

Parameters:

token
Token identifying the boolean sensor procedure to be run. This token is a copy of the token assigned to the procedure on a registerProcedure() call.

hdr
A copy of the (completed) event header (IAEventHeader) identifying the event being processed.

atom
An atom, in the form of a null-terminated KIF string (a String, in Java), the terms of which represent the arguments for the boolean sensor procedure. The terms of the atom can be parsed and analyzed through the use of the IAAtom class.

Return:

Nothing.

Factory Functions

newAdapter
   C++: extern "C" IAEXPORT1 IAAdapter * IAEXPORT2 IACLINK
                      newAdapter(const char *domain, void *parm);

   Java: public static IAAdapter newAdapter(String domain,
                       String parm)  throws IAAdapterException

The IAAgent object calls the newAdapter() factory function to create an object of your adapter class.

Parameters:

domain
The application area that the adapter represents to the agent. This should be the domain that will be used on subsequent registerProcedure() and notify() calls.

parms
These are any start-up parameters that your adapter requires.

Return (IAAdapter */IAAdapter):
The adapter's newAdapter() function should return an object of the adapter's class.

Notes

  1. The newAdapter() function is a special one. For C++ adapters it is written as a regular C function rather than a method on the adapter class. In Java it is written as a static member function.

Class IAAtom

The IAAtom class is used to construct atoms and extract terms from atoms. Facts are atoms that contain all bound terms, so this class also supports facts. Atoms are used in communicating information between adapters and engines.

To create an atom, first a default atom is constructed. SetKIF could be then used to initialize the whole atom with a KIF string. Examples of KIF facts are:

( Subject "My new PC" )
    ( MotherOf "Bill" "Lorraine" )
    ( ChancesOfRain (real .4))
    ( UnluckyFridays (integer 13))

The first string in a KIF fact is the predicate name. A predicate name is a symbol. A symbol must begin with an alphabetic character and contain only alphanumeric characters. The subsequent tokens in a KIF fact are the terms. Terms can be integers, real numbers, strings or symbols. Instead of setKIF, setPredicate along with addTerm could be used to incrementally initialize the atom.

Note: When an integer or real number is used in an atom, the functional form of specifying the integer or real number must be used as follows:

(integer 13)

(real -3.91)

The shorter form (13, -3.91) is not supported at this time by the by the IAAtom class.

Header File

#include <iatk/atom.h>

This header file is automatically included when iatk/adapter.h is included.

Constructors

IAAtom
   C++:  IAAtom()

   Java:  IAAtom()

Creates a new atom object.

Parameters:

None.

IAAtom
   C++:  IAAtom(const IAAtom &from)

Creates a new copy of an existing atom object.

Parameters:

from
an atom object

Member Functions

~IAAtom
   C++:  void ~IAAtom()

This member function is the destructor for the IAAtom class.

== (operator overload)
   C++:  IABool operator ==(const IAAtom &rhs) const

This is the equality operator overload.

Parameters:

rhs
an atom object

Returns:

true(1) if the facts contained within the atom objects are identical, false(0) if the facts contained within the atom objects are different.

!= (operator overload)
   C++:  IABool operator !=(const IAAtom &rhs) const

This is the inequality operator overload.

Parameters:

rhs
an atom object

Returns:

true(1) if the facts contained within the atom objects are different, false(0) if the facts contained within the atom objects are identical.

operator <
   C++:  IABool operator <(const IAAtom &rhs) const

This is the less than operator overload.

Parameters:

rhs
an atom object

Returns:

true(1) if the fact contained within the left-hand side atom is less (alphabetic ordering) than the fact contained within the right-hand side atom.

(conversion) operator const char *()
   C++:  operator const char *() const

   Java:  String toString()

This is a conversion operator, converting the atom object into a character string.

Parameters:

None

Returns:

A character string containing the KIF atom.

setPredicate
   C++:  void setPredicate(const char *predicate) throw(IAError);

   Java:  void setPredicate(String predicate) throws IAError;

This member function sets the predicate in the KIF atom. If the predicate was previously set in the KIF atom, the old value is discarded.

Parameters:

predicate
a character string containing a valid KIF predicate

Returns:

None.

Exceptions

An IAError is thrown if predicate is not a valid predicate.

setKIF
   C++:  void setKIF(const char * KIFString) throw(IAError);

   Java:  void setKIF(String KIFString) throws IAError;

This member function resets the KIF string in the atom. Since the predicate and terms are part of KIF string, they will also be reset.

Parameters:

KIFString
a string in KIF format

Returns:

None.

Exceptions

An IAError is thrown if KIFString is not a valid KIF string.

setTerms
   C++:  void setTerms(const char * terms) throw(IAError);

   Java:  void setTerms(String terms) throws IAError;

This member function sets the terms in the KIF atom. Any terms that are in the KIF atom when this member function is invoked are deleted.

Parameters:

terms
a blank delimited character string containing the terms for the KIF atom.

Returns:

None.

Exceptions

An IAError is thrown if terms are not valid KIF terms.

replaceSymbolLogicalVariable
   C++:  void replaceSymbolLogicalVariable(int position,
                                      const char * term) throw(IAError);

   Java:  void replaceSymbolLogicalVariable(int position,
                                      String term) throws IAError;

This member function replaces the variable at position position with the term supplied in the parameter.

Parameters:

position
the term in the termlist to be replaced.

Note: This member function assumes a origin 1 numbering scheme for positions. The first position is 1, not 0.

term
A valid symbol (see description of a valid symbol at beginning)

Returns:

None.

Exceptions

An IAError is thrown if position is invalid, the term at position is not a symbol logical variable, or term is not a valid symbol.

replaceLogicalVariable
   C++:  void replaceLogicalVariable(int position,int term) throw(IAError);

   Java:  void replaceLogicalVariable(int position,int term) throws IAError;

This member function replaces the integer variable at position position with the term supplied in the parameter.

Parameters:

position
the term in the termlist to be replaced.

Note: This member function assumes an origin 1 numbering scheme for positions. The first position is 1, not 0.

term
an integer value

Returns:

None.

Exceptions

An IAError is thrown if position is invalid or the term at position is not an integer logical variable.

replaceLogicalVariable
   C++:  void replaceLogicalVariable(int position, double term) throw(IAError);

   Java:  void replaceLogicalVariable(int position, double term) throws IAError;

This member function replaces the real number variable at position position with the term supplied in the parameter.

Parameters:

position
the term in the termlist to be replaced.

Note: This member function assumes an origin 1 numbering scheme for positions. The first position is 1, not 0.

term
a real number value expressed as a double.

Returns:

None.

Exceptions

An IAError is thrown if position is invalid or the term at position is not a real number logical variable.

replaceLogicalVariable
   C++:  void replaceLogicalVariable(int position,const char * term) throw(IAError);

   Java:  void replaceLogicalVariable(int position,String term) throws IAError;

This member function replaces the string variable at position position with the term supplied in the parameter.

Parameters:

position
the term in the termlist to be replaced.

Note: This member function assumes an origin 1 numbering scheme for positions. The first position is 1, not 0.

term
a string value

Returns:

None.

Exceptions

An IAError is thrown if position is invalid or the term at position is not a string logical variable.

getKif
   C++:  const char * getKif() const

   Java:  String getKif()

This member function returns a character string containing the KIF atom.

Parameters:

None.

Returns:

A character string containing the KIF string from the atom.

addTerm
   C++:  void addTerm(int integerValue);

   Java:  void addTerm(int integerValue);

This member function adds an integer term to the end of the existing term list.

Parameters:

integerValue
the integer value to add to the termlist.

Returns:

None.

addTerm
   C++:  void addTerm(double realnumValue);

   Java:  void addTerm(double realnumValue);

This member function adds a real number term to the end of the existing term list.

Parameters:

realnumValue
the real number value to add to the termlist.

Returns:

None.

addTerm
   C++:  void addTerm(const char * stringValue);

   Java:  void addTerm(String stringValue);

This member function adds a string term to the end of the existing term list.

Parameters:

stringValue
the string value to add to the termlist.

Returns:

None.

addSymbolTerm
   C++:  void addSymbolTerm(const char * symbolValue) throw(IAError);

   Java:  void addSymbolTerm(String symbolValue) throws IAError;

This member function adds a symbol term to the end of the existing term list.

Parameters:

symbolValue
a character string containing a valid KIF symbol.

Returns:

None.

Exceptions

An IAError is thrown if symbolValue is not a valid symbol.

addLogicalVariable
   C++:  void addLogicalVariable(const char * type) throw(IAError);

   Java:  void addLogicalVariable(String type) throws IAError;

This member function adds a logical variable to the end of the existing term list.

Parameters:

type
the type of the logical variable to add. Valid types are(case insensitive): String, Integer, Real, Symbol .

Returns:

None.

Exceptions

An IAError is thrown if type is not a valid term type.

getNumberOfTerms
   C++:  int getNumberOfTerms() const

   Java:  int getNumberOfTerms()

This member function returns the number of terms in the termlist.

Parameters:

None.

Returns:

int - the number of terms in the term list.

getTermType
   C++:  const char * getTermType(int position) throw(IAError);

   Java:  String getTermType(int position) throws IAError;

This member function returns the type of the term in the specified position of the termlist.

Parameters:

position
an integer that specifies the position of the desired term.

Returns:

A character string containing the type of the desired term. Valid types are: String, Integer, Real, Symbol, StringLvar, IntegerLvar, RealLvar, and SymbolLvar .

Exceptions

An IAError is thrown if position is invalid.

isFact
   C++:  IABool isFact() const

   Java:  boolean isFact()

This member function checks to see if the KIF string contained by the object is a fact. A KIF fact does not contain any variables.

Parameters:

None.

Returns:

true(1) if the KIF string is a fact, false(0) if the KIF string contains one or more variables.

isLogicalVariable
   C++:  IABool isLogicalVariable(int position) throw(IAError);

   Java: boolean isLogicalVariable(int position) throws IAError;

This member function tests to see if the term at the specified position is a logical variable of any type.

Parameters:

position
an integer specifying the term in the termlist.

Returns:

true(1) if the type of the term at position position is a logical variable of any type. False(0) if the term at the specified position is not a logical variable or does not exist in the termlist.

Exceptions

An IAError is thrown if position is invalid.

isLogicalVariable
   C++:  IABool isLogicalVariable(int position, const char * type) throw(IAError);

   Java: boolean isLogicalVariable(int position, String type) throws IAError;

This member function tests to see if the term at the specified position is a logical variable of the specified type.

Parameters:

position
an integer specifying the term in the termlist.

type
the type of the term. Valid types are: String, Integer, Real, Symbol .

Returns:

true(1) if the type of the term at position position matches the specified type. False(0) if the types do not match or the specified position does not exist in the termlist.

Exceptions

An IAError is thrown if position is invalid.

getSymbolTerm
   C++:  const char * getSymbolTerm(int position) throw(IAError);

   Java:  String getSymbolTerm(int position) throws IAError;

This member function returns the symbol at the specified position in the termlist.

Parameters:

position
the position of the symbol in the termlist.

Returns:

the symbol at the specified position.

Exceptions

An IAError is thrown if position is invalid or the term at position is not a symbol.

getStringTerm
   C++:  const char * getStringTerm(int position) throw(IAError);

   Java:  String getStringTerm(int position) throws IAError;

This member function returns the string at the specified position in the termlist.

Parameters:

position
the position of the string in the termlist.

Returns:

This member function returns the string at the specified position in the termlist.

Exceptions

An IAError is thrown if position is invalid or the term at position is not a string.

getIntegerTerm
   C++:  int getIntegerTerm(int position) throw(IAError);

   Java:  int getIntegerTerm(int position) throws IAError;

This member function returns the integer at the specified position in the termlist.

Parameters:

position
the position of the integer in the termlist.

Returns:

int - the integer at the specified term in the termlist.

Exceptions

An IAError is thrown if position is invalid or the term at position is not an integer.

getRealTerm
   C++:  double getRealTerm(int position) throw(IAError);

   Java:  double getRealTerm(int position) throws IAError;

This member function returns the real number (double) at the specified position in the termlist.

Parameters:

position
the position of the real number in the termlist.

Returns:

double - the real number at the specified term in the termlist.

Exceptions

An IAError is thrown if position is invalid or the term at position is not a real number.

getPredicate
   C++:  const char * getPredicate() const

   Java:  String getPredicate()

This member function returns the predicate from the atom.

Parameters:

None.

Returns:

a character string containing the predicate from the atom.

dbgInfo
   C++:  void dbgInfo(ostream &o) const;

   Java:  void dbgInfo(OutputStream o)
   Java:  void dbgInfo(Writer o);

This function will stream out a debugging representation of the KIF string held by the atom object.

Parameters:

o
an ostream, OutputStream, or Writer object

Returns:

None

Class IAError

The IAError class contains status information.

Header File

#include <iatk/iaerrors.h>

This header file is automatically included when iatk/adapter.h is included.

Constructors

IAError(default constructor)
   C++:  IAError();

   Java: IAError();

Constructs an IAError object that contains no error (successful status).

Parameters:

None.

Returns:

Nothing.

IAError
   C++:  IAError(int msgnumber);

   Java: IAError(int msgnumber);

Constructs an IAError object that contains the input error number.

Parameters:

msgnumber
The error number which represents the error condition that occurred.

IAError
   C++:  IAError(int msgnumber, const char *msgpattern, ...);

Constructs an IAError object that contains the input error number and it's associated message text, with message substitutions as needed.

Parameters:

msgnumber
The error number which represents the error condition that occurred.

msgpattern
A string containing the message text.

The message text can be a simple string ("Process failed") or it can be a format-string which contains escape sequences and format specifications ("Process %s failed"). See ANSI C library function printf for valid format specifiers and escape sequences.

...
A comma-separated list of values to use as substitutions for the format specifiers that are contained in the message text string. For example:
  IAError status(20, "Process %s failed with rc = %d.", "MyProcess", 4);

This parameter is only required when the message string contains format specifiers, and one value is required for each specifier. See ANSI C library function printf for more information.

IAError
   Java:  IAError(int msgnumber, String msgpattern);

Constructs an IAError object that contains the input error number and it's associated message text.

Parameters:

msgnumber
The error number which represents the error condition that occurred.

msgpattern
A string containing the message text.

The message is a simple string ("Process failed").

IAError
   Java:  IAError(int msgnumber, String msgpattern, String sub1);

Constructs an IAError object that contains the input error number and it's associated message text, with 1 to 4 string substitutions in the message text.

Parameters:

msgnumber
The error number which represents the error condition that occurred.

msgpattern
A string containing the message text and from 1 to 4 "string" format specifiers (%s).

sub1
A comma-separated list of 1 to 4 strings to be used as substitutions for the string specifiers in the message text. There should be one string for each string specifier. For Example:
 IAError status(20, "Process %s failed.", "MyProcess");

 IAError status(20, "%s: Process %s failed.", "MyObject", "MyProcess");

 IAError status(20, "%s: Process %s failed with rc= %s.", "MyObject",
                "MyProcess", "4");

 IAError status(20, "%s: Process %s failed with rc= %s, message =%s.",
                "MyObject", "MyProcess", "4", "Invalid option");

Copy constructor
   C++:  IAError(const IAError ©);

Constructs an IAError which is a copy of an existing IAError.

Parameters:

copy
an existing IAError object.

Member Functions

Destructor
   C++: ~IAError()

This member function deletes an IAError object.

Parameters:

None.

Returns:

Nothing.

=(operator overload)
   C++:  IAError & operator=(const IAError &from)

This member function is the assignment operator.

Parameters:

from
The IAError object from which the assignment is made.

msgnumber
   C++:  int msgnumber() const;

   Java: int msgnumber();

Accesses the message number that represents this error.

Parameters:

None.

Returns:

Nothing.

errormsg
   C++:  const char *errormsg() const;

   Java: String errormsg();

Accesses the message text associated with this error.

Parameters:

None.

Returns:

Nothing.

isOk
   C++:  IABool isOk(void);

   Java: boolean isOk(void);

Determines if the object represents successful completion (no error).

Parameters:

None.

Returns:

1 (true)
This IAError represents successful completion. There is no error contained in the object.

0 (false)
This IAError contains an error condition.

!(operator override)
   C++:  IABool operator !() const;

Determines if the object represents an error.

Parameters:

None.

Returns:

1 (true)
This IAError contains an error condition.

0 (false)
This IAError represents successful completion. There is no error contained in the object.

not
   Java:  boolean not();

Determines if the object represents an error.

Parameters:

None.

Returns:

1 (true)
This IAError contains an error condition.

0 (false)
This IAError represents successful completion. There is no error contained in the object.

set
   C++: void set(int msgnumber);

   Java: void set(int msgnumber);

Sets or changes the error represented by this object to a new error, which is represented by the error number provided.

Parameters:

msgnumber
The error number which represents the error condition that occurred.

set
   C++:  void set(int msgnumber, const char *msgpattern, ...);

Sets or changes the error represented by this object to a new error, which is represented by the error number and message provided.

Parameters:

msgnumber
The error number which represents the error condition that occurred.

msgpattern
A string containing the message text.

The message text can be a simple string ("Process failed") or it can be a format-string which contains escape sequences and format specifications ("Process %s failed"). See ANSI C library function printf for valid format specifiers and escape sequences.

...
A comma-separated list of values to use as substitutions for the format specifiers that are contained in the message text string. For example:
  IAError status(20, "Process %s failed with rc = %d.", "MyProcess", 4);

This parameter is only required when the message string contains format specifiers, and one value is required for each specifier. See ANSI C library function printf for more information.

set
   Java:  set(int msgnumber, String msgpattern);

Sets or changes the error represented by this object to a new error, which is represented by the error number and message provided.

Parameters:

msgnumber
The error number which represents the error condition that occurred.

msgpattern
A string containing the message text.

The message is a simple string ("Process failed").

set
   Java:  set(int msgnumber, String msgpattern, String sub1);

Sets or changes the error represented by this object to a new error, which is represented by the error number and message provided, with 1 to 4 string substitutions in the message.

Parameters:

msgnumber
The error number which represents the error condition that occurred.

msgpattern
A string containing the message text and from 1 to 4 "string" format specifiers (%s).

sub1
A comma-separated list of 1 to 4 strings to be used as substitutions for the string specifiers in the message text. There should be one string for each string specifier. For example:
 IAError status(20, "Process %s failed.", "MyProcess");

 IAError status(20, "%s: Process %s failed.", "MyObject", "MyProcess");

 IAError status(20, "%s: Process %s failed with rc= %s.", "MyObject",
                "MyProcess", "4");

 IAError status(20, "%s: Process %s failed with rc= %s, message =%s.",
                "MyObject", "MyProcess", "4", "Invalid option");

dbgInfo
   C++:  void dbgInfo(ostream &o) const;

   Java: void dbgInfo(OutputStream o);
   Java: void dbgInfo(Writer o);

This function will stream out a debugging representation of the error held by the IAError object.

Parameters:

o
an ostream object (OutputStream or Writer object in Java)

Returns:

Nothing.

Class IAEventHeader

An IAEventHeader object contains standard header data that describes a particular event being processed by the agent. This header is created by the Adapter that calls IAAdapter::notify() to initiate event processing. A copy of the header is provided on calls made to Adapters (getSensorSet(), performAction(), eventComplete(), etc. methods) during event processing.

Each event processed by the agent is identified by an event id in the form of an IAUniqueId. This event id is contained within the IAEventHeader and is generated automatically by the default constructor for this class. Adapters may find it convenient to store and retrieve event-related data based on the event's id; the event id contained with an IAEventHeader can be accessed using the getId() member function.

In order to guarantee uniqueness of event ids, each instance of an IAEventHeader object is intended to be used in at most one IATriggerEvent passed to IAAdapter::notify(). The notify() method returns an error if it is called with an IATriggerEvent that contains a header previously used on a notify().

Header File

#include <iatk/trigevnt.h> =

This header file is automatically included when iatk/adapter.h is included.

Constructors

IAEventHeader (default constructor)
   C++:  IAEventHeader();

Creates a skeletal IAEventHeader and sets the event id within the event header to a unique value.

The IAEventHeader created with this default constructor is not valid for use (isValid returns 0). Use the setType() member function to create valid IAEventHeaders.

The default constructor is provided primarily to make it convenient to define temporary IAEventHeader objects that hold copies of valid event headers.

Parameters:

None

Copy constructor
   C++:  IAEventHeader(const IAEventHeader &from);

This member function is the copy constructor.

Parameters:

from
The IAEventHeader object from which the copy is made.

Member Functions

Destructor
   C++:  ~IAEventHeader();

This member function is the destructor.

Parameters:

None.

Returns:

Nothing.

=(operator overload)
   C++:  IAEventHeader & operator=(const IAEventHeader &rhs);

This member function is the assignment operator.

Parameters:

rhs
The IAEventHeader object from which the assignment is made.

Returns:

A reference to *this.

getId
   C++:  const IAUniqueId & getId() const;

   Java: IAUniqueId getId()

Accesses the event id (IAUniqueId) within this event header.

Parameters:

None.

Returns:

A reference to the event id for this event header.

getDomain
   C++:  const char * getDomain() const;

   Java: String getDomain()

Returns the event domain name from this event header.

Parameters:

None

Returns:

Pointer to the null-terminated domain name string (in Java, a string) for this event header if this event header has been completed by IAAdapter::notify(). Returns NULL if this event header has not been completed by IAAdapter::notify().

getSelector
   C++:  const char *getSelector(void) const;

   Java: String getSelector(void);

Accesses the selector token within this event header.

Parameters:

None.

Returns:

A null-terminated string containing the selector from the event header. Returns a null string "" when called for an event header for which the setSelector function has not been called.

getType
   C++:  const char * getType() const;

   Java: String getType()

Returns the event type from this event header.

Parameters:

None.

Returns:

Pointer to the null-terminated event type string (in Java, a String) for this event header.

eventNumber
   C++:  long eventNumber() const;

   Java: int eventNumber();

Returns the event number from this event header. Event numbers are sequential in order of event occurrence and are greater than 0.

Parameters:

None.

Returns:

Integer representing the event number.

getTime
   C++:  time_t getTime() const;

   Java:  Date getTime()

Returns the time at which event processing was initiated for the event represented by this event header.

Parameters:

None

Returns:

Returns the time, in the form of the C library time() call for width=60 scale=auto.C++ (a Date object for Java), at which event processing was initiated for this event. If this header is not for an event initiated by IAAdapter::notify(), zero is returned.

setType
   C++:  void setType(const char *type) throw(IAError);

   Java: void setType(String type) throws IAError;

The event type field in the event header is set to type.

Parameters:

type
Pointer to a null-terminated string (for Java, a String) containing the domain-specific identifier for the type of event being generated, for example "NewNews".

This type identifier is part of the fully-qualified name for the event. The fully-qualified name for the event is formed by concatenating the domain name of the initiating adapter, a colon (:) and the event-type identifier specified on this constructor. For example, the fully qualified name of a NewNews event generated by an NNTP adapter is "NNTP:NewNews".

Exceptions (IAError):

IA_E_INVALID_EVENT_TYPE
type is null or points to a string that is not a valid type identifier.

Notes:

  1. In addition to the type identifier, and event id, the event header also contains the domain name of the initiating adapter, an event timestamp, and a selector. The domain name and event time stamps are filled in (for the event header within an IATriggerEvent) by IAAdapter::notify(). The selector can be set using the setSelector() function, or it can default to a null string "".

setSelector
   C++:  void setSelector(const char *selector) throw(IAError);

   Java: void setSelector(String selector) throws IAError;

The selector token in the event header is set to selector.

Parameters:

selector
Pointer to a null-terminated string (for Java, a String) containing the selector token for the event.

Exceptions (IAError):

IA_E_INVALID_EVENT_SELECTOR
selector is null.

dbgInfo
   C++:  void dbgInfo(ostream &o) const;

   Java:  void dbgInfo(OutputStream o)
   Java:  void dbgInfo(Writer o);

Prints a debugging representation of this IAEventHeader.

Parameters:

o
The output stream to which the output is written.

Returns:

Nothing.

Class IAFactSet

The IAFactSet class is used to construct fact sets. A fact set is a set of atoms, which may or may not be facts. To help in manipulation of the set of atoms, the fact set object maintains an internal cursor for positioning within the fact set.

Header File

#include <iatk/atom.h>

This header file is automatically included when iatk/adapter.h is included.

Constructors

IAFactSet
   C++:  IAFactSet()

   Java: IAFactSet()

Constructs a fact set object that contains no atoms.

Parameters:

None.

IAFactSet
   C++:  IAFactSet(const IAFactSet &from);

Constructs a fact set which is a copy of an existing fact set. All atoms in the existing fact set are copied to the new fact set.

Parameters:

from
an existing fact set

Member Functions

~IAFactSet
   C++: void ~IAFactSet()

This member function deletes a fact set object.

Parameters:

None.

Returns:

Nothing.

operator =
   C++:  IAFactSet & operator=(const IAFactSet &target)

This operator will copy the source fact set into the target fact set. Any existing atoms in the target fact set are deleted by this operation.

Parameters:

target
a fact set object which is to be copied into the target fact set object.

add
   C++:  void add(const IAAtom &atom) throw(IAError);

   Java: void add(IAAtom atom) throws IAError;

Adds a copy of the atom to the set. The set's internal iteration cursor is invalidated.

Parameters:

atom
a KIF atom

Exceptions:

IAError thrown if the atom is not a fact.

add
   C++:  void add(const char *atom) throw(IAError);

   Java: void add(String atom) throws IAError;

Adds a copy of the atom to the set. The set's internal iteration cursor is invalidated.

Parameters:

atom
a KIF atom

Exceptions:

IAError thrown if the atom is not a valid KIF fact.

clear
   C++:  void clear();

   Java: void clear();

Deletes all facts in the set. The set's iteration cursor is invalidated.

size
   C++:  int size() const;

   Java: int size()

This member function returns the number of atoms in the fact set.

Returns:

int - the number of atoms in the fact set.

first
   C++:  IAAtom * first();

   Java: IAAtom first();

If the list is non-empty, first() sets the internal list cursor to the first element of the list and returns a pointer to that element (in Java, an IAAtom is returned). If the list is empty, first() invalidates the internal cursor and returns NULL.

next
   C++:  IAAtom * next();

   Java: IAAtom  next();

If the internal cursor is valid and list items remain, next() advances the cursor to the next item in the list and returns a pointer to that element (in Java, an IAAtom is returned). If either the internal cursor is not valid, or there are no more items in the list, next() returns NULL.

Returns:

IAAtom * - a pointer to the next item in the list of atoms contained by the fact set object. In Java, an IAAtom object is returned. If the internal cursor is not valid or there are no more items in the list, next() returns NULL.

dbgInfo
   C++:  void dbgInfo(ostream &o) const;

   Java: void dbgInfo(OutputStream o)
   Java: void dbgInfo(Writer o);

This function will stream out a debugging representation of the KIF string held by the FactSet object.

Parameters:

o
an ostream object (OutputStream or Writer object in Java)

Returns:

Nothing.

Class IATriggerEvent

An IATriggerEvent object contains the event data provided to Engines on IAAdapter::notify() calls. It consists of a standard event header (IAEventHeader) that identifies the event, and a set of short term facts that are used as input for the processing of the event.

Each event processed by the agent is identified by an event id in the form of an IAUniqueId. This event id is contained within the IAEventHeader that is part of the IATriggerEvent passed to IAAdapter::notify() and is automatically generated when the IATriggerEvent (and hence IAEventHeader) is constructed. In order to guarantee uniqueness of the event ids, each instance of an IATriggerHeader object is intended to be used in at most one IAAdapter::notify() call. The IAAdapter::notify() method returns an error if it is called with an IATriggerEvent that was previously used on a notify().

Header File

#include <iatk/trigevnt.h>

This header file is automatically included when iatk/adapter.h is included.

Constructors

IATriggerEvent (default constructor)
   C++:
  IATriggerEvent();

Creates a skeletal IATriggerEvent.

The IATriggerEvent created with this default constructor is not valid for use in an IAAdapter::notify() call. Use the setType() member function to create valid IATriggerEvents.

The default constructor is provided primarily to make it convenient to define temporary IATriggerEvent objects that hold copies of valid trigger events.

Copy constructor
  C++:  IATriggerEvent(const IATriggerEvent &from);

This member function is the copy constructor.

Parameters:

from
The IATriggerEvent object from which the copy is made.

Member Functions

Destructor
  C++:  ~IATriggerEvent();

This member function is the destructor.

Parameters:

None.

Returns:

Nothing.

=(operator overload)
  C++:  IATriggerEvent& operator =(const IATriggerEvent&rhs);

This member function is the assignment operator.

Parameters:

rhs
The IATriggerEvent object from which the assignment is made.

Returns:

A reference to *this.

getHeader
  C++:  IAEventHeader & getHeader() const;

  Java: IAEventHeader getHeader()

Accesses the event header (IAEventHeader) within this trigger event.

Parameters:

None.

Returns:

A reference to the event header for this trigger event.

getFacts
  C++:  IAFactSet & getFacts() const;

  Java: IAFactSet  getFacts()

Accesses the fact set (IAFactSet) within this trigger event.

Parameters:

None.

Returns:

A reference to the fact set for this trigger event.

isValid
  C++:  IABool isValid() const;

  Java: boolean isValid()

Determines if this IATriggerEvent is valid for use in an IAAdapter::notify() call.

Parameters:

None

Returns:

1 (true)
This IATriggerEvent is a valid trigger event containing a valid event header.

0 (false)
This IATriggerEvent is not valid.

setFactSet
  C++:  void setFactSet(const IAFactSet &fs);

  Java:  void setFactSet(IAFactSet fs);

Sets the fact set into the trigger event.

Parameters:

fs
An IAFactSet object containing the set of short-term facts for the event. These facts are used by the agent's Engines as event-specific inputs for the processing of this event.

Facts can be added by obtaining a reference to the trigger event's fact set using getFactSet() and then using IAFactSet::add().

setType
  C++:  void setType(const char *eventType) throw(IAError);

  Java:  void setType(String eventType) throws IAError;

Sets the event type.

Parameters:

eventType
Pointer to a null-terminated string (for Java, a String) containing the domain-specific identifier for the type of event being generated, e.g. "NewNews". This argument is used in constructing the event header contained within the IATriggerEvent. See the description for the IAEventHeader class for a description of the use of the event type argument.

If no fact set has been established for the event, then facts can be added by creating a fact set and using setFactSet(). If a fact set has already been established for this event, then new facts can be added by obtaining a reference to the trigger event's fact set using getFactSet() and then using IAFactSet::add().

When no fact set is established, the trigger event is given an empty fact set.

Exceptions (IAError):

IA_E_INVALID_EVENT_TYPE
eventType is null or points to a string that is not a valid type identifier.

dbgInfo
  C++:  void dbgInfo(ostream &o) const;

  Java: void dbgInfo(OutputStream o)
  Java: void dbgInfo(Writer o);

Prints a debugging representation of this IATriggerEvent.

Parameters:

o
The output stream to which the output is written.

Returns:

Nothing.

Class IAUniqueId

An IAUniqueId object is a "serial number" that can be used to distinguish one Agent Building Environment Developer's Toolkit object (trigger event, adapter, etc.) from another within the scope of a particular agent instance (start to stop).

Note: Because an IAUniqueId is guaranteed to be unique only within an agent instance, IAUniqueIds are not appropriate for use as persistent identifiers of objects or data. Future implementations of IAUniqueId may provide a greater scope of uniqueness.

Header File

#include <iatk/uniqueid.h>

This header file is automatically included when iatk/adapter.h is included.

Constructors

IAUniqueId
   C++:  IAUniqueId();

   Java: IAUniqueId();

Creates a new IAUniqueId.

The IAUniqueId generated with this default constructor is not valid for use (isValid() returns 0). The generate() function must be called to make the IAUniqueId valid.

Parameters:

None

Copy constructor
   C++:  IAUniqueId(const IAUniqueId &from);

This member function is the copy constructor.

Parameters:

from
The IAUniqueId object from which the copy is made. The destination (this) IAUniqueId is set to have the same identification value as from.

Member Functions

~IAUniqueId
   C++:  ~IAUniqueId()

This member function is the destructor for the object.

Parameters:

None.

Returns:

Nothing.

= (operator overload)
   C++:  IAUniqueId & operator=(const IAUniqueId &rhs);

This member function is the assignment operator.

Parameters:

rhs
The IAUniqueId object from which the assignment is made. The destination (this) IAUniqueId is set to have the same identification value as rhs.

Returns:

A reference to *this.

== (operator overload)
   C++:  IABool operator==(const IAUniqueId &rhs) const;

   Java: boolean equals(IAUniqueId rhs)

Compares this IAUniqueId with another to determine if they represent the same identifying value.

Parameters:

rhs
The IAUniqueId object to which this IAUniqueId is compared.

Returns:

1 (true)
The two IAUniqueIds have the same identification values.

0 (false)
The two IAUniqueIds represent different identifying values, or one or both of this IAUniqueId and rhs are not valid.

!= (operator overload)
   C++:  IABool operator!=(const IAUniqueId &rhs) const;

   Java: boolean notEqual(IAUniqueId rhs)

Compares this IAUniqueId with another to determine if they have different identifying values.

Parameters:

rhs
The IAUniqueId object to which this IAUniqueId is compared.

Returns:

1 (true)
The two IAUniqueId represents different identifying values, or one or both of this IAUniqueId and rhs are not valid.

0 (false)
This two IAUniqueIds represent the same identifying value.

< (operator overload)
   C++:  IABool operator<(const IAUniqueId &rhs) const;

   Java: boolean lessThan(IAUniqueId rhs)

Determines an ordering between two IAUniqueIds.

The primary intent of this function is to enable IAUniqueIds to be used as element keys of collection classes that require a key-ordering relation. This function defines an arbitrary ordering that does not necessarily correspond to an ordering according to time of generation.

Parameters:

rhs
The IAUniqueId object to which this IAUniqueId is compared.

Returns:

1 (true)
This IAUniqueId is considered to be less than rhs.

0 (false)
This IAUniqueId is considered to be not less than rhs.

hashCode
   C++:  long hashCode() const

   Java: int hashCode()

Returns a positive integer hash code for this IAUniqueId.

Parameters:

None

Returns:

A positive integer.

generate
   C++:  void generate()

   Java: void generate()

Sets this IAUniqueId to a unique value that will not be generated again in this agent instance.

Parameters:

None

Returns:

Nothing.

asString
   C++:  const char * asString() const;

   Java: String asString()

Returns string representation of this IAUniqueId.

Parameters:

None

Returns:

A pointer to the null-terminated string (for Java, a String) representation of this IAUniqueId.

isValid
   C++:  IABool isValid() const;

   Java: boolean isValid()

Determines if this IAUniqueId represents a validly generated unique identifying value (as generated by generate()). A non-zero value is returned if this IAUniqueId contains a valid unique ID as generated by IAUniqueId::generate, otherwise returns zero.

Parameters:

None

Returns:

1 (true)
This IAUniqueId represents a validly-generated identifying value.

0 (false)
This IAUniqueId does not represent a validly-generated identifying value.

dbgInfo
   C++:  void dbgInfo(ostream &o) const;

   Java: void dbgInfo(OutputStream o)
   Java: void dbgInfo(Writer o);

Prints a debugging representation of this IAUniqueid.

Parameters:

o
The output stream to which the output is written.

Returns:

Nothing.


[ Top of Page | Previous Page | Next Page | Table of Contents ]