Apache JSPWiki 2.9.0-incubating - Upgrading Notes ================================================= Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. The license file can be found in LICENSE. Upgrading JSPWiki to 2.9.1 -------------------------- 1. Beginning with JSPWiki-2.9.1-svn-3, generics have been added to WikiPlugin's execute() signature, which now looks like: String execute( WikiContext context, Map params ) throws PluginException; Internally this Map was always constructed and expected to be used as , except for the special _bounds parameter, which was constructed internally as an int[pos, end]. This parameter is built now as a String and has the form of "pos|end". Other than that, this change of signature shouldn't affect your custom plugins. 2. JSPWiki API The package org.apache.wiki.api aims to provide an API to give access to JSPWiki internals. Check doc/2.10-API.txt to see its packages, classes affected and to be removed when 2.10, etc. 3. RCS Support deprecated 2.9.1 will be the last JSPWiki version to support RCS as a Provider. In the next JSPWiki version, RCS support will be removed (JSPWIKI-758). Upgrading JSPWiki from 2.8.x to 2.9.0 ------------------------------------- 1. Shut down your web container 2. Backup your old configuration files: * jspwiki.properties * filters.xml * web.xml 3. Backup any modifications or customizations you may have done 4. Unzip JSPWiki.war to a new directory 5. JSPWiki's Java package names have changed from com.ecyrd.jspwiki to org.apache.wiki. In case your backed up files do contain the old package names or are, in case of binaries, built upon previous versions of JSPWiki, you will most probably have to adapt these files to the new package names. NOTE: The mandatory files jspwiki.properties and web.xml are affected, you will have to patch them! Finished patching, copy the patched files and any further of your old modified files on top of the newly installed copy of JSPWiki. 6. Replace your old installed copy with the new version. 7. Empty any temporary directories your web container might have (e.g. $CATALINA_HOME/work and $CATALINA_HOME/temp) 8. Restart your web container There is no need to empty the JSPWiki work directory or modify any preferences or settings (apart from the package name change in 5.). If you've deployed JSPWiki already as a WAR file, then you can just reinstall JSPWiki.war using the new version. Just make sure you have backed up and adapted your configuration files first! Upgrading JSPWiki from older versions to any version of 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