apama.iaf¶

Contains PySys extensions for starting and interacting with IAF processes.

IAFHelper¶

class apama.iaf.IAFHelper(parent, port=None, host=None, name='iaf', **startArgs)[source]¶

Bases: apama.common.ApamaServerProcess

Helper class for the Software AG Apama Integration Adapter Framework (IAF).

The IAF Helper class has been designed for use as an extension module to the PySys System Test Framework, offering the ability to configure, start and interact with an instance of the IAF. The usage pattern of the class is to create an instance per IAF, and to then make method calls onto the instance to perform operations such as to start the component, request reload of the configuration file, perform management operationes etc. For example:

iaf = IAFHelper(self, config="iaf-config.xml")
iaf.start(logfile="iaf.log")
iaf.client(reload=True)

Process related methods of the class declare a method signature which includes named parameters for the most frequently used options to the method. They also declare the **xargs parameter to allow passing in of additional supported arguments to the process. The additional arguments that are currently supported via **xargs are:

workingDir: The default value for the working directory of a process

state: The default state of the process (pysys.constants.BACKGROUND | pysys.constants.FOREGROUND)

timeout: The default value of the process timeout

stdout: The default value of the process stdout

stderr: The default value of the process stderr

arguments: List of extra arguments to be passed to the process

This means that legitimate calls to the start method include:

iaf.start(logfile="iaf.log")
iaf.start(logfile="iaf.log", stdout="iaf1.out")
iaf.start(state=FOREGROUND, timeout=5*60)

Variables

~.parent – Reference to the PySys pysys.basetest.BaseTest testcase (or pysys.process.user.ProcessUser) instantiating this instance.
~.port (int) – Port used for starting and interaction with the process. If no port parameter is used in the argument list an available port will be dynamically found from the OS and used for starting the process, and performing all operations against it.
~.host (str) – Hostname for interaction with a remote process. The host parameter is only used to perform operations against a remote process started externally to the PySys framework - the class does not support the starting of a remote process.
~.environ (dict(str,str)) – The environment for running the process
~.name (str) – A display name for this process (default is “iaf”), also used for the default stdout/err filenames.

Parameters

~.startArgs – Default values can be provided here for any keyword arguments that are supported by start().

addToClassPath(path)[source]¶: Add the supplied path to the APAMA_IAF_CLASSPATH environment variable for starting this IAF instance.

addToPath(path)[source]¶: Add the supplied path to the PATH (win32) or LD_LIBRARY_PATH (unix) environment variable for starting this IAF instance.

start(configname=None, configdir=None, replace=None, logfile=None, verbosity=None, environ=None, waitForServerUp=None, **xargs)[source]¶

Start the IAF. Note that default values for any of this method’s parameters can be passed to the constructor when this object is instantiated.

Start an IAF using the supplied configuration file. If the configdir argument is not supplied, the location of the configuration file defaults to the testcase input directory. The configuration file can first be tailored to replaced token values within the file with values required at run time using the``replace`` argument. For replace of the form

replace = {"@logs_dir@":"/var/tmp/logs"} 

any tokens in the coniguration file directly matching @logs_dir@ will be replaced with the value “/var/tmp/logs”. Note that multiple token value pairs can be supplied in the replace dictionary.

Parameters

configname (str) – The IAF configuration file or template name
configdir (str) – The directory containing the IAF configuration file or template
logfile (str) – Name of the IAF log file
verbosity (str) – The verbosity level of the IAF logging
environ (dict[str,str]) – Map of environment variables to override.
replace (dict[str,str]) – A dictionary of tokens / values to be replaced in the configuration file
waitForServerUp (bool) – Set to False to disable automatically waiting until the component is ready.
xargs – Optional startProcess keyword arguments, e.g. timeout, ignoreExitStatus, arguments, workingDir

client(reload=False, suspend=False, resume=False, **xargs)[source]¶

Perform client operations against the IAF (reload, suspend, resume).

Runs as a foreground process by default.

Parameters

reload – Request reload of the IAF configuration file
suspend – Request the IAF to suspend event sending
resume – Request the IAF to resume event sending
xargs – Optional startProcess keyword arguments, e.g. timeout, ignoreExitStatus, arguments, workingDir

manage(arguments=[], displayName='manage', **xargs)¶

Execute component_management operations against the process.

Parameters

arguments – The arguments to be passed to component_management
xargs – Optional startProcess keyword arguments, e.g. timeout, ignoreExitStatus, arguments, workingDir

running()¶: Returns True if this has a local process that is running, or False if it has stopped, or was not started by this object.

shutdown(message='Shutdown requested by test', timeout=60, **args)¶

Requests a clean shutdown of the component.

If it was started by this object, also waits for the process to terminate, and silently ignores requests to shutdown if the process was already stopped.

waitForComponentUp(timeout=60, **xargs)¶: Block until the the component declares itself to be ready for processing.

waitForLogGrep(expr, errorExpr=['(ERROR|FATAL|Failed to parse) .*'], ignores=None, mappers=None, **kwargs)¶

Wait until this component’s logfile contains the specified regular expression, such as a message indicating that the test has completed.

For example:

correlator.waitForLogGrep(r'INFO .* Test completed')

This is a wrapper around pysys.basetest.BaseTest.waitForGrep that adds functionality specific to Apama components, such as aborting early (with a clear outcome reason) if an error message is found in the log file or the process dies while waiting (with mappers to convert multi-line stack traces to a self-contained message), and always using the UTF-8 encoding to read the log file.

Any of the standard waitForGrep keywords such as ignores=, timeout= may also be pass in as keyword arguments.

Parameters

expr (str) – The regular expression to search for in the log file. Remember to escape characters such as []()\.
condition (str) – The condition to be met for the number of lines matching the regular expression; by default we wait until there is at least one occurrence.
timeout (int) – The number of seconds to wait for the regular expression before giving up and aborting the test with pysys.constants.TIMEDOUT (unless abortOnError=False in which case execution will continue).
ignores (list[str]) – A list of regular expressions used to identify lines in the file which should be ignored when matching both expr and errorExpr. By default this is taken from the value of the apama.testplugin.ApamaPlugin.defaultLogIgnores.
mappers (List[callable[str]->str]) – A list of filter functions that will be used to pre-process each line of the log. Unless explicitly overridden, mappers for EPL and Java will be used ( apama.testplugin.ApamaPlugin.JoinEPLStackLines and pysys.mappers.JoinLines.JavaStackTrace).

Returns

A list of the matches; see pysys.basetest.BaseTest.waitForGrep for details.

New in version 10.11.0.