Setting custom configuration variables in JForum

[robert crowther]

Note: most of this post refers to the bugfix version posted on Google code. The version is 2.3.4 (at the time of writing 2.3.5 is released)

To make this point a little clearer, the post will continually refer to JForum2, but this does not mean the original JForum (now on a version 2) - it means the Goole Code bugfix versions. This is important, as in the area of configuration, the bugfix version has reworked the original code.


Background
There are scenarios in JForum2 usage where custom configuration options may be desirable. For example, the standard for Java Servlet deployment is very flexible. The author found himself unable to use the same configuration on local and host servers. This is possibly the most obvious reason, but there may be others, such as custom additions to source (a hack), special staged deployment, etc.

JForum2 has unusual and extensive configuration options, which have a small and general writeup here,

https://coderanch.com/t/627864/jforum/JForum-configuration-system

This post will consider ways of getting JForum2 to take custom options.


Using server functionality - Tomcat
Other servers (Jetty/Glassfish etc.) are likely to have similar functionality - please see their documentation.

In Tomcat, server-wide variables can be added to the server file catalina.properties, like this,

co.uk.hiddenlittleborough.site.proxiedContextPath=http://localhost:8080/myapp/

This has the format of a standard Java property file. Values can be recovered with code like this,

String contextPath = System.getProperty("co.uk.hiddenlittleboroughtest.site.proxiedContextPath");

Values are server-wide, so it is good form to namespace them heavily.

The downsides of this approach is that, like global variable, these variable don't announce (by spec) their inclusion in code, and are outside the scope of the code, and don't use conventional error handling. Move the codebase, forget to change them, and code may crash with few warnings. They could be protected a little. On the other hand, they are not true globals, the action is not unlike adding parameters (but unannounced) to a class. They are also fast to set up.


Modifying JForum2 property loading
This can only be done with source compiling, not with .jar installations.

Add new keys to net.jforum.utils.preferences.ConfigKeys.java, e.g.

public final class ConfigKeys 
{
    // Custom item
	public static final String MY_CUSTOM_PROPERTY = "my.custom.property";
	public static final String LOGGED = "logged";
    ...
}

Then add the new property to /WebContent/WEB-INF/config/SystemGlobals.properties,

###################################################
# CUSTOM SETTINGS FOR THIS MODIFIED JFORUM SOURCE 
###################################################
my.custom.property="Hu905ySeW"

#####################
# GENERAL SETTINGS 
#####################

## Local
forum.link = http://localhost:8080/jforum

...

That's it. The property can be retrieved anywhere in JForum2 code using code like,

SystemGlobals.getValue(ConfigKeys.MY_CUSTOM_PROPERTY);

Downsides are that this mingles custom variables with jForum setup so may interfere with upgrading. Upsides are that all config is in one place, so easier if rolling modifications onwards, and it uses the stock JForum config (so, for example, variables are live updated)


Supplementing JForum2 property loading
This method mimics JForum2 property loading. I can be used inside source-based sites, or a supplementary code to both source and .jar based sites.

JForum2 property loading is a set of classes separated from the main body of code. This separation is not clear from source, as the classes, and particularly their initialization and usage, are scattered across the codebase.

Some snippets of code are added below. This code strips out the logging, the default property file backups, property saving, and the file listener. These are helpful to JForum2, but not essential to, say, a simple supplementary site. If the code is changed in this way, it becomes very clean, so also serves as an illustration of how the system works.

Steps
JForum2 has achieved a tidy separation of the preference code by using a Servlet listener. This loads all property files, and initializes them.

Duplicate the Servlet Listener
Copy net.jforum.ContextListener.java, and put in a new package where the new configuration code will be gathered, e.g. copy to,

com.mysite.ContextListener.java

There is now a choice. If the listening code is to be included, several extra classes will need to be copied across to this new package. If not, the code reduces to very little. Here's the stripped version,

public class ContextListener implements ServletContextListener {

	/* (non-Javadoc)
	 * @see javax.servlet.ServletContextListener#contextInitialized(javax.servlet.ServletContextEvent)
	 */
	public void contextInitialized(ServletContextEvent sce) {

		final ServletContext application = sce.getServletContext();
		final String appPath = application.getRealPath("");
		
	    //JForum registers some server-wide resources here.

        final String containerInfo = application.getServerInfo();		
		ConfigLoader.startSystemglobals(appPath);			

		final String[] info = getAppServerNameAndVersion(containerInfo);
		SystemGlobals.setValue("site.container.app", info[0]);
		SystemGlobals.setValue("site.container.version", info[1]);
        // The author included a toString()
        //System.out.println("cfg: " + ConfigLoader.configToString());     
	}

	/* (non-Javadoc)
	 * @see javax.servlet.ServletContextListener#contextDestroyed(javax.servlet.ServletContextEvent)
	 */
	public void contextDestroyed(ServletContextEvent sce) {
      //JForum unregister its drivers here.
	}

