blob: 3a9e3bf072c1f8d67cf00259bcb51610e4ccbcb1 [file] [log] [blame]
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