Upgrading JSPWiki to 2.8 ------------------------ This file documents the steps necessary to upgrade JSPWiki 2.8 from 2.6. This document was written for two audiences: a. Deployers -- system administrators who want to upgrade JSPWiki , but who have not created custom JSPs, plugins, or developed against JSPWiki APIs b. Developers -- persons who have integrated their code with JSPWiki public APIs. Detailed instructions for both groups follow. UPGRADE INSTRUCTIONS FOR DEPLOYERS ---------------------------------- 1. Required Steps 2. Suggested Steps 3. Backwards Incompatibilities 1. Required Steps -------------- A. Preparing the web container -> If you are using Tomcat, delete the $CATALINA_HOME/temp and $CATALINA_HOME/work directories before upgrading. B. Replacing JSPs and web resources -> If you are upgrading from 2.4, you should replace all of the top-level JSPs (relative to the webroot) with the new ones from 2.6. You should also copy the contents of the 2.8 release's /scripts, /templates, and /images directories. -> If you are upgrading from 2.6, you should copy the contents of the /scripts, /templates and /images directories. You do not need to copy the top-level JSPs (relative to the webroot), because these are identical to those in 2.6. C. Upgrading jspwiki.properties -> You must upgrade jspwiki.properties. JSPWiki 2.8 adds several new properties to it. We recommend you use the 2.8 version of jspwiki.properties as a base, and copy your existing settings into it line-by-line. You should also add these properties, although they will default to sensible values if you do not: jspwiki.allowCreationOfEmptyPages jspwiki.userdatabase.uid jspwiki.userdatabase.lockExpiry jspwiki.userdatabase.attributes -> In jspwiki.properties, 'jspwiki.baseURL' is now a mandatory attribute, and you MUST set it to the URL that resolves to your JSPWiki webapp. Be careful if you use a localhost address (http://localhost/ or http://127.0.0.1/): this will cause some unwanted side effects if your wiki is accessed from any other computer than where the wiki is running. Example: jspwiki.baseURL = http://www.jspwiki.org/wiki/ Note that the trailing slash is REQUIRED. D. Upgrading WEB-INF resources and libraries -> If you are upgrading from JSPWiki 2.4, we recommend that you use the 2.8 version of WEB-INF/web.xml as a base, and copy any customizations into it line by line. JSPWiki 2.6 added JSON/AJAX features and JavaMail resource declarations, which you will get if you use the new web.xml file. -> Replace the old WEB-INF/jspwiki.tld and WEB-INF/lib/JSPWiki.jar with the new versions. If you are upgrading from 2.4, you must also add WEB-INF/jstl.fmt.tld. -> If you are upgrading from 2.4 or 2.6, add the following WEB-INF/lib files from the new version to your existing WEB-INF: commons-fileupload-1.2.1.jar, commons-io-1.4.jar -> If you are upgrading from 2.4, you should upgrade the following WEB-INF/lib files from the new version to your existing WEB-INF: commons-lang-2.0.jar, freshcookies-security-0.54.jar, log4j-1.2.14.jar, xmlrpc.jar (You should remove any older versions of these jars from WEB-INF/lib.) -> Remove the following files from your existing WEB-INF/lib: jug-asl-2.0.0.jar, multipartrequest.jar E. Upgrading security features -> JSPWiki now wires up its own JAAS login process, and no longer interferes with existing JAAS login stacks. The JAAS configuration options that were previously set in WEB-INF/jspwiki.jaas are now set in jspwiki.properties. You should make the following changes to jspwiki.properties in accordance with your preferred container login configuration (package names omitted for brevity): Old jspwiki.jaas values (2.4/2.6) Equivalent jspwiki.properties values -------------------------------------------------------------------------------- CookieAuthenticationLoginModule SUFFICIENT jspwiki.cookieAuthentication = true CookieAuthenticationLoginModule (omitted) jspwiki.cookieAuthentication = false CookieAssertionLoginModule SUFFICIENT jspwiki.cookieAssertions = true CookieAssertionLoginModule (omitted) jspwiki.cookieAssertions = false AnonymousLoginModule (any value) n/a (it is always turned on) For cookie authentication, you might also want to change the jspwiki.cookieAuthentication.expiry value, which defaults to 14 days. -> If you specified a third-party JAAS LoginModule for custom authentication, (for example: com.foo.login.MyLoginModule REQUIRED), you must specify this in jspwiki.properties as follows: jspwiki.loginModule.class = com.foo.login.MyLoginModule If this property is not set, JSPWiki will default (as before) to the UserDatabaseLoginModule implementation. Note that parameters passed to your custom LoginModule are now expressed in jspwiki.properties also, as key/value pairs, rather than in the JAAS config file. The parameter names and values will be loaded to a Map and passed to the LoginModule as the 'options' parameter when its initialize() method is called. The default UserDatabaseLoginModule class does not need any options. jspwiki.loginModule.options.param1 = value1 jspwiki.loginModule.options.param2 = value2 If you have developed a custom LoginModule, you should also read the DEVELOPERS section of this document for additional information. -> If you are upgrading from JSPWiki 2.4, you should consider basing your security policy (WEB-INF/jspwiki.policy) on the version supplied in 2.8, because of the fact that JAR-signing is no longer required. The overall granting structure is also more compact and readable. We recommend you use the 2.8 version of jspwiki.policy as a base, and copy your existing policy into it line-by-line. Note: If you would prefer to retain your existing policy (but upgrade it), you should remove the 'keystore jspwiki' line, the initial 'grant signedby "jspwiki"' block that grants Java permissions to JSPWiki, and all 'signedBy "jspwiki"' references. -> If you use the JDBCUserDatabase for storage of user profiles, you must add the following columns to your users table: column name type -------------------------------------------------------------------------------------------- uid varchar (100) lockExpiry timestamp attributes longvarchar (or other large text/memo field) The primary key should also be changed to the 'uid' column. The column names can be re-mapped in jspwiki.properties similar to other JDBC columns. We do not yet have an upgrade DDL script for these new columns. 2. Suggested Steps --------------- -> If you are running JBOSS, you may safely delete the following entries in your login-config.xml: -> If you are running Tomcat and have configured JAAS, you may safely remove the following system property from CATALINA_OPTS: java.security.auth.login.config -> If you are upgrading from JSPWiki 2.4, you may safely delete the Java keystore file (stored at WEB-INF/jspwki.jks). JSPWiki JARs do not need to be signed in 2.6 and higher. -> If you are upgrading from JSPWiki 2.4, you may safely delete WEB-INF/oscache.properties. 3. Backwards Incompatibilities --------------------------- -> Vote.jsp and the vote plugin are removed in 2.8. 4. Notes -------- -> The method for storing passwords in UserDatabases has changed. We now use salted SHA-1 hashes. These are transparently upgraded on the fly as users log in. -> User profiles now have a unique identifier associated with them. These are stored by the XML and JDBC UserDatabase implementations. UIDs are Strings. They are transparently added to any profiles that do not have them, on the fly, as users log in. The UID property is not widely used yet, but we expect it to be useful for security logging in future releases of JSPWiki. You can migrate your existing UserDatabase with a conversion utility available at http://www.jspwiki.org/wiki/UserDatabaseConversion UPGRADE INSTRUCTIONS FOR DEVELOPERS ----------------------------------- 1. Required Steps 2. Suggested Steps 3. Backwards Incompatibilities 1. Required Steps -------------- JSPWiki 2.8 requires at least Java 5, so make sure you have that available. 2. Suggested Steps --------------- (to be written) 3. Backwards Incompatibilities --------------------------- This section describes the changes to JSPWiki's API in version 2.8 compared to the previous release (2.6). Only public API changes are documented here. For a complete list of changes, including those to protected and private methods and fields, see doc/API Changes from 2.4. These changes are derived from the output of JarJarDiff, a component of the "DependencyFinder" package (not bundled with JSPWiki). If you have it installed, you can generate a full API diff report against any version of JSPWiki by running the Ant target "api-diff". -> The following interfaces have changed slightly, and may introduce compatibility problems if you do not fix them in your custom classes. These interfaces are NOT generally implemented by third parties, so this probably will not affect you: -> com.ecyrd.jspwiki.auth.user.UserDatabase - removed boolean isSharedWithContainer() -> com.ecyrd.jspwiki.auth.user.UserProfile - implements java.io.Serializable - added java.util.Date getLockExpiry() - added long getUid() - added boolean isLocked() - added setLockExpiry(java.util.Date) - added void setUid(long) -> com.ecyrd.jspwiki.workflow.Step - extends java.io.Serializable - method getMessageArguments() now returns Serializable[] rather than Object[] All classes in JSPWiki that implement these interfaces changed also. In particular, your Task and Decision subclasses will need to be modified (slightly) to acommodate the changes to the Step interface. -> The UserDatabase implementations (e.g., JDBCUserDatabase and XMLUserDatabase) have been enhanced to persist the additional properties for the UserProfile interface. If you have implemented your own UserDatabase class, you should examine either of these to see how these new properties should be persisted. In addition, UserDatabase no longer supports any "shared with container" methods or behaviors. -> Many of the Comparator classes now use the Java 5 idiom, rather than the old-style boolean.compare(Object). -> The following public fields were removed or made private: com.ecyrd.jspwiki.PropertyReader.PARAM_VAR_DECLARATION, PARAM_VAR_DECLARATION com.ecyrd.jspwiki.TranslatorReader.ATTACHMENT, EDIT, READ com.ecyrd.jspwiki.auth.AuthenticationManager.LOGIN_CONTAINER, LOGIN_CUSTOM com.ecyrd.jspwiki.auth.user.JDBCUserDatabase.DEFAULT_DB_HASH_PREFIX, PROP_DB_HASH_PREFIX com.ecyrd.jspwiki.filters.PingWeblogsComFilter.m_pingURL com.ecyrd.jspwiki.forms.FormInfo.m_action, m_error, m_handler, m_hide, m_name m_result, m_status, m_submission com.ecyrd.jspwiki.modules.ModuleManager.LOAD_INCOMPATIBLE_MODULES com.ecyrd.jspwiki.parser.JSPWikiMarkupParser.CHARACTER, ELEMENT, IGNORE com.ecyrd.jspwiki.plugin.BugReportHandler.DEFAULT_DATEFORMAT, DESCRIPTION, MAPPINGS, PAGE, TITLE, VERSION com.ecyrd.jspwiki.plugin.CurrentTimePlugin.DEFAULT_FORMAT com.ecyrd.jspwiki.plugin.Denounce.PARAM_LINK, PARAM_LINK, PROPERTYFILE, PROP_AGENTPATTERN, PROP_DENOUNCETEXT, PROP_HOSTPATTERN, PROP_REFERERPATTERN com.ecyrd.jspwiki.plugin.Image.PARAM_ALIGN, PARAM_ALT, PARAM_BORDER, PARAM_CAPTION, PARAM_CLASS, PARAM_HEIGHT, PARAM_LINK, PARAM_SRC, PARAM_STYLE, PARAM_TARGET, PARAM_WIDTH com.ecyrd.jspwiki.plugin.IndexPlugin.INITIALS_COLOR com.ecyrd.jspwiki.plugin.InsertPage.PARAM_CLASS, PARAM_DEFAULT, PARAM_MAXLENGTH, PARAM_PAGENAME, PARAM_SECTION, PARAM_STYLE com.ecyrd.jspwiki.plugin.PluginManager.DEFAULT_FORMS_PACKAGE com.ecyrd.jspwiki.plugin.WeblogArchivePlugin.PARAM_PAGE com.ecyrd.jspwiki.plugin.WeblogEntryPlugin.MAX_BLOG_ENTRIES, PARAM_ENTRYTEXT com.ecyrd.jspwiki.plugin.WeblogPlugin.DEFAULT_DAYS, DEFAULT_PAGEFORMAT, PARAM_ALLOWCOMMENTS, PARAM_DAYS, PARAM_ENTRYFORMAT, PARAM_MAXENTRIES, PARAM_PAGE, PARAM_STARTDATE com.ecyrd.jspwiki.search.SearchManager.PROP_USE_LUCENE com.ecyrd.jspwiki.tags.CheckLockTag.LOCKED, NOTLOCKED, OWNED com.ecyrd.jspwiki.tags.CheckVersionTag.FIRST, LATEST, NOTFIRST, NOTLATEST com.ecyrd.jspwiki.ui.admin.beans.SearchManagerBean.METHODS com.ecyrd.jspwiki.util.MailUtil.PROP_MAIL_AUTH -> The following public fields were deprecated, but not removed: -> com.ecyrd.jspwiki.auth.AuthenticationManager.PROP_SECURITY -> Workflow classes narrow their scope in several cases from Objects to Serializable, either as parameters or return types: -> com.ecyrd.jspwiki.workflow.AbstractStep.getMessageArguments() now returns ava.io.Serializable[] -> com.ecyrd.jspwiki.workflow.Fact.getValue() now returns java.io.Serializable -> com.ecyrd.jspwiki.workflow.Workflow.getMessageArguments() now returns ava.io.Serializable[] -> Class com.ecyrd.jspwiki.TranslatorReader was deprecated, and its constructor was removed so that it can no longer be instantiated. It is retained strictly for reverse compatibility. -> Class PageRenamer was moved to package com.ecyrd.jspwiki.content and completely rewritten because of licensing issues -> Class com.ecyrd.jspwiki.WikiSession method getLoginContext() was removed. -> Because of the changes under the covers to how JAAS works in 2.8, the following methods in SecurityVerifier were removed: -> isJaasConfigured() -> isJaasConfiguredAtStartup() -> jaasConfiguration() -> For security reasons, class com.ecyrd.jspwiki.auth.permissions.PermissionFactory was made final, and its contructor was made private to prevent direct instantiation. -> For security reasons, class com.ecyrd.jspwiki.auth.user.DefaultUserProfile was made final. -> Class com.ecyrd.jspwiki.rpc.RPCManager's constructor is now protected. -> Class com.ecyrd.jspwiki.plugin.BugReportHandler had it's public parameter names changed to PARAM_xxx