
Apache JSPWiki 2.10.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.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