/**
* engine_client_cpp.hpp
*
* This is the header file for the Apama Event Manager C++ SDK
*
* $Copyright(c) 2013 Software AG, Darmstadt, Germany and/or its licensors$
*
* $Id$
*/
 
#ifndef ENGINE_CLIENT_CPP_HPP
#define ENGINE_CLIENT_CPP_HPP
 
#include <AP_Types.h>
#include <AP_Platform.h>
#include <iostream>
#include <sstream>
#include <exception>
 
#undef ERROR
 
namespace com {
namespace apama {
 
/**
* An EngineException is thrown by methods in this library if any
* problems are encountered.
*/
class AP_ENGINE_CLIENT_API EngineException : public std::exception {
 
public:
// Constructors
EngineException(const char* message);
EngineException(const EngineException& ce);
EngineException& operator= (const EngineException& ce);
 
// Destructor
virtual ~EngineException() throw();
 
/**
* Retrieve the message enclosed within the exception.
*
* @return C style string with details of the error that
* caused the operation to fail.
*/
virtual const char* what() const throw();
 
/**
* Retrieve the set of warnings associated with the exception
*
* @return A pointer to a NULL terminated list of warnings,
* possibly NULL if there are none. This list is owned by
* the exception object. It should not be deleted.
*/
virtual const char* const* getWarnings() const;
 
protected:
const char* const* m_warnings;
 
private:
char* m_message;
};
 
/** Available logging levels */
typedef enum {
OFF_LEVEL,
FORCE_LEVEL,
CRIT_LEVEL,
FATAL_LEVEL,
ERROR_LEVEL,
WARN_LEVEL,
INFO_LEVEL,
DEBUG_LEVEL,
TRACE_LEVEL
} LogLevel;
 
/**
* Sets the level at which the client library will log information.
*
* @param level The level to log at
*/
AP_ENGINE_CLIENT_API void setLogLevel(LogLevel level);
 
/**
* Sets the file to which the client library should log information.
*
* @param filename The filename to which the library should log. Will log
* to stderr if the filename cannot be opened.
* @param truncate If non-zero the log file will be truncated when it is
* opened. If zero then it will simply be appended to.
* @param utf8 Interpret filename as UTF-8, rather than the local character
* set.
*/
AP_ENGINE_CLIENT_API void setLogFile(const AP_char8* filename, bool truncate,
bool utf8 = false);
 
/**
* Sets the file descriptor to which the client library should log information
*
* @param fd The file descriptor to log to
*/
AP_ENGINE_CLIENT_API void setLogFD(int fd);
 
/**
* Sets the mutex which the client library logger should use. For internal use only.
*
*/
AP_ENGINE_CLIENT_API void setLogMutex(void *mutex);
 
/**
* Re-opens the log file. Also called if SIGHUP is received.
*
*/
AP_ENGINE_CLIENT_API void reOpenLog();
 
/** Convert a string in local encoding to UTF-8, as required by most of the Apama API */
AP_ENGINE_CLIENT_API AP_char8* convertToUTF8(const AP_char8* s);
 
/** Convert a string in UTF-8 to the local encoding, since most of the
Apama API returns UTF-8 */
AP_ENGINE_CLIENT_API AP_char8* convertFromUTF8(const AP_char8* s);
 
namespace event {
 
/**
* An Event object represents an event instance.
*/
class AP_ENGINE_CLIENT_API Event {
 
friend AP_ENGINE_CLIENT_API Event* createEvent(const char* eventString);
friend AP_ENGINE_CLIENT_API void deleteEvent(Event* ev);
 
public:
/**
* Retrieve the event's type and its contents as a string.
*
* @return C style string with the event's textual representation.
* Note that these strings should be encoded in UTF-8.
*/
virtual const char* getText() const = 0;
 
/**
* Retrieve the event's channel. This currently only has meaning for
* events which have been sourced from the correlator, in which case
* it is set to the name of the channel the event was emitted from, or
* "" (the empty string) for the wildcard channel.
*
* @return The channel of the event, encoded in UTF-8.
*/
virtual const char* getChannel() const = 0;
 
/**
* Retrieve the event's timestamp. This timestamp currently only has
* meaning for events which have been sourced from the correlator, in
* which case it is set to the correlator time at which it was created,
* or the value it was set to explicitly by code running within the
* correlator.
*
* @return the timestamp of the event, in floating point seconds since
* the Unix epoch.
*/
virtual double getTime() const = 0;
 
// Stream output operators
inline friend std::ostream& operator << (std::ostream& stream, const Event& obj) {
stream << obj.getText();
return stream;
}
inline friend std::ostream& operator << (std::ostream& stream, const Event* obj) {
stream << obj->getText();
return stream;
}
 
private:
Event(const Event&);
Event& operator= (const Event&);
 
protected:
Event();
virtual ~Event();
};
 
/**
* An EventSupplier represents the resources created by the Engine
* to service a connection to an external sink of events. It
* filters the event output of the Engine by delivering only the
* events emitted on a particular set of channels. An
* EventSupplier passes events to an EventConsumer.
* EventSupplier objects should be freed using the
* com::apama::event::deleteEventSupplier function.
*/
class AP_ENGINE_CLIENT_API EventSupplier {
 
friend AP_ENGINE_CLIENT_API void deleteEventSupplier(EventSupplier* evsup);
 
public:
/**
* Disconnect the EventSupplier from its consumer and
* release its resources.
*
* @exception EngineException
*/
virtual void disconnect() = 0;
 
protected:
EventSupplier();
virtual ~EventSupplier();
 
private:
EventSupplier(const EventSupplier&);
EventSupplier& operator= (const EventSupplier&);
};
 
/**
* An EventConsumer can connect to the Engine through an
* EventSupplier and register to receive events. In order to
* receive events from the Engine, a developer must inherit from
* this class and define its sendEvents method. This method is
* called by the EventSupplier when events are emitted from the
* Engine.
*/
class AP_ENGINE_CLIENT_API EventConsumer {
 
public:
/**
* This method must be defined in inherited classes to
* enable receiving of events. This method is called by an
* EventSupplier.
*
* Note that EventSuppliers are not reentrant so
* calling the disconnect method on the calling
* EventSupplier is not permitted from within the
* sendEvents implementation.
*
* @param events An array of pointers to Event objects.
*/
virtual void sendEvents(const Event* const* events) = 0;
 
protected:
EventConsumer();
virtual ~EventConsumer();
 
private:
EventConsumer(const EventConsumer&);
EventConsumer& operator= (const EventConsumer&);
};
 
class AP_ENGINE_CLIENT_API DisconnectableEventConsumer : public EventConsumer {
 
public:
/**
* Used to inform the consumer that it is not going
* to be sent any more events.
*
* @param A string giving the reason why the consumer
* is being disconnected. May be NULL.
*/
virtual void disconnect(const char* reason) = 0;
protected:
DisconnectableEventConsumer();
virtual ~DisconnectableEventConsumer();
private:
DisconnectableEventConsumer(const DisconnectableEventConsumer&);
DisconnectableEventConsumer& operator= (const DisconnectableEventConsumer&);
};
 
/**
* This function allows creation of an Event object.
*
* @param eventString C style string representing the event
* instance in MonitorScript. Note that this string should
* be encoded in UTF-8.
* @return A reference to an Event object.
*/
AP_ENGINE_CLIENT_API Event* createEvent(const char* eventString);
 
/**
* This function allows deletion of an Event object.
*
* @param ev A reference to an Event object.
*/
AP_ENGINE_CLIENT_API void deleteEvent(Event* ev);
 
/**
* This function allows deletion of an EventSupplier object.
* It also stops the associated EventConsumer from receiving
* events.
*
* @param evsup A reference to an EventSupplier object.
*/
AP_ENGINE_CLIENT_API void deleteEventSupplier(EventSupplier* evsup);
 
} // namespace event
 
namespace engine {
 
/**
* A MonitorScript object encapsulates a MonitorScript code
* fragment, containing package, event and monitor definitions to
* be injected into an Engine.
*/
class AP_ENGINE_CLIENT_API MonitorScript {
 
friend AP_ENGINE_CLIENT_API MonitorScript*
createMonitorScript(const char* monitorString);
friend AP_ENGINE_CLIENT_API void deleteMonitorScript(MonitorScript* mon);
 
public:
/**
* Retrieve the text of a MonitorScript fragment as a string.
*
* @return C style string containing the text of the
* MonitorScript fragment. Note that this string should
* be encoded in UTF-8.
*/
virtual const char* getText() const = 0;
 
// Stream output operators
inline friend std::ostream& operator << (std::ostream& stream,
const MonitorScript& obj) {
stream << obj.getText();
return stream;
}
inline friend std::ostream& operator << (std::ostream& stream,
const MonitorScript* obj) {
stream << obj->getText();
return stream;
}
 
private:
MonitorScript(const MonitorScript&);
MonitorScript& operator= (const MonitorScript&);
 
protected:
MonitorScript();
virtual ~MonitorScript();
};
 
/**
* A class used for the iterating trough all status items
*/
class AP_ENGINE_CLIENT_API StatusIterator {
 
public:
/**
* Checks if there are more status items available
* @return True if there are more status items
* available, false otherwise.
*/
virtual bool hasNext() const = 0;
 
/**
* Sets arguments with the next status item name and value
* @return True if the name and the value were set False
* if there were no more status items, in which case the
* name and the value arguments are not set
*/
virtual bool getNext(const char *&name, const char *&value) const = 0;
 
virtual ~StatusIterator();
private:
StatusIterator(const StatusIterator&);
StatusIterator& operator= (const StatusIterator&);
 
protected:
StatusIterator();
};
 

/**
* EngineStatus represents the operational status of the Engine.
*/
class AP_ENGINE_CLIENT_API EngineStatus {
friend AP_ENGINE_CLIENT_API void deleteStatus(EngineStatus* status);
 
public:
/**
* Get the time in ms that the Engine has been running
* for.
*/
virtual AP_uint64 getUptime() const = 0;
 
/**
* Get the number of monitors defined in the Engine.
*/
virtual AP_uint32 getNumMonitors() const = 0;
 
/**
* Get the number of monitor processes or active
* sub-monitors. If a monitor spawns it creates a new
* process.
*/
virtual AP_uint32 getNumProcesses() const = 0;
 
/**
* Get the number of java applications defined in the Engine.
*/
virtual AP_uint32 getNumJavaApplications() const = 0;
 
/**
* Get the number of active listeners.
*/
virtual AP_uint32 getNumListeners() const = 0;
 
/**
* Get the number of active listeners.
*/
virtual AP_uint32 getNumSubListeners() const = 0;
 
/**
* Get the number of event types defined.
*/
virtual AP_uint32 getNumEventTypes() const = 0;
 
/**
* Get the number of events waiting on the internal input
* queue.
*/
virtual AP_uint32 getNumQueuedFastTrack() const = 0;
 
/**
* Get the number of events waiting on the input queue.
*/
virtual AP_uint32 getNumQueuedInput() const = 0;
 
/**
* Get the number of events received since the Engine
* started (including those discarded because they
* were invalid)..
*/
virtual AP_uint64 getNumReceived() const = 0;
 
/**
* Get the number of events taken off the input queue
* and processed since the Engine started.
*/
virtual AP_uint64 getNumProcessed() const = 0;
 
/**
* Get the number of events received on the internal input
* queue since the Engine started.
*/
virtual AP_uint64 getNumFastTracked() const = 0;
 
/**
* Get the number of event consumers connected to the
* engine.
*/
virtual AP_uint32 getNumConsumers() const = 0;
 
/**
* Get the number of events waiting on the output queue.
*/
virtual AP_uint32 getNumOutEventsQueued() const = 0;
 
/**
* Gets the number of output events which have been
* put onto the output queue. This corresponds to the
* number of MonitorScript emit commands executed.
*/
virtual AP_uint64 getNumOutEventsCreated() const = 0;
 
/**
* This is the number of output events sent out by the
* correlator process. This differs from getNumOutEventsCreated
* since events can be of interest to a varying number of
* consumers.
*/
virtual AP_uint64 getNumOutEventsSent() const = 0;
 
/**
* Get the number of active contexts.
*/
virtual AP_uint32 getNumContexts() const = 0;
 
/**
* Returns an instance of the StatusIterator which
* allows to iterate over all status items
* @return pointer to the StatusIterator. The caller
* is responsible for the deletion of the returned
* instance
*/
virtual StatusIterator *getAllValues() const = 0;
 
/** Stream output operator */
inline friend std::ostream& operator << (std::ostream& stream, const EngineStatus& obj) {
std::ostringstream ost;
ost
<< "Uptime(ms): " << obj.getUptime() << std::endl
<< "Number of contexts: " << obj.getNumContexts() << std::endl
<< "Number of monitors: " << obj.getNumMonitors() << std::endl
<< "Number of sub-monitors: " << obj.getNumProcesses() << std::endl
<< "Number of java applications: " << obj.getNumJavaApplications() << std::endl
<< "Number of listeners: " << obj.getNumListeners() << std::endl
<< "Number of sub-listeners: " << obj.getNumSubListeners() << std::endl
<< "Number of event types: " << obj.getNumEventTypes() << std::endl
<< "Events on input queue: " << obj.getNumQueuedInput() << std::endl
<< "Events received: " << obj.getNumReceived() << std::endl
<< "Events processed: " << obj.getNumProcessed() << std::endl
<< "Events on internal queue: " << obj.getNumQueuedFastTrack() << std::endl
<< "Events routed internally: " << obj.getNumFastTracked() << std::endl
<< "Number of consumers: " << obj.getNumConsumers() << std::endl
<< "Events on output queue: " << obj.getNumOutEventsQueued() << std::endl
<< "Output events created: " << obj.getNumOutEventsCreated() << std::endl
<< "Output events sent: " << obj.getNumOutEventsSent() << std::endl;
stream << ost.str();
return stream;
}
 
/** Stream output operator */
inline friend std::ostream& operator << (std::ostream& stream, const EngineStatus* obj) {
std::ostringstream ost;
ost
<< "Uptime(ms): " << obj->getUptime() << std::endl
<< "Number of contexts: " << obj->getNumContexts() << std::endl
<< "Number of monitors: " << obj->getNumMonitors() << std::endl
<< "Number of sub-monitors: " << obj->getNumProcesses() << std::endl
<< "Number of java applications: " << obj->getNumJavaApplications() << std::endl
<< "Number of listeners: " << obj->getNumListeners() << std::endl
<< "Number of sub-listeners: " << obj->getNumSubListeners() << std::endl
<< "Number of event types: " << obj->getNumEventTypes() << std::endl
<< "Events on input queue: " << obj->getNumQueuedInput() << std::endl
<< "Events received: " << obj->getNumReceived() << std::endl
<< "Events processed: " << obj->getNumProcessed() << std::endl
<< "Events on internal queue: " << obj->getNumQueuedFastTrack() << std::endl
<< "Events routed internally: " << obj->getNumFastTracked() << std::endl
<< "Number of consumers: " << obj->getNumConsumers() << std::endl
<< "Events on output queue: " << obj->getNumOutEventsQueued() << std::endl
<< "Output events created: " << obj->getNumOutEventsCreated() << std::endl
<< "Output events sent: " << obj->getNumOutEventsSent() << std::endl;
stream << ost.str();
return stream;
}
 
protected:
EngineStatus();
virtual ~EngineStatus();
 
private:
EngineStatus(const EngineStatus& old);
EngineStatus& operator= (const EngineStatus& other);
};
 
/**
* Base class for a named object (i.e. event type, container type
* or monitor) returned by an engine inspection. Returned by methods
* of the EngineInfo class. Strings returned by methods of this class
* are valid until the EngineInfo class is deleted.
*/
class AP_ENGINE_CLIENT_API NameInfo {
 
public:
/**
* Name, excluding package, for example "MyEvent".
*/
virtual const char* getName() const = 0;
 
/**
* Package name, for example "com.apamax", or an
* empty string if in the default package.
*/
virtual const char* getPackage() const = 0;
 
/**
* Fully qualified name, for example "com.apamax.MyEvent"
*/
virtual const char* getFullyQualifiedName() const = 0;
 
private:
NameInfo(const NameInfo&);
NameInfo& operator= (const NameInfo&);
 
protected:
NameInfo();
virtual ~NameInfo();
};
 
/**
* Information about a monitor returned by an engine inspection.
* Returned by the getMonitors method of the EngineInfo class.
*/
class AP_ENGINE_CLIENT_API NamedMonitorInfo : public NameInfo {
 
public:
/**
* Gets the number of sub-monitors belonging to this monitor.
*/
virtual unsigned int getNumSubMonitors() const = 0;
 
private:
NamedMonitorInfo(const NamedMonitorInfo&);
NamedMonitorInfo& operator= (const NamedMonitorInfo&);
 
protected:
NamedMonitorInfo();
virtual ~NamedMonitorInfo();
};
 
/**
* Information about a java application returned by an engine inspection.
* Returned by the getJavaApplications method of the EngineInfo class.
*/
class AP_ENGINE_CLIENT_API NamedJavaApplicationInfo : public NameInfo {
 
public:
/**
* Gets the number of listeners belonging to this application.
*/
virtual unsigned int getNumListeners() const = 0;
 
private:
NamedJavaApplicationInfo(const NamedJavaApplicationInfo&);
NamedJavaApplicationInfo& operator= (const NamedJavaApplicationInfo&);
 
protected:
NamedJavaApplicationInfo();
virtual ~NamedJavaApplicationInfo();
};
 
/**
* Information about a context returned by an engine inspection.
* Returned by the getContexts method of the EngineInfo class.
*/
class AP_ENGINE_CLIENT_API NamedContextInfo : public NameInfo {
 
public:
/**
* Gets the number of sub-monitors belonging to this context.
*/
virtual unsigned int getNumSubMonitors() const = 0;
 
/**
* Gets the queue size of this context.
*/
virtual unsigned int getQueueSize() const = 0;
 
private:
NamedContextInfo(const NamedContextInfo&);
NamedContextInfo& operator= (const NamedContextInfo&);
 
protected:
NamedContextInfo();
virtual ~NamedContextInfo();
};
 
/**
* Information about a event type returned by an engine inspection.
* Returned by the getEventTypes method of the EngineInfo class.
*/
class AP_ENGINE_CLIENT_API NamedEventTypeInfo : public NameInfo {
 
public:
/**
* Gets the number of event templates for this event type.
*/
virtual unsigned int getNumEventTemplates() const = 0;
 
private:
NamedEventTypeInfo(const NamedEventTypeInfo&);
NamedEventTypeInfo& operator= (const NamedEventTypeInfo&);
 
protected:
NamedEventTypeInfo();
virtual ~NamedEventTypeInfo();
};
 
/**
* Information about a timer type returned by an engine inspection.
* Returned by the getTimers method of the EngineInfo class.
*/
class AP_ENGINE_CLIENT_API NamedTimerInfo : public NameInfo {
 
public:
/**
* Gets the number of timers for this timer type.
*/
virtual unsigned int getNumTimers() const = 0;
 
private:
NamedTimerInfo(const NamedTimerInfo&);
NamedTimerInfo& operator= (const NamedTimerInfo&);
 
protected:
NamedTimerInfo();
virtual ~NamedTimerInfo();
};
 
/**
* Information about an aggregate function returned by an engine
* inspection.
* Returned by the getAggregates method of the EngineInfo class.
*/
class AP_ENGINE_CLIENT_API NamedAggregateInfo : public NameInfo {
 
private:
NamedAggregateInfo(const NamedAggregateInfo&);
NamedAggregateInfo& operator= (const NamedAggregateInfo&);
 
protected:
NamedAggregateInfo();
virtual ~NamedAggregateInfo();
};
 
/**
* Information about the monitors and types currently in an engine.
* Instances of this class are returned by the inspectEngine
* method of the EngineManagement interface and can be deleted with the
* deleteInfo function.
*
* When an EngineInfo class is deleted, everything returned by the
* getMonitors, getEventTypes, etc methods is deleted.
* This includes the arrays themselves, the classes pointed to by
* the arrays and any strings returned by those classes. This means
* that deleteInfo is the only cleanup method that needs to be called
* after an engine inspection.
*/
class AP_ENGINE_CLIENT_API EngineInfo {
 
friend AP_ENGINE_CLIENT_API void deleteInfo(EngineInfo* info);
 
public:
/**
* Gets the number of monitors in the engine.
*/
virtual unsigned int getNumMonitors() const = 0;
 
/**
* Gets the number of Java applications in the engine.
*/
virtual unsigned int getNumJavaApplications() const = 0;
 
/**
* Gets the number of event types in the engine.
*/
virtual unsigned int getNumEventTypes() const = 0;
 
/**
* Gets the number of timers in the engine.
*/
virtual unsigned int getNumTimers() const = 0;
 
/**
* Gets the number of aggregate functions in the engine.
*/
virtual unsigned int getNumAggregates() const = 0;
 
/**
* Returns information about the monitors in the engine,
* in the form of a NULL terminated array of pointers to
* MonitorInfo objects. The size of the array can be found
* by calling getNumMonitors (or looking for the
* NULL terminator).
*/
virtual NamedMonitorInfo** getMonitors() const = 0;
 
/**
* Returns information about the Java applications in the
* engine, in the form of a NULL terminated array of pointers
* to JavaApplicationInfo objects. The size of the array can
* be found by calling getNumJavaApplications (or looking for
* the NULL terminator).
*/
virtual NamedJavaApplicationInfo** getJavaApplications() const = 0;
 
/**
* Returns information about the event types in the engine,
* in the form of a NULL terminated array of pointers to
* NamedEventTypeInfo objects. The size of the array can be
* found by calling getNumEventTypes (or looking for the
* NULL terminator).
*/
virtual NamedEventTypeInfo** getEventTypes() const = 0;
 
/**
* Returns information about the timers in the engine,
* in the form of a NULL terminated array of pointers to
* NamedTimerInfo objects. The size of the array can be
* found by calling getNumTimers (or looking for the
* NULL terminator).
*/
virtual NamedTimerInfo** getTimers() const = 0;
 
/**
* Returns information about the aggregate functions in the
* engine, in the form of a NULL terminated array of pointers
* to NamedAggregateInfo objects. The size of the array can be
* found by calling getNumAggregates (or looking for the
* NULL terminator).
*/
virtual NamedAggregateInfo** getAggregates() const = 0;
 
/**
* Gets the number of contexts in the engine.
*/
virtual unsigned int getNumContexts() const = 0;
 
/**
* Returns information about the contexts in the
* engine, in the form of a NULL terminated array of pointers
* to ContextInfo objects. The size of the array can
* be found by calling getNumContexts (or looking for
* the NULL terminator).
*/
virtual NamedContextInfo** getContexts() const = 0;
 
private:
EngineInfo(const EngineInfo&);
EngineInfo& operator= (const EngineInfo&);
 
protected:
EngineInfo();
virtual ~EngineInfo();
};
 
/**
* The Engine Management class acts as the interface to the Engine,
* and allows operations to be carried out on it. It is not
* possible to construct an object of this class. The static
* methods supplied below in the engine namespace must be used
* instead.
*
* Because an EngineManagement object is also an EventConsumer,
* it can have events sent to it (and to the Engine) through its
* sendEvents() method.
*/
class AP_ENGINE_CLIENT_API EngineManagement : public com::apama::event::EventConsumer {
  
public:
enum ConnectMode {
CONNECT_LEGACY,
CONNECT_PARALLEL
};
 
public:
/**
* Inject MonitorScript text into the Engine.
*
* @param script MonitorScript text to be injected.
* @exception EngineException
*/
virtual void injectMonitorScript(MonitorScript& script) = 0;
 
/**
* Inject MonitorScript text into the Engine,
* returning any warnings produced by the
* MonitorScript compiler
*
* @param script MonitorScript text to be injected.
* @return A pointer to a NULL terminated array of
* warnings which must be deleted with the
* deleteWarnings() function, or NULL if there are
* none
* @exception EngineException, which may contain
* warnings as well as an error message
*/
virtual const char* const* injectMonitorScriptWithWarnings(MonitorScript& script) = 0;
 
/**
* Inject MonitorScript text into the Engine,
* supplying the filename it was injected from and
* returning any warnings produced by the
* MonitorScript compiler
*
* @param script MonitorScript text to be injected.
* @param filename The filename the MonitorScript text
* was injected from
* @return A pointer to a NULL terminated array of
* warnings which must be deleted with the
* deleteWarnings() function, or NULL if there are
* none
* @exception EngineException, which may contain
* warnings as well as an error message
*/
virtual const char* const* injectMonitorScriptWithWarningsFilename(MonitorScript& script,
const char *filename) = 0;
 
/**
* Delete a named object from the Engine.
*
* @param name The name of the object to be deleted.
* @exception EngineException
*/
virtual void deleteName(const char * name) = 0;
 
/**
* Force deletion of a named object from the Engine.
*
* @param name The name of the object to be deleted.
* @exception EngineException
*/
virtual void forceDeleteName(const char * name) = 0;
 
/**
* Kill a named monitor in the Engine.
*
* @param name The name of the monitor to be killed.
* @exception EngineException
*/
virtual void killName(const char * name) = 0;
 
/**
* Deletes everything from the engine.
*/
virtual void deleteAll() = 0;
 
/**
* Injects a Java application (a jar) into the engine.
*
* @param jarbytes A pointer to the array of bytes
* containing the jar
* @param size The size of the jar
* @exception EngineException
*/
virtual void injectJava(const AP_uint8* jarbytes, AP_uint32 size) = 0;
 
/**
* Injects a Java application (a jar) into the engine.
*
* @param jarbytes A pointer to the array of bytes
* containing the jar
* @param size The size of the jar
* @return A pointer to a NULL terminated array of
* warnings which must be deleted with the
* deleteWarnings() function, or NULL if there are
* none
* @exception EngineException, which may contain
* warnings as well as an error message
*/
virtual const char* const* injectJavaWithWarnings(const AP_uint8* jarbytes,
AP_uint32 size) = 0;
 
/**
* Injects a Java application (a jar) into the engine.
*
* @param jarbytes A pointer to the array of bytes
* containing the jar
* @param size The size of the jar
* @param filename The name of the jar file
* @return A pointer to a NULL terminated array of
* warnings which must be deleted with the
* deleteWarnings() function, or NULL if there are
* none
* @exception EngineException, which may contain
* warnings as well as an error message
*/
virtual const char* const* injectJavaWithWarningsFilename(const AP_uint8* jarbytes,
AP_uint32 size, const char *filename) = 0;
 
/**
* Injects a CDP (Correlator Deployment Package file) into the engine.
*
* @param cdpbytes A pointer to the array of bytes
* containing the CDP file
* @param size The size of the CDP
* @exception EngineException
*/
virtual void injectCDP(const AP_uint8* cdpbytes, AP_uint32 size,
const char *filename=NULL) = 0;

/**
* Injects a CDP (Correlator Deployment Package file) into the engine.
*
* @param cdpbytes A pointer to the array of bytes
* containing the CDP file
* @param size The size of the CDP file
* @return A pointer to a NULL terminated array of
* warnings which must be deleted with the
* deleteWarnings() function, or NULL if there are
* none
* @exception EngineException, which may contain
* warnings as well as an error message
*/
virtual const char* const* injectCDPWithWarnings(const AP_uint8* cdpbytes,
AP_uint32 size) = 0;

/**
* Injects a CDP (Correlator Deployment Package file) into the engine.
*
* @param cdpbytes A pointer to the array of bytes
* containing the CDP file
* @param size The size of the CDP file
* @param filename The name of the CDP file
* @return A pointer to a NULL terminated array of
* warnings which must be deleted with the
* deleteWarnings() function, or NULL if there are
* none
* @exception EngineException, which may contain
* warnings as well as an error message
*/
virtual const char* const* injectCDPWithWarningsFilename(const AP_uint8* cdpbytes,
AP_uint32 size, const char *filename) = 0;

/**
* Get the Engine's current operational status. Use
* deleteStatus to delete the returned object when
* it is no longer needed.
*
* @exception EngineException
*/
virtual EngineStatus* getStatus() = 0;
 
/**
* Connect an event receiver to the Engine.
*
* @param consumer The EventConsumer to connect to the
* Engine.
* @param channels An array of names representing the
* channels to subscribe to. This is a null-terminated array
* of pointers to zero-terminated char arrays. If it is null or
* empty subscribe to all channels. Note that these channel
* names should be encoded in UTF-8.
* @disconnectSlow tell the correlator it can disconnect
* this receiver if it is slow. Only the first consumer's
* disconnectSlow value is used; subsequent consumers added
* to this EngineManagement object share the connection and
* thus the disconnect behaviour. Defaults to false.
* @return A reference to an EventSupplier resource, which the caller
* is responsible for freeing, using com::apama::event::deleteEventSupplier().
* Each EventSupplier resource must be explicitly disconnected or deleted
* before disconnecting this EngineManagement object.
* @exception EngineException
*/
virtual com::apama::event::EventSupplier* connectEventConsumer(
com::apama::event::EventConsumer* consumer,
const char* const* channels, bool disconnectSlow = false) = 0;
 
/**
* Connect this Engine as an event receiver to another Engine.
*
* @param target The Engine to connect to
* @param channels An array of names representing the
* channels to subscribe to. This is a null-terminated array
* of pointers to zero-terminated char arrays. If this is null or empty,
* subscribe to all channels. Note that these channel names
* should be encoded in UTF-8.
* @param disconnectSlow disconnect if slow. Only the first consumer's
* disconnectSlow value is used; subsequent consumers added to this
* EngineManagement object share the connection and thus the disconnect
* behavior.
* @param mode the connection mode to use,
* defaults to legacy (single connection, all
* events delivered to the default
* channel). Set to CONNECT_PARALLEL for
* connection per channel and channel values passed through.
* @return true if successful
* @exception EngineException
*/
virtual bool attachAsEventConsumerTo(
EngineManagement* target, const char* const* channels,
bool disconnectSlow = false, ConnectMode mode = CONNECT_LEGACY) = 0;
 
/**
* Connect this Engine as an event receiver to another Engine.
*
* @param host The hostname of the Engine to connect to
* @param port The port of the Engine to connect to
* @param channels An array of names representing the
* channels to subscribe to. This is a null-terminated array
* of pointers to zero-terminated char arrays. If this is null or empty,
* subscribe to all channels. Note that these channel names
* should be encoded in UTF-8.
* @param disconnectSlow disconnect if slow. Only the first consumer's
* disconnectSlow value is used; subsequent consumers added to this
* EngineManagement object share the connection and thus the disconnect
* behaviour.
* @param mode the connection mode to use,
* defaults to legacy (single connection, all
* events delivered to the default
* channel). Set to CONNECT_PARALLEL for
* connection per channel and channel values passed through.
* @return true if succesful
* @exception EngineException
*/
virtual bool attachAsEventConsumerTo(
const char* host, int port, const char* const* channels,
bool disconnectSlow = false, ConnectMode mode = CONNECT_LEGACY) = 0;
 
/**
* Unsubscribe as an event receiver from another engine.
*
* @param target The Engine to unsubscribe from.
* @param channels An array of names representing the
* channels to unsubscribe from. This is a null-terminated array
* of pointers to zero-terminated char arrays. If this is null or empty
* unsubscribe from all channels.
* @param mode the connection mode to use,
* defaults to legacy (single connection, all
* events delivered to the default
* channel). Set to CONNECT_PARALLEL for
* connection per channel and channel values passed through.
* @exception EngineException
*/
virtual void detachAsEventConsumerFrom(
EngineManagement* target, const char* const* channels,
ConnectMode mode = CONNECT_LEGACY) = 0;
 
/**
* Unsubscribe as an event receiver from another engine.
*
* @param host The host of the Engine to unsubscribe from.
* @param port The port of the Engine to unsubscribe from.
* @param channels An array of names representing the
* channels to unsubscribe from. This is a null-terminated array
* of pointers to zero-terminated char arrays. If this is null or empty
* unsubscribe from all channels.
* @param mode the connection mode to use,
* defaults to legacy (single connection, all
* events delivered to the default
* channel). Set to CONNECT_PARALLEL for
* connection per channel and channel values passed through.
* @exception EngineException
*/
virtual void detachAsEventConsumerFrom(
const char* host, int port, const char* const* channels,
ConnectMode mode = CONNECT_LEGACY) = 0;
 
/**
* Inject events into the Engine (inherited from
* EventConsumer), automatically batching messages
* on a separate thread. May return before events are
* sent - call flushEvents before exiting.
*
* @param events An array of pointers to Event objects
* containing the events to inject into the Engine.
* @exception EngineException
*/
virtual void sendEvents(const com::apama::event::Event* const* events) = 0;
 
/**
* Inject events into the Engine
*
* @param events An array of pointers to Event objects
* containing the events to inject into the Engine.
* @exception EngineException
*/
virtual void sendEventsNoBatching(const com::apama::event::Event* const* events) = 0;
 
/**
* Send any outstanding events sent via sendEvents.
*/
virtual void flushEvents() = 0;
 
/**
* Returns information about the monitors, event types and
* container types which exist in the engine. Use deleteInfo
* to delete the returned object when it is no longer needed.
*
* @return Information about the engine.
* @exception EngineException
*/
virtual EngineInfo* inspectEngine() = 0;
 
/**
* This method is used to check that the Engine is
* still alive, potentially reconnecting if needed.
* If the Engine is alive it returns
* normally. If there is a problem then an
* EngineException is thrown.
*
* @exception EngineException
*/
virtual void ping() = 0;
 
/**
* This method is used to check that this object is
* still connected to the Engine. It will never
* reconnect. Returns true if connected.
*/
virtual bool isConnected() = 0;
 
protected:
EngineManagement();
virtual ~EngineManagement();
 
private:
EngineManagement(const EngineManagement&);
EngineManagement& operator= (const EngineManagement&);
};
 
/**
* This function must be called once per process first before
* any other Engine operations are carried out.
*
* @exception EngineException
*/
AP_ENGINE_CLIENT_API void engineInit(const char* processName = "C++ Client");
 
/**
* This function (or engineInit) must be called once per process first before
* any other Engine operations are carried out.
*
* @exception EngineException
*/
AP_ENGINE_CLIENT_API void engineInitMessaging(const char *processName,
bool initMessaging=true);
 
/**
* This function must be called once per process before the
* application closes down. It ensures that communications are
* shutdown properly and state cleaned up.
*/
AP_ENGINE_CLIENT_API void engineShutdown();
 
/**
* This function attempts to establish a connection to an
* Engine. It returns an EngineManagement object that can be used
* to access the Engine.
*
* @param host The machine name where an Engine can be located.
* @param port The port that the Engine is listening on for
* transport negotiations with the client.
* @return An EngineManagement object if an Engine is located and
* a connection established.
* @exception EngineException
*/
AP_ENGINE_CLIENT_API EngineManagement* connectToEngine(const char* host,
unsigned short port);
 
/**
* Attempt to establish a receive-only connection to an Engine listening
* on the named host and port. If successful, the returned
* EngineManagement can be used for the connectEventConsumer(),
* getStatus(), inspectEngine() and ping() operations.
* All other operations will fail.
*
* @param host The hostname of the machine the Engine is running on.
* @param port The port that the Engine is listening on.
* @return An EngineManagement object operating in receive-only mode.
* @exception EngineException If the connection cannot be established.
*/
AP_ENGINE_CLIENT_API EngineManagement* connectToEngineReceiveOnly(const char* host,
unsigned short port);
 
/**
* Attempt to establish a monitor-only connection to an Engine listening
* on the named host and port. If successful, the returned
* EngineManagement can be used for the getStatus(),
* inspectEngine() and ping() operations. All other operations will fail.
*
* @param host The hostname of the machine the Engine is running on.
* @param port The port that the Engine is listening on.
* @return An EngineManagement object operating in monitor-only mode.
* @exception EngineException If the connection cannot be established.
*/
AP_ENGINE_CLIENT_API EngineManagement* connectToEngineMonitorOnly(const char* host,
unsigned short port);
 
/**
* This function allows disconnection from an Engine.
*
* @param corr The Engine to disconnect from.
*/
AP_ENGINE_CLIENT_API void disconnectFromEngine(EngineManagement* corr);
  
/**
* This function allows creation of MonitorScript objects.
*
* @param monitorString MonitorScript monitor/event definitions
* @return A MonitorScript object.
*/
AP_ENGINE_CLIENT_API MonitorScript* createMonitorScript(const char* monitorString);
 
/**
* This function allows deletion of MonitorScript objects.
*
* @param mon The MonitorScript object to delete.
*/
AP_ENGINE_CLIENT_API void deleteMonitorScript(MonitorScript* mon);
 
/**
* This function allows deletion of an EngineStatus object.
*
* @param status The EngineStatus object to delete.
*/
AP_ENGINE_CLIENT_API void deleteStatus(EngineStatus* status);
 
/**
* This function allows deletion of an EngineInfo object.
* All objects returned by any calls to the methods of the
* EngineInfo object are also deleted, so after calling
* inspectEngine, deleteInfo is the only method which
* needs to be called to clean up.
*
* @param info The EngineInfo object to delete.
*/
AP_ENGINE_CLIENT_API void deleteInfo(EngineInfo* info);
 
/**
* This function allows deletion of the lists of warnings
* returned by injectMonitorScriptWithWarnings(), injectCDPWithWarnings(),
* and injectJavaWithWarnings()
*
* @param warnings A list of warnings to be deleted
*/
AP_ENGINE_CLIENT_API void deleteWarnings(const char* const* warnings);
 
/**
* Set custom parameters for this instance of the client library.
* Must be called before engineInit. The parameters are passed
* as a set of name, value pairs formatted as
* <name1>=<value1>;<name2=value2>;
* (i.e. equals sign between name and value, and semicolon separating
* the name value pairs).
*
* The following parameters are defined so far.
*
* ConfigFile - A filename from which to read a configuration file
* LogicalID - The logical id with which this component should be
* identified (a 64-bit integer)
*/
AP_ENGINE_CLIENT_API void setEngineParams(const char* params);
 
} // namespace engine
} // namespace apama
 
} // namespace com
 
#endif // ENGINE_CLIENT_CPP_HPP