Preserving Customization When Upgrading JForum ********************************************** Concept V 1.0 Heri Bender / 24.10.2013 Background ********** A servlet container like Tomcat deploys a war file by unzipping it and copy the found files into the webapp folder of the application. Any previous files there having the same name are overridden. If the operator of the web application has done custom configurations in one of these files they will be lost after a new deploy of the same or a new versioned war file. Goal **** Enhancing JForum by a feature which allows to keep all customizations when upgrading to a new version. Possible Places Where Customizations Take Place In JForum ********************************************************* - property files in WEB-INF\config - logger configuration in WEB-INF\log4j.xml - database scripts in WEB-INF\config\database - user texts in WEB-INF\config\languages - templates, CSS, javascripts SystemGlobals.properties and jforum-custom.conf ----------------------------------------------- This pair of property file allows already to preserve any customization because jforum-custom.conf overrides at runtime each key contained in the deployed SystemGlobals.property. And because it is not contained in the deployed war file it kept untouched when upgrading. Operators who leave the SystemGlobals.properties untouched and manage the desired customizations only within the jforum-custom.conf will preserve these customizations. Realization Of the New Feature ****************************** Property Files -------------- The same approache as it is already applied to the pair SystemGlobals.properties/jforum-custom.conf can easily be applied to all property files. This means that each property file gets a partner file whose content overloads the content of the original file when loading the keys at runtime. This partner file is not contained in the war file and thus does not override customizations when upgrading. In order to implement a generic PropertyFileLoader which can do the overload task for an arbitrary property file it is recommended to introduce following naming convention: .properties -> _custom.properties The former is deployed by war file and contains the default, the latter is created on the fly if not yet existing, containing only a comment like: # Created by JForum # If you want to change a default value setting contained in # ${NameOfThePropFile}.properties it is recommended to place the same # key into this file and assign it to the desired new value. This # new setting will override the default value when loading # the deployed file at runtime. # This guarantees that any customization is preserved when upgrading to # a new version of JForum. Thus the system of customization is also a kind of self documented which easily can be understood by operators. Legacy Problem: The existing overload mechanisme of the SystemGlobals does not fit into the new property file naming convention. For a first step in realizing the new feature we leave this inconvenience alone and solve it by a special handling in the new PropertyFileLoader. The legacy file jforum-custom.conf can additionally be annotated as deprecated with the suggestion to better use SystemGlobals_custom.properties instead of jforum-custom.conf. In a later stage (only major release) this legacy stuff can be eliminated. But this will enforce at least some migration code and - more important - a big effort to update JForum's documentation (Web-Sites, WIKIs, etc.). Logger Configuration -------------------- JForum's configuration of the logger framework which is currently implemented has some drawbacks. Currently the Logger is configured (in a hardcoded way) by the deployed file WEB-INF\log4j.xml. This prevents operators to choose other, probably more sophisticated means of configuring the Loggers. Another drawback is that log4j at this stage already has performed its embedded self configuration algorithm (through the static call Logger.getLogger() in net.jforum.ContextListener). If log4j, e.g., finds a log4j.xml or log4j.properties file in tomcats parent classloader, or another config file which has been defined by command line param of tomcat or by a system environment variable, it is already configured using this config file. The current JForum code will then add its own configuration which might not be wanted by an operator. It would be much better if JForum relies on the automatical self configuration mechanism of log4j (or even commons-logging or the more uptodate SLF4J framework), and help out only if the self configuration has no success. New way of initialization the logger framework: - WEB-INF\log4j.xml is moved/renamed to WEB-INF\classes\log4j_template.xml - The hardcoded logger configuration code in net.jforum.ContextListener.contextInitialized() is removed. Instead a new method checkLoggingConfiguration() is called. Pseudocode: if loggerFrameworkFullyConfigured() return Copy file WEB-INF\classes\log4j_template.xml to WEB-INF\classes\log4j.xml Call DOMConfigurator.configure(appPath + "/WEB-INF/classes/log4j.xml") As side effect, this approach resolves also our intent preserving any customization done in log4j.xml because this file never gets deployed by the war file. Database Scripts ---------------- The database scripts anyhow are never used by the JForum code after the JForum has performed its initial configuration (either through the built in wizard or by preconfiguring it by a sophisticated install package). Therefore we refrain supplying a PreserveCustomization mechanism for these files. Alternatively the deploy could also contain only xy_template.sql files which - on first use - are copy/renamed to xy_custom.sql which are then used performing the DB operations (similar to the logj4 mechanism described above). User Texts ---------- Since these files are ordinary property files we can apply the same mechanism as describe above in chapter Property Files. Templates, CSS, Javascripts --------------------------- The only way CSS files or java scripts are attracted is through a declaration within a template file. Since the definition which template is to be used in each case is already implemented by a generical configurable way (templatesMapping.properties) we can use the same mechanism as describe above in chapter Property Files. A designer which wnats to customize the look and feel of JForum just has to provide a new template (and used includes) and configure the new mapping in templatesMapping_custom.properties Conclusion ********** The implementation of the new PreserveCustomization feature - is not very costly (I assume two or three man-day) - provides a valuable enhancement of JForum towards professionalisme - does not need migration tasks when upgrading existing installations - has therefore a low risk (introducing new troubles or bugs) if carefully covered by unit tests