You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jspwiki.apache.org by aj...@apache.org on 2008/07/01 01:32:56 UTC
svn commit: r672957 - /incubator/jspwiki/trunk/UPGRADING
Author: ajaquith
Date: Mon Jun 30 16:32:56 2008
New Revision: 672957
URL: http://svn.apache.org/viewvc?rev=672957&view=rev
Log:
Initial checkin.
Added:
incubator/jspwiki/trunk/UPGRADING
Added: incubator/jspwiki/trunk/UPGRADING
URL: http://svn.apache.org/viewvc/incubator/jspwiki/trunk/UPGRADING?rev=672957&view=auto
==============================================================================
--- incubator/jspwiki/trunk/UPGRADING (added)
+++ incubator/jspwiki/trunk/UPGRADING Mon Jun 30 16:32:56 2008
@@ -0,0 +1,262 @@
+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
+ --------------
+
+ -> If you are using Tomcat, delete the $CATALINA_HOME/temp and
+ $CATALINA_HOME/work directories before upgrading.
+
+ -> 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.
+
+ -> 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. However, it you retain your existing
+ jspwiki.properties file, you must add the following new properties:
+ jspwiki.defaultprefs.*
+
+ 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.
+
+ -> Replace the old WEB-INF/jspwiki.tld and JSPWiki.jar with the
+ new versions.
+
+ -> Add the following WEB-INF/ files from the new version to your existing WEB-INF:
+ commons-fileupload-1.2.1.jar, commons-io-1.4.jar
+
+ -> Remove the following files from yoru existing WEB-INF/:
+ jug-asl-2.0.0.jar, multipartrequest.jar
+
+ -> 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/jwpwiki.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 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 is 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 use the JDBCUserDatabase for storage of user profiles, you must
+ add the following columns to your users table:
+
+ column name type
+ ----------------------------
+ uid bigint (or other long integer equivalent)
+ 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
+
+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.
+
+
+UPGRADE INSTRUCTIONS FOR DEPLOYERS
+----------------------------------
+
+1. Required Steps
+2. Suggested Steps
+3. Backwards Incompatibilities
+
+1. Required Steps
+ --------------
+(to be written)
+
+
+2. Suggested Steps
+ ---------------
+(to be written)
+
+
+3. Backwards Incompatibilities
+ ---------------------------
+
+ -> 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.
+
+ -> 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.
\ No newline at end of file