by SuperBonBon

JAFS events and EAI

Introduction

Definitions :

• EIS : Enterprise Information System
• EAI : Enterprise Application Integration, the process to integrate an application into an EIS.

JAFS contains an events dispatching (push) mechanism who can be used to integrate the server into your software infrastructure quite easily.

Currently the events are defined into 3 distinct categories :

• Service events : All the events fired by the JAFS services.
• Server events : The events fired by the deployed FTP server instances.
• Session events : FTP client session related events.

As you can see, all events names are self explanatory, so no need to document them one by one.

All events when fired have an attached events Object who contains informations related to the events execution context ( I.E : a file path for an file related event ).

Once fired by JAFS components all events are dispatched to registered events listeners who can then handle the event and interact with your EIS. All registered events listeners can select the type of events set they want to receive. The listeners can also filter the event they have received and decide (based on the data contained into the event object) if the event needs to be handled or not.

If you need to retreive (pull) data from your EIS, JAFS provides an mechanism to plug receivers who can be used to read the data form the EIS and dispatch it within JAFS.

The following schema summarize everything :

Provided events listeners

Currently six events listener are provided :

• net.sbbi.jafs.eventslisteners.JMXNotificationEventsListener : Fires events as JMX notifications via a JMX Model bean.
• net.sbbi.jafs.eventslisteners.JabberEventsListener : Fires events on an Jabber IM Server for a given user.
• net.sbbi.jafs.eventslisteners.JMSEventsListener : Fires events on an Java Messaging Queue.
• net.sbbi.jafs.eventslisteners.MailEventsListener : Publish the events into an e-mail
• net.sbbi.jafs.eventslisteners.SoundEventsListener : Plays a sound for a given event
• net.sbbi.jafs.eventslisteners.SystemOutEventsListener : Output the event data to the System.out ( for testing purpose ).

Provided events receivers

Currently three events receivers are provided :

• net.sbbi.jafs.eventslisteners.SyslogEventsListener : Unix syslog generic receiver
• net.sbbi.jafs.eventslisteners.NetgearDG834GSyslogEventsListener : Netgear DG834 DSL router modem syslog receiver to automatically shield the JAFS deployed servers against DOS and ports scan reported by the router via syslog message broadcast.
• net.sbbi.jafs.eventslisteners.SystemOutEventsListener : Output recieved syslogs to System.out ( for testing purpose ).

Events listeners setup

To plug an events listener you'll have to add an events listener configuration entry into the JAFS service config file.

Each configuration entry consists of :

• An entry name
• An listener class name ( such as described above )
• A list of settings for the listener
• A list of events names ( ServicesEvents,ServerEvents,SessionEvents class ) that the listener will receive

You can see a sample configuration entry here which will register 2 events listener :

      
      <jafs-service xmlns="http://www.sbbi.net/jafs/1.0/jafs-service"
                      ...>
        ...
        <events-listeners>
          <listener name="systemoutSessionEvents" 
                    class-name="net.sbbi.jafs.eventslisteners.SystemOutEventsListener">

            <setting name="targetFtpServersCode">sample_server</setting>
            <setting name="targetPaths">../ftp/pub/userhome,../ftp/pub/testdir</setting>
            <setting name="targetClientsIp">127.0.0.1,192.168.1.33</setting>
      
            <target-events>
              <server-event name="onBlackListMatch"/>
              <session-event name="*"/>
            </target-events>    
          </listener>
          
          <listener name="jabberSessionEvents" 
                    class-name="net.sbbi.jafs.eventslisteners.JabberEventsListener" asynchronous="true">

            <setting name="targetPaths">../ftp/pub/userhome,../ftp/pub/testdir</setting>
            <setting name="targetClientsIp">127.0.0.1,192.168.1.33</setting>

            <setting name="sslServer">true</setting>
            <setting name="serverName">jabber.mycomp.com</setting>
            <setting name="serverPort">1234</setting>
            <setting name="userName">username</setting>
            <setting name="userServer">jabber.mycomp.com</setting>
            <setting name="password">password</setting>
            <setting name="messagesReceiver">messagesReceiver@jabber.mycomp.com</setting>
            <setting name="eventsPerMessage">4</setting>
            <setting name="sendTestMessage">true</setting>
            <setting name="reconnectRetriesMaxTime">10</setting>
  
            <target-events>
              <services-event name="onIPBlackListReload"/>  
              <session-event name="onFileUploadStart"/>
              <session-event name="onFileUploadFinished"/>
            </target-events>    
          </listener-->
        </events-listeners>
        ...
      </jafs-service>
      

The first listener( systemoutSessionEvents ) will output to the console all session events ( <session-event name="*"/> ) and when an clients matchs an ip blacklist entry ( <server-event name="onBlackListMatch"/> ). The second listener ( jabberSessionEvents ) will send a message asynchonously to a Jabber server each time 4 events of type onFileUploadStart, onFileUploadFinished are received for client IP 127.0.0.1 or 192.168.1.33 for a file contained into the ../ftp/pub/userhome or ../ftp/pub/testdir directory. The event onIPBlackListReload will always be received since it does not contains any client IP or file path related information.

Generic settings

All events listener can filter an event based on the event object content. Currently 3 settings to filter the events are available :

• targetFtpServersCode : For server and session events. A comma delimited list of ftp server codes to determine for which FTP server instance the event will be received by the listener.
• targetPaths : For session events. A comma delimited list of file path. The value will instruct the listener to only accept file transferts related events occuring into a certain set of directories. This gives you the possibility to monitor file related session events for certain directories.
• targetClientsIp : For session events. A comma delimited list of IP, the setting allows the listener to only accept session events for a certain set of target IP.

If you're not happy with the provided filters you can write some code to create your own filters quite easily.

Listeners settings

