In this post, we're going to learn, how to create an event gateway in Lucee. Before that, we should know about, what is an Event gateway.

In common, An event gateway is a program, which is continuously monitoring a resource & do necessary actions on certain events. In Lucee, we also have the similar process available. Recent versions of Lucee come up with two built-in event gateways ( Directory watcher & Mail watcher ). But we could create our own event gateways for handling any special scenarios like SASS compilation etc.

• A Gateway component
• A Gateway Driver component
• A Listener component ( Optional )

Of Course, we should place these files in right location & each file should be in some specific structure. So, i'll mention the right locations, whenever it is needed. Just remember the directory mappings below.

• {{lucee-web}} : this is the WEB-INF folder of webroot.
• {{lucee-server}} : this is the folder, where Lucee has been installed.

It should be placed in "{{lucee-server}}/context/context/admin/gdriver/demoGateway.cfc".

This is the file, which is responsible for doing the actions whatever we need. This component must contain some public functions inside that.

• init function, which receives the all configurations for the event gateway.
• start function, which will be continuously running in the background based on a config "variables.state".
• A stop and restart functions to stop/restart the event gateway from Admin interface.
• A getState function, which returns the current state of the gateway instance (running,stopping,stopped).
• A sendMessage function, to manually call the event gateway from code using sendGatewayMessage().

Additionally you might need to create some private functions for error logging etc. Here is the sample code for demoGateway.cfc

demoGateway.cfc

It should be placed in {{lucee-web}}/lucee/components/lucee/extension/gateway/demoDriver.cfc.

The driver is used to configure and define your Gateway. Using this, you can define the form fields in the Lucee admin settings page for your gateway. If you need more configurations, you might need to add them as fields array in this driver component. Also it makes sure that your gateway is listed as an available Gateway in the Lucee Admin page.

• getClass():string
  • Returns the java class name.
  • If the gateway is Java based, then the java class has to implement the interface "org.opencfml.eventgateway.Gateway".
  • If it is not java based, then this method must return an empty string or void.
• getCFCPath():string
  • Returns the cfc path, when the gateway is cfc based.
  • If it is not cfc based, then this method must return an empty string or void.
• getLabel():string
  • The label (friendly name) of the gateway.
• getDescription():string
  • The description of the gateway
• onBeforeUpdate(string cfcPath, string startupMode, struct custom):void
  • This method is invoked before the settings entered in the form are saved.
  • This method can be used to validate the entered data.
• onBeforeError(cfcatch):void
  • Invoked before an error is thrown.
  • Can be used to throw your own error, and/or do logging.
• getListenerCfcMode():string.
  • It should be "none", if no listener is defined.
  • It should be "required", if we're defining a listener for the gateway.
• getListenerPath():string
  • returns the config, location of a listener cfc.

demoDriver.cfc

It should be placed in {{lucee-web}}/lucee/components/lucee/extension/gateway/demoGatewayListener.cfc.

Listener is component which is used to make the Gateway file as small as we can. If an event occurs for the gateway, it should call a corresponding function from the listener component.

demoGatewayListener.cfc

Once all the files are placed in right location, we're all set to create the event gateway instance from Lucee web administrator under menu "Services --> Event Gateway".

While creating the gateway instance from the web administrator, you might need to enter the details that are required for the event gateway as per the fields configuration in driver component.

For more details about creating Event gateways for a specific task, please check one of our blog post about SASS compilation.