/*
 * See the NOTICE file distributed with this work for additional
 * information regarding copyright ownership.
 *
 * This is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This software is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this software; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 */
package com.xpn.xwiki.store.migration;

import org.xwiki.component.annotation.Role;

/**
 * Interface for data migration. New data migration should be named like "R"+vernum+issuenumber+"DataMigration" to
 * prevent collisions.
 *
 * @version $Id$
 * @since 3.4M1
 */
@Role
public interface DataMigration
{
    /**
     * @return the data migration hint. For example "R4340XWIKI883".
     */
    String getName();

    /**
     * @return a description of what the data migration does
     */
    String getDescription();

    /**
     * @return data version which need migration. before you commit stuff which needs migration, you need write data
     *         migration with version = current release number (i.e 32000 for release 3.2).
     */
    XWikiDBVersion getVersion();

    /**
     * Run migration.
     *
     * @throws DataMigrationException if any error
     */
    void migrate() throws DataMigrationException;

    /**
     * @param startupVersion the database version when the migration process starts (before any dataMigration is
     *            applied). This is useful for data migration which need to run only when the database is in a certain
     *            version.
     * @return true if the migration should be executed or false otherwise
     */
    boolean shouldExecute(XWikiDBVersion startupVersion);
}

@@ -1048,11 +1048,26 @@
 med 
-lik
+using the%0A * %7B@cod
 e %22R
@@ -1106,33 +1106,429 @@
 ion%22
- to%0A * prevent collisions
+%7D format to prevent collisions. The format for %7B@code vernum%7D is%0A * %7B@code MMmmbbN%7D where %7B@code M%7D is the 0-leftpadded major (e.g. %226%22 is written as %2206%22), %7B@code m%7D is the%0A * 0-leftpadded minor, %7B@code b%7D is the 0-leftpadded bugfix number and %7B@code N%7D a digit to be incremented in case we%0A * have several migrations in a given release. For example, the first migration for 10.8 would have the number%0A * %7B@code 1008000%7D
 .%0A *

Improve javadoc