This shows you the differences between the selected revision and the current version of the page.
| ecs_tec:how_to_write_a_source 2007/02/09 18:27 | ecs_tec:how_to_write_a_source 2007/02/09 18:49 current | ||
|---|---|---|---|
| Line 11: | Line 11: | ||
| <implement class="com.eventgnosis.sources.XmlTCPIPSocketListener" source="ecs.jar" type="Java" /> | <implement class="com.eventgnosis.sources.XmlTCPIPSocketListener" source="ecs.jar" type="Java" /> | ||
| </sourceType> | </sourceType> | ||
| - | </code> \\ \\ This XML snippet should be placed in [[ecs: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 “EcsTcpEventReceiver” source. You will also need to set the path to your implementation\\ (here ''com.eventgnosis.sources.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. | + | </code> This XML snippet should be placed in [[ecs: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 “EcsTcpEventReceiver” source. You will also need to set the path to your implementation\\ (here ''com.eventgnosis.sources.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. |
| - Add any specific attributes (private class variables) 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.sources.XmlTCPIPSocketListener.java.''\\ \\ | - Add any specific attributes (private class variables) 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.sources.XmlTCPIPSocketListener.java.''\\ \\ | ||
| - | - Implement //**setVars()**//. First call the superclass method, extracting each ECA configuration parameter into your Source attributes for this instance of the protocol. Examples of configuration parameters for the XMLTCPIPSocketListener 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 Source’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 mere primitives but are composite types, such as the type //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 in ECA so that the GUI can understand the composition: <code xml> | + | - Implement //**setVars()**//. First call the superclass method, extracting each ECA configuration parameter into your Source attributes for this instance of the protocol. Examples of configuration parameters for the ''XMLTCPIPSocketListener'' 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 Source’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 mere primitives but are composite types, such as the type //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 in ECA so that the GUI can understand the composition: <code xml> |
| <parameterType description="%Login%" objectId="Login"> | <parameterType description="%Login%" objectId="Login"> | ||
| <implement class="com.eventgnosis.sources.LoginInfo" source="ecs.jar" type="Java" /> | <implement class="com.eventgnosis.sources.LoginInfo" source="ecs.jar" type="Java" /> | ||
| </parameterType> | </parameterType> | ||
| - | </code> 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.sources.LoginInfo'', and its use in setVars() in ''com.eventgnosis.sources.EmailSlave.'' In summary, each Source attribute must be carefully processed in setVars() using the following steps: | + | </code> 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.sources.LoginInfo'', and its use in //setVars()// in ''com.eventgnosis.sources.EmailSlave.'' In summary, each Source attribute must be carefully processed in //setVars()// using the following steps: |
| - Get the parameter instance as a string specified by name and index. | - Get the parameter instance as a string specified by name and index. | ||
| - | - Convert to the requisite class attribute type, if it’s not a Java String. | + | - Convert to the requisite class attribute type, if it’s not a Java ''String''. |
| - Check for conversion errors, and if so, log errors and consider disabling the entire object for fatal values or applying a default value. | - Check for conversion errors, and if so, log errors and consider disabling the entire object for fatal values or applying a default value. | ||
| - Implement the consistency rules between parameters and error out if there are serious inconsistencies. | - Implement the consistency rules between parameters and error out if there are serious inconsistencies. | ||
| - | - 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 source. 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: <code java> | + | - 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 source. 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: <code java> |
| if( connection == null ) { | if( connection == null ) { | ||
| Line 28: | Line 28: | ||
| } | } | ||
| </code> | </code> | ||
| - | - Implement disconnect() using the class and connection attributes. Implement this method according to the needs of your particular protocol, knowing that this method is responsible for terminating the connection to the external event source and releasing system resources. This method should also be called if the ECS exits in a controlled manner.\\ \\ | + | - Implement //**disconnect()**// using the class and connection attributes. Implement this method according to the needs of your particular protocol, knowing that this method is responsible for terminating the connection to the external event source and releasing system resources. This method should also be called if the ECS exits in a controlled manner.\\ \\ |
| - | - Implement getNextEvent(), probably the most important method in a source. It reads your specific protocol stream, converting it to the EventGnosis-specific internal format. This method is continually called by the framework, which has the effect of pulling events into the ECS, given your particular protocol configuration instance. For an example of a good getNextEvent() implementation see \\ ''com.eventgnosis.sources.XMLTCPIPSocketListenerSlave.java.''\\ \\ Overall, its responsibilities are the following: | + | - Implement //**getNextEvent()**//, probably the most important method in a source. It reads your specific protocol stream, converting it to the EventGnosis-specific internal format. This method is continually called by the framework, which has the effect of pulling events into the ECS, given your particular protocol configuration instance. For an example of a good //getNextEvent()// implementation see \\ ''com.eventgnosis.sources.XMLTCPIPSocketListenerSlave.java.''\\ \\ Overall, its responsibilities are the following: |
| * Monitor the health of the inbound connection (may not be necessary in many circumstances), forcing reconnection if necessary. | * Monitor the health of the inbound connection (may not be necessary in many circumstances), forcing reconnection if necessary. | ||
| - | * Format the incoming protocol-specific stream into discrete EventGnosis events, returning one for each getNextEvent() call. | + | * Format the incoming protocol-specific stream into discrete EventGnosis events, returning one for each //getNextEvent()// call. |
| - | * Continue to check if the ECS is still running via the SystemObject. continueOperation() method. \\ | + | * Continue to check if the ECS is still running via the ''SystemObject''. //continueOperation() method//. \\ |
| - | - Implement shutdown() and kill(), methods that are used to perform cleanup operations when the ECS is shutdown gracefully or killed.\\ \\ | + | - Implement //**shutdown()**// and //**kill()**//, methods that are used to perform cleanup operations when the ECS is shutdown gracefully or killed.\\ \\ |
| - | - Implement getProtocolName(), a simple method that returns a string naming the particular protocol.\\ \\ | + | - Implement //**getProtocolName()**//, a simple method that returns a string naming the particular protocol.\\ \\ |
| - | - Implement getConfigXml(), which is a snapshot of configuration state.\\ \\ | + | - Implement //**getConfigXml()**//, which is a snapshot of configuration state.\\ \\ |
| - | - Implement getRuntimeXml(), which is a snapshot of runtime state.\\ \\ | + | - Implement //**getRuntimeXml()**//, which is a snapshot of runtime state.\\ \\ |
| - | - Implement toString(), another method that shows object state which is useful for debugging. | + | - Implement //**toString()**//, another method that shows object state which is useful for debugging. |