jspwiki-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ajaqu...@apache.org
Subject svn commit: r672957 - /incubator/jspwiki/trunk/UPGRADING
Date Mon, 30 Jun 2008 23:32:56 GMT
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



Mime
View raw message