You can see here all the available settings for the provided events listeners:

        
        <listener name="soundsListener" class-name="net.sbbi.jafs.eventslisteners.SoundEventsListener">
          <setting name="targetFtpServersCode">sample_server,my_other_server_code</setting>
 
          <setting name="onConnect">/foo/bar/onConnectSoundFile.wav</setting>
          <setting name="onDisconnect">/foo/bar/onDisconnectSoundFile.wav</setting>
          <target-events>
            <session-event name="onConnect"/>
            <session-event name="onDisconnect"/>
          </target-events>    
        </listener> 
        

Events receivers setup

Each events receivers are configured into an events receiver entry. Each entry consists of an name, a receiver class name, an execution time interval in ms and finally a set of custom setting use to configure the receiver.

      
      <jafs-service xmlns="http://www.sbbi.net/jafs/1.0/jafs-service"
                      ...>
        ...
        <events-receivers>
          <receiver name="myEventsReceiver" class-name="com.mycompany.TestPullEventsListener" listening-time="1000">
            <setting name="mySampleSetting">testValue</setting>
          </receiver>
        </events-receivers>
        ...
      </jafs-service>
      

Receivers settings

You can see here all the available settings for the provided events receivers:

Create your own events listeners

To create your own listener you'll have to write a class that implements the net.sbbi.jafs.events.PushEventsListener interface an implement the following methods :

• filterEvent() : filters the event, used to accept (true returned) or reject an event based on the event object event content.
• getName() : retreive the name of the events listener.
• setName() : sets the name of the events listener, called after the listener object creation.
• handleEvent() : handle the event.
• enableLogging() : for loggin purpose called before the parameterize method.
• service() : used to lookup services objects.
• start() : called when the listener is started.
• stop() : called when the listener is stopped.
• parameterize() : used to retrieve the settings of the listener, called before the start method.

You can see a small example class here :

      package com.mycompany;
      
      import net.sbbi.jafs.services.ServersDeploymentService;
      
      import org.apache.avalon.framework.logger.Logger;
      import org.apache.avalon.framework.parameters.ParameterException;
      import org.apache.avalon.framework.parameters.Parameters;
      import org.apache.avalon.framework.service.ServiceException;
      import org.apache.avalon.framework.service.ServiceManager;
      
      public class TestEventsListener extends GenericEventsListener 
                                      implements PushEventsListener {
      
        private String myNeededParam;
        private String myOptionalParam;
        
        public void handleEvent( int topic, String event, 
                                 Event eventData, long eventTimestamp ) {
          System.out.println( "Received event " + event + 
                              " with context object " + eventData );
        }
        
        public boolean filterEvent( Event eventData ) {
          // no special filter needed
          return true;
        }
        
        public void service( ServiceManager manager ) throws ServiceException {
          ServersDeploymentService deplySrv = 
            (ServersDeploymentService)manager.lookup( ServersDeploymentService.ROLE );
          System.out.println( "Deployed server codes are : " + 
                              deplySrv.getDeployedServersCodes() );
        }
        
        public void start() throws Exception {
        }
        
        public void stop() throws Exception {
        }
        
        public void parameterize( Parameters params ) throws ParameterException {
          myNeededParam = params.getParameter( "myNeededParam" );
          myOptionalParam = params.getParameter( "myOptionalParam", null );
        }
      }
      

You can extend the net.sbbi.jafs.events.GenericEventsListener interface if you want a part of the job to be done automatically and the net.sbbi.jafs.events.GenericServerEventsListener, net.sbbi.jafs.events.GenericServicesEventsListener or net.sbbi.jafs.events.GenericSessionEventsListener if you want certain generic filtering capabilities.

Once compiled, put the class into a jar file and drop it into the JAFS libs directory, configure the service config file to register your new listener and start JAFS, everything should be allright :o)

Create your own events receivers

This time you'll need to implement the net.sbbi.jafs.events.PullEventsListener interface which is quite similar to the net.sbbi.jafs.events.PushEventsListener interface. You'll have to implement the following methods :

• isEventReady() : reads from the EIS if an event is ready to be handled, this method will be called each listening time ms. When the method returns true, the handleEvent() method will be called.
• getName() : retreive the name of the events receiver.
• setName() : sets the name of the events receiver, called after the receiver object creation.
• handleEvent() : handle the readen event.
• enableLogging() : for logging purpose called before the parameterize method.
• service() : used to lookup services objects.
• start() : called when the receiver is started.
• stop() : called when the receiver is stopped.
• parameterize() : used to retrieve the settings of the receiver, called before the start method.

You can see a small example class here :

      package com.mycompany;
      
      import java.io.IOException;
      
      import org.apache.avalon.framework.logger.Logger;
      import org.apache.avalon.framework.parameters.ParameterException;
      import org.apache.avalon.framework.parameters.Parameters;
      import org.apache.avalon.framework.service.ServiceException;
      import org.apache.avalon.framework.service.ServiceManager;
      
      public class TestEventsListener implements PullEventsListener {
      
        private String name;
        private Logger log;
        
        public String getName() {
          return name;
        }
        
        public void setName( String listenerName ) {
          name = listenerName;
        }
        
        public void enableLogging( Logger logger ) {
          this.log = logger;
        }
        
        public void handleEvent() throws Exception {
          // handle the event stored into memory
        }
        
        public boolean isEventReady() throws IOException {
          // read the event into memory
          return true;
        }
        
        public void parameterize( Parameters params ) throws ParameterException {
        }
        
        public void service( ServiceManager manager ) throws ServiceException {
        }
        
        public void start() throws Exception {
        }
        
        public void stop() throws Exception {
        }
      }
      

Once compiled, put the class into a jar file and drop it into the JAFS libs directory, configure the service config file to register your new receiver and start JAFS.