Destination SystemObjects send events out of the ECS, often in an asynchronous manner due to the nature of both the ECS and the nature of the receiving protocol. Because of the unpredictable arrival of events to the destination from within the source as well as the unpredictable rate of consumption of events via the external receiver, a Destination must be threaded. This is done by specifying the right parameter for the setEventProcessor() call in the local setVars() method.

A Destination is responsible for converting an “event” in the EventGnosis’ proprietary, normalized Event format (basically a small XML document) and streaming it to the receiving external entity via its specific protocol.

The following steps need to be performed when writing a typical EventGnosis Destination. It is assumed that you do understand, in detail, the protocol for the Destination you are writing.

1. Extend the abstract class com.eventgnosis.destinations.EventDestinationBase, which itself extends com.eventgnosis.system.SystemObject and implements the com.eventgnosis.system.OutputEvents interface. Since a Destination is a SystemObject, you inherit significant functionality, and your new object will be part of the startup and runtime object hierarchy automatically, given that this Destination is active and configured into an ECA. This behind-the-scenes work is performed by the framework.
   
   
2. Come up with a terse English text description of your Destination with configuration parameters between the ‘%’ modeled after the destinationType examples in
   EV_HOME/config/extra/emptyECA.xml. Any text surrounded by ‘%’ will be assumed to be a parameter by the GUI and will be presented to the user as a configuration parameter, validated and then stored as a configuration value. Every parameter should have a corresponding parameterType definition in the EMML (XML) file. Finally, this parameter will be parsed by the ECS Configuration Manager at startup and used by the particular Destination to set its configuration in its setVars() method.
   Example XML:

   <destinationType description="Send EventGnosis EMS events to %Host% and %Port%." objectId="EmsTcpEventSender" schema="">
        <implement class="com.eventgnosis.destinations.XmlTCPIPSocketDestination" source="ecs.jar" type="Java" /> 
   </destinationType>

   This XML snippet should be placed in EV_HOME/config/extra/emptyECA.xml, the source of configuration information for the GUI and the ECS. Note that this example has two parameters (host & port), which will be set and validated by the GUI when a user selects an “EcsTcpEventSender” Destination. You will also need to set the path to your implementation (here com.eventgnosis.Destinations.XmlTCPIPSocketListener) and its jar. Typically, you could create an addon jar that is separate from the ecs.jar and is specific to your company. This new jar must, of course, be in the classpath of the ECS for it to be recognized.
   

3. Add any specific attributes that are needed to retain any state information for your protocol to the implementing class, as in the private attributes at the top of the class com.eventgnosis.Destinations.XmlTCPIPSocketListener.
   
   
4. Implement setVars(). First call the superclass method, extracting each ECA configuration parameter into your Destination attributes for this instance of the protocol. Examples of configuration parameters for the XMLTCPIPSocketSender are port number and interface name. Note that each parameter set by the GUI can be extracted using the object EmmlConfig (eCfg) object using method getParameter( name, instance# ), where name is the name of the parameter from its XML description and instance number is a simple index of which configuration instance (there can be more than one with the same name) starting from zero. The first instance is zero, the next one, and so on. Note that getParameter(…) returns a String. If the Destination’s class attribute is not of type java.lang.String it must be converted to its requisite type. Conversion utilities for the most common types can be found in com.eventgnosis.util.Util.java. Furthermore, some types set by the GUI are not primitives but are composite types, such as the type com.eventgnosis.util.LoginInfo, which includes user name and password. A composite type can be referred to in a SystemObject description, but it must then be defined with a parameterType XML snippet inside ECA so that the GUI can understand the composition:

   <parameterType description="%Login%" objectId="Login">
        <implement class="com.eventgnosis.Sources.LoginInfo" source="ecs.jar" type="Java" /> 
   </parameterType>

   If composite types are utilized, they must of course be implemented, added into your jar and the usual information specified in the “implement” section so that the ECS can locate your code. Examples of such implementations are com.eventgnosis.Destinations.LoginInfo, and its use in setVars() in com.eventgnosis.Destinations.EmailSlave. In summary, each Destination attribute must be carefully processed in setVars() using the following steps:

   1. Get the parameter instance as a string specified by name and index.
   2. Convert to the requisite class attribute type, if it’s not a Java String.
   3. Check for conversion errors, and if so, log errors and consider disabling the object for fatal values or applying a default value.
   4. Implement the consistency rules between parameters and error out if there are serious inconsistencies.
5. Implement connect() using the class attributes you just set. Implement these methods according to the needs of your particular protocol, knowing that this method alone is responsible for initiating the connection to the external event Destination. Log errors using logging conventions such as err, warn or info to indicate severity. These messages are very useful for debugging problems. Finally, note that connect() will not be explicitly called by the framework. The suggested method for establishing a connection is to use a class attribute that assumes an illegal value (such as null) until the connection sequence has succeeded. Place the call to connect() in the getNextEvent() method surrounded by a check for this illegal value so that the connection logic is only performed when there is no connection, or if a prior connection has gone bad and a new connection initialization sequence needs to happen.
   Example:

   if( connection == null ) {
   	connection =  {…do connection logic }
   }

6. Implement disconnect() using the class and connection attributes, according to the needs of your particular protocol, knowing that this method is responsible for terminating the connection to the external event Destination. This method should also be called if the ECS exits in a controlled manner, thus releasing system resources to the operating system.
   
   
7. Implement outputEvent(), probably the most important method for destinations. It initiates a connection with the outside entity, and then continually reads EventGnosis Events, converting it and pushing it out on your specific protocol stream. This method is continually called by the framework, which has the effect of pushing events out of the ECS, given your particular protocol configuration instance. For an example of a good outputEvent() implementation see
   com.eventgnosis.destinations.XMLTCPIPSocketDestination.
   Overall, its responsibilities are the following:
   • Monitor the health of the outbound connection (may not be necessary in many circumstances), forcing reconnection if necessary.
   • Format the incoming event into the outbound protocol-specific stream, returning each time an entire event has been sent.
   • Continue to check if the ECS is running via the SystemObject. continueOperation() method.
     
     
8. Implement shutdown() and kill(), methods that are used to perform cleanup operations when the ECS is shutdown gracefully or killed.
   
   
9. Implement getProtocolName(), a simple method that returns a string naming the particular protocol.
   
   
10. Implement getConfigXml(), which is a snapshot of configuration state.
    
    
11. Implement getRuntimeXml(), which is a snapshot of runtime state.
    
    
12. Implement toString(), another method that shows object state which is useful for debugging.