	public static String[] getAppServerNameAndVersion(String serverInfo)
	{
		final Pattern p = Pattern.compile("\\d+\\.\\d+(\\.\\d+)*");
		final Matcher matcher = p.matcher(serverInfo);
		String[] result = new String[2];
		if (matcher.find()){			
			result[0] = serverInfo.substring(0, matcher.start()-1);
			String version = matcher.group();
			result[1] = version.substring(0, version.indexOf('.'));
		}
		return result;
	}
}

This is also a good place to do other code-wide work (JForum tears down the DriverManager here, but that's left to the reader).

Add a new web.xml element
In /WebContent/WEB-INF/web.xml, insert a new element, probably below the other listeners,

<listener> <listener-class>com.mysite.ContextListener</listener-class> </listener>


Duplicate the configLoader into the new package
A class of static methods which interfaces to the system.

Copy net.jforum.ConfigLoader.java, and put in the new package. The original includes methods for loading specialised configurations, starting caches, properties file listeners, and more. Here's the stripped version,

public final class ConfigLoader 
{
	/**
	 * Start ( or restart ) <code>SystemGlobals</code>.
	 * This method loads all configuration keys set at
	 * <i>SiteSystemGlobals.properties</i>, <i><user.name>.properties</i>.
	 * 
	 * @param appPath The application root's directory
	 */
	public static void startSystemglobals(final String appPath)
	{
		// Yes, this first path is hard-coded. Here adapted for a new properties file.
		SystemGlobals.initGlobals(appPath, appPath + "/WEB-INF/config/SiteSystemGlobals.properties");
	}

	/**
	 * Returns a string representing the config keys.
	 */
	public static String configToString()
	{
		return SystemGlobals.configToString();
	}
	
	private ConfigLoader() {}
}

Duplicate SystemGlobals.java
Another class of static methods, which interfaces to the preferences.

Copy net.jforum.utils.preferences.SystemGlobals.java, and put in the new package. Here's the relevant methods for the stripped version (most of the methods are for typed setting/getting of properties. These should be retained, but are not shown here),

public final class SystemGlobals implements VariableStore
{	
	private static SystemGlobals globals = new SystemGlobals();

	//Address of the properties file
	private String defaultConfig;
	//Internal storage of properties
	private Properties defaults = new Properties();
	// Pre-expanded values cached here
	private Properties installation = new Properties();
	// Using the same class and API, stash Objects.
	private Map<String, Object> objectProperties = new HashMap<String, Object>();


	private VariableExpander expander = new VariableExpander(this, "${", "}");
	
	private SystemGlobals() {}

	/**
	 * Initialize the global configuration
	 * @param appPath The application path (normally the path to the webapp base dir
	 * @param mainConfigurationFile The file containing system defaults (when null, defaults to <appPath>/WEB-INF/config/SiteSystemGlobals.properties)
	 */
	public static void initGlobals(String appPath, String mainConfigurationFile)
	{
		globals.buildSystem(appPath, mainConfigurationFile);
	}
	
	private void buildSystem(String appPath, String mainConfigurationFile)
	{
		if (mainConfigurationFile == null) {
			throw new InvalidParameterException("defaultConfig for site could not be null");
		}

		this.defaultConfig = mainConfigurationFile;
		this.defaults.clear();

		this.defaults.put(ConfigKeys.APPLICATION_PATH, appPath);

		SystemGlobals.loadDefaults();
	
		this.installation.clear();
	}

	/**
	 * Load system defaults
	 */
	public static void loadDefaults()
	{
        System.out.println("Loading " + globals.defaultConfig + " ...");

		try
		{
			FileInputStream input = new FileInputStream(globals.defaultConfig);
			globals.defaults.load(input);
			input.close();
			globals.expander.clearCache();
		}
		catch (IOException e)
		{
			throw new ForumException(e);
		}
	}
	
    // The toString() method
	public static String configToString() {
		StringBuilder sb;
		sb = new StringBuilder();
		sb.append("SystemGlobals");
		sb.append(globals.defaults.toString());
	    return sb.toString();
    }
}

Move other relevant files from net.jforum.utils.preferences
These files,

VariableExpander.java
VariableStore.java

These files (as I recall) do not need altering.

Set the config
Put a new ConfigKeys.java file into the package, e.g.

public final class ConfigKeys 
{
	//Custom URLs
	public static final String MY_CUSTOM_PROPERTY = "my.custom.property";
	
	// Config metakeys
	// Usually points to /WEB-INF using ${application.path}.
	// Used several times in SystemGlobals.java
	public static final String APPLICATION_PATH = "application.path";
	
	private ConfigKeys() {}
}

Create the new Properties file, with the code above this would be /WebContent/WEB-INF/config/SiteSystemGlobals.properties, and populate,

#####################
# GENERAL SETTINGS 
#####################
my.custom.property=3

That's it. No more is needed, as the ServletListener triggers the structure.

The above is of no use if JForum2 is embedded in a site. If systematic upgrading of source is required, it may be helpful to have custom properties in a separate file. If a support site is built in parallel to JForum2, the above additions (however done) may contribute a great deal to staging and maintainability.