| |
| Apache JSPWiki 2.11.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.11.0 |
| --------------------------- |
| |
| 1. New requirements |
| * Java 8 needed to run JSPWiki |
| * Servlet 3.1 / JSP 2.3 compliant JEE server (i.e., Tomcat 8.5 and onwards) |
| |
| 2. Haddock as new default template |
| * if you need to revert to the 2.10 default template, you should set the jspwiki.templateDir property to 210 on your jspwiki[-custom].properties file |
| |
| 3. Backwards API incompatible changes: https://jspwiki.apache.org/japicmp/2.11.0.M1/ |
| |
| Upgrading JSPWiki to 2.10.0 |
| --------------------------- |
| |
| 1. There have been some public API changes, detailed at: |
| http://svn.apache.org/repos/asf/jspwiki/trunk/jspwiki-war/src/main/config/doc/2.10-API.txt |
| |
| 2. RCS Support dropped, as noted on 2.9.1 upgrade notes |
| |
| |
| 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<String, String> params ) throws PluginException; |
| |
| Internally this Map was always constructed and expected to be used as <String, String>, 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: |
| <application-policy name="JSPWiki-container"> |
| <application-policy name="JSPWiki-custom"> |
| |
| -> 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 |