PlugIn

OpenBlueDragon has a powerful plugin interface that allows you to easily add new functionality to the core engine without having to worry about understanding every part of the engine.

You can package your plugin's up as downloadable JAR files, that users simply drop-in into their /WEB-INF/lib/ folder and restart. OpenBD will autodiscovery the plugin's without any prior configuration and load them up as the engine starts up. Full details of the plugin's that were loaded are detailed in the output of the bluedragon.log file.

Naming Conventions

Any plugin handler class you write must end in PlugIn, taking note to preserve the case. When the engine autodiscovers new plugin's it will look for classes that end in this postfix only. It can, however, be in any package.

When you are packaging your plugin classes all up into a single JAR file, you must prefix the JAR file with openbdplugin-. For example, openbdplugin-myCoolStuff.jar.

Sample PlugIn

The main entry point for your plugin is the com.bluedragon.plugin.Plugin interface to which you provide an implementation for overriding the methods as shown in the example below.

This gives you hooks to register your custom functions and tags at engine start up, and optionally, do some clean up when the engine is shutting down.

import com.bluedragon.plugin.Plugin;
import com.bluedragon.plugin.PluginManagerInterface;
import com.naryx.tagfusion.xmlConfig.xmlCFML;

public class myPlugIn implements Plugin {
	public String getPluginDescription() {
		return "My OpenBD plugin";
	}

	public String getPluginName() {
		return "MyPlugin";
	}

	public String getPluginVersion() {
		return "0.1";
	}

	public void pluginStart(PluginManagerInterface manager, xmlCFML systemParameters) {
		// the engine has started; time to register your tags and functions
	}

	public void pluginStop(PluginManagerInterface manager) {
		// the engine is stopping
	}
}

PluginManagerInterface

You interact with the engine through the PluginManagerInterface reference, which is available as a parameter passed in upon engine startup, or as a static reference using: PluginManager.getPlugInManager().

This gives you a number of helper methods that lets you easily register new functions and tags, create and call CFC's dynamically, and even register a listener so you can hook into the start and end of every request.

/**
 * This is the main plugin manager that lets you interact with the core engine.
 *
 */
public interface PluginManagerInterface {

	
/**
 * Gets a handle to a CFC based on the current session.  If the 'cfdata' is a CFC reference (given from the core engine) then
 * this reference is used.  Otherwise, the 'cfdata' is converted to a string, and a new CFC instance will be created and returned.
 * 
 * @param session
 * @param cfdata
 * @return the CFC object 
 * @throws Exception
 */
public ObjectCFC createCFC( cfSession session, cfData cfdata ) throws Exception;
	

/**
 * Creates a new CFC based on the Session object passed in.  The CFC creation goes through the same rules as if you had called
 * the "CreateObject('component', cfcName)" directly within CFML page, looking up the current directory then going to the 
 * custom-tag directory accordingly.
 * 
 * @param session
 * @param cfcName
 * @return the CFC object 
 * @throws Exception
 */
public ObjectCFC createCFC( cfSession session, String cfcName ) throws Exception;
	

/**
 * Depending on your plugin, you may not be executing in a traditional 'page' request.  Under these circumstances you require
 * a dummy session to be created that lets the rest of the tags execute.  This dummy session can be used to create CFC's using 
 * the methods in this class.  The root context is assumed to be the raw page.
 * 
 * @return a blank session
 */
public cfSession createBlankSession();
	
	
 /**
  * Registers a tag into the core engine.  If the tag already already exists then it is replaced with this one.
  * 
  * @param tagName  the name of the name
  * @param tagClass the full class path of the class to be registered
  */
  public void registerTag( String tagName, String tagClass );
  
  
  /**
   * Registers a new function with the core engine.  If the expression already exists then it is replaced with this one.
   * 
   * @param functionName 	the name of the function
   * @param functionClass the full class path of the class to be registered
   */
  public void registerFunction( String functionName, String functionClass );
  
  /**
   * Registers the enginer listener allowing you get a hook when the engine shuts down or an update is made to the admin
   * 
   * @param _new the listener
   */
  public void addEngineListener(engineListener _new);
  
  
  /**
   * Stops the given listener from receiving events
   * 
   * @param _new
   */
  public void removeEngineListener(engineListener _new);
  
  /**
   * Registers a request listener to the core engine.  This lets you receive events regarding incoming requests.
   * 
   * @param _new
   */
  public void addRequestListener(RequestListener _new);

  
  
  /**
   * Removes the given request listener
   * 
   * @param _new
   */
  public void removeRequestListener(RequestListener _new);
 
  /**
   * Starts the core engine tracking manager to collect stats on incoming requests; total hits, average hits etc
   */
  public void startRequestStats();
  
  /**
   * Stops the core engine from registering stats
   */
  public void stopRequestStats();
  
  /**
   * Request Stats collection must be enabled; -1 returned otherwise
   * 
   * @return total requests serviced 
   */
  public long getStatsTotalRequests();
  
  /**
   * Request Stats collection must be enabled; -1 returned otherwise
   * 
   * @return average time in milliseconds for each request
   */
  public long getStatsAverageRequestTimeMS();
  
  /**
   * Request Stats collection must be enabled; -1 returned otherwise
   * 
   * @return shortest request time in milliseconds
   */
  public long getStatsShortestRequestTimeMS();
  
  /**
   * Request Stats collection must be enabled; -1 returned otherwise
   * 
   * @return longest request time in milliseconds
   */
  public long getStatsLongestRequestTimeMS();
  
  /**
   * Request Stats collection must be enabled; -1 returned otherwise
   * 
   * @return number of requests currently being processed
   */
  public long getStatsActiveRequests();  
  
  
  /**
   * Prints the given log string out to the system log for the core engine
   * 
   * @param log
   */
  public void log( String log );
}