org.rhq.enterprise.communications.util.prefs.PreferencesUpgrade Maven / Gradle / Ivy

Go to download
/*
 * RHQ Management Platform
 * Copyright (C) 2005-2008 Red Hat, Inc.
 * All rights reserved.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation version 2 of the License.
 *
 * This program 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 General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */
package org.rhq.enterprise.communications.util.prefs;

import java.util.List;
import java.util.prefs.BackingStoreException;
import java.util.prefs.Preferences;
import mazz.i18n.Logger;
import org.rhq.enterprise.communications.i18n.CommI18NFactory;
import org.rhq.enterprise.communications.i18n.CommI18NResourceKeys;

/**
 * Performs an upgrade of a set of preferences from one configuration schema version to another (where a set of
 * preferences is tagged by what is called a "configuration schema version" or simply a "configuration version").
 *
 * Subclasses need only implement {@link #getConfigurationSchemaVersionPreference()} to indicate the name of the
 * preference key that contains the configuration schema version number for the preferences to be upgraded and to ensure
 * they override the constructor {@link PreferencesUpgrade#PreferencesUpgrade(List)} passing in the appropriate upgrade
 * steps. Calling {@link #upgrade(Preferences, int)} on instances of a subclass will use those installed
 * {@link PreferencesUpgradeStep upgrade steps} to perform the actual upgrade.
 *
 * @author John Mazzitelli
 */
public abstract class PreferencesUpgrade {
    /**
     * Logger
     */
    private static final Logger LOG = CommI18NFactory.getLogger(PreferencesUpgrade.class);

    /**
     * The list of upgrade steps that perform the version-to-version upgrades.
     */
    private List m_upgradeSteps;

    /**
     * Constructor for {@link PreferencesUpgrade} given a set of upgrade step instructions for each known, supported
     * configuration schema version. The given list must be ordered from the lowest supported configuration version to
     * the latest supported version.
     *
     * @param upgrade_steps the list of upgrade steps that are used to perform the upgrades from one version to another
     */
    public PreferencesUpgrade(List upgrade_steps) {
        m_upgradeSteps = upgrade_steps;
    }

    /**
     * This will upgrade the given set of preferences to the given configuration schema version. If the preferences are
     * at that version or higher, this method does nothing.
     *
     * @param preferences        the set of preferences to upgrade
     * @param upgrade_to_version the configuration version to upgrade the preferences to
     */
    public void upgrade(Preferences preferences, int upgrade_to_version) {
        String version_pref_name = getConfigurationSchemaVersionPreference();
        int current_version = getConfigurationSchemaVersion(preferences);

        if (current_version < upgrade_to_version) {
            for (PreferencesUpgradeStep step : m_upgradeSteps) {
                int step_version = step.getSupportedConfigurationSchemaVersion();

                if (current_version < step_version) {
                    LOG.debug(CommI18NResourceKeys.CONFIG_SCHEMA_VERSION_STEP_UPGRADING, version_pref_name,
                        current_version, step_version);

                    // upgrade to the step version and once that's done, bump up the version number
                    step.upgrade(preferences);
                    setConfigurationSchemaVersion(preferences, step_version);
                    try {
                        preferences.flush();
                    } catch (BackingStoreException e) {
                        throw new RuntimeException(e); // abort the upgrade
                    }
                    current_version = step_version;

                    LOG.debug(CommI18NResourceKeys.CONFIG_SCHEMA_VERSION_STEP_UPGRADED, version_pref_name,
                        current_version);
                }

                if (current_version >= upgrade_to_version) {
                    LOG.info(CommI18NResourceKeys.CONFIG_SCHEMA_VERSION_UPGRADED, version_pref_name, current_version);
                    break;
                }
            }

            if (current_version < upgrade_to_version) {
                LOG.error(CommI18NResourceKeys.CONFIG_SCHEMA_VERSION_NOT_UPTODATE, version_pref_name,
                    upgrade_to_version, current_version);
            }
        } else {
            LOG.debug(CommI18NResourceKeys.CONFIG_SCHEMA_VERSION_UPTODATE, version_pref_name, current_version);
        }

        return;
    }

    /**
     * Given a set of preferences, this will ask for its configuration schema version. If the version could not be
     * determined, 0 is returned.
     *
     * @param  preferences the set of preferences whose version is to be returned
     *
     * @return the version that the given set of preferences conforms to or 0 if unknown
     */
    public int getConfigurationSchemaVersion(Preferences preferences) {
        return preferences.getInt(getConfigurationSchemaVersionPreference(), 0);
    }

    /**
     * Given a set of preferences, this will set its configuration schema version to the given version number.
     *
     * @param preferences the set of preferences whose version is to be set
     * @param version     the new version of the preferences
     */
    public void setConfigurationSchemaVersion(Preferences preferences, int version) {
        preferences.putInt(getConfigurationSchemaVersionPreference(), version);
    }

    /**
     * Returns the name of the preference whose value is the configuration schema version of the entire set of
     * preferences.
     *
     * @return the name of the preference whose value is the configuration version integer
     */
    public abstract String getConfigurationSchemaVersionPreference();
}