This week's book giveaway is in the OCAJP 8 forum. We're giving away four copies of OCA Java SE 8 Programmer I Study Guide and have Edward Finegan & Robert Liguori on-line! See this thread for details.
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 JavaServlet 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,
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,
This has the format of a standard Java property file. Values can be recovered with code like this,
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.
Then add the new property to /WebContent/WEB-INF/config/SystemGlobals.properties,
That's it. The property can be retrieved anywhere in JForum2 code using code like,
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,
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,
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,
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,
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),
Move other relevant files from net.jforum.utils.preferences These files,
These files (as I recall) do not need altering.
Set the config Put a new ConfigKeys.java file into the package, e.g.
Create the new Properties file, with the code above this would be /WebContent/WEB-INF/config/SiteSystemGlobals.properties, and populate,
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.