/*
* Zed Attack Proxy (ZAP) and its related class files.
*
* ZAP is an HTTP/HTTPS proxy for assessing web application security.
*
* Copyright 2015 The ZAP Development Team
*
* Licensed 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.
*/
package org.zaproxy.zap.common;
import org.apache.commons.configuration.ConversionException;
import org.apache.log4j.Logger;
import org.parosproxy.paros.common.AbstractParam;
/**
* A versioned {@code AbstractParam}.
* <p>
* A version number is saved in the configuration file to keep track of changes between releases, in case changes/updates are
* needed.
*
* @since 2.4.0
* @see AbstractParam
*/
public abstract class VersionedAbstractParam extends AbstractParam {
private final Logger logger = Logger.getLogger(this.getClass());
/**
* The key to read/write the version of the configurations, as an attribute. It should be used to compose the key for the
* configurations node.
*
* @see #getConfigVersionKey()
*/
protected static final String VERSION_ATTRIBUTE = "[@version]";
/**
* A dummy version number used at runtime to indicate that the configurations were never persisted.
*
* @see #getCurrentVersion()
* @see #ERROR_READING_CONFIG_VERSION
*/
protected static final int NO_CONFIG_VERSION = -1;
/**
* A dummy version number used at runtime to indicate that an error occurred while reading the version from the file.
*
* @see #getCurrentVersion()
* @see #NO_CONFIG_VERSION
*/
protected static final int ERROR_READING_CONFIG_VERSION = -2;
/**
* Parses the file for configurations.
* <p>
* Calls {@link #updateConfigFile()} followed by {@link #parseImpl()}.
* <p>
* <strong>Note:</strong> It shouldn't be overridden in normal conditions.
*/
@Override
protected void parse() {
updateConfigFile();
parseImpl();
}
/**
* Parses the file for configurations.
* <p>
* Called after checking and updating, if necessary, the configurations in the file.
*/
protected abstract void parseImpl();
/**
* Updates the configurations in the file, if needed.
* <p>
* The following steps are made:
* <ol>
* <li>Read the version of the configurations that are in the file, by calling {@code readConfigFileVersion()};</li>
* <li>Check if the version read is the latest version, by calling {@code isLatestConfigVersion(int)};</li>
* <li>If it's not at the latest version, update the configurations, by calling {@code updateConfigsFromVersion(int)}.</li>
* </ol>
* <p>
* <strong>Note:</strong> It shouldn't be overridden in normal conditions.
*
* @see #readConfigFileVersion()
* @see #isLatestConfigVersion(int)
* @see #updateConfigsFromVersion(int)
*/
protected void updateConfigFile() {
int configVersion = readConfigFileVersion();
if (!isLatestConfigVersion(configVersion)) {
updateConfigsFromVersion(configVersion);
}
}
/**
* Reads the version number from the configuration file, using the key returned by {@code getConfigVersionKey()}.
* <p>
* <strong>Note:</strong> It shouldn't be overridden in normal conditions.
*
* @return the version number read, or {@code NO_CONFIG_VERSION} if no version was found or
* {@code ERROR_READING_CONFIG_VERSION} if an error occurred while reading the version
* @see #NO_CONFIG_VERSION
* @see #ERROR_READING_CONFIG_VERSION
* @see #getConfigVersionKey()
*/
protected int readConfigFileVersion() {
try {
return getConfig().getInt(getConfigVersionKey(), NO_CONFIG_VERSION);
} catch (ConversionException e) {
logger.error("Error while getting the version of the configurations: " + e.getMessage(), e);
return ERROR_READING_CONFIG_VERSION;
}
}
/**
* Returns the key to read/write the version of the configurations.
* <p>
* For example:<blockquote>
*
* <pre>
* BASE_KEY + VERSION_ATTRIBUTE
* </pre>
*
* </blockquote>
*
* @return the key to read/write the version
* @see #VERSION_ATTRIBUTE
*/
protected abstract String getConfigVersionKey();
/**
* Tells whether or not the given {@code version} number is the latest version, that is, is the same version number as the
* version of the running code.
* <p>
* <strong>Note:</strong> It shouldn't be overridden in normal conditions.
*
* @param version the version that will be checked
* @return {@code true} if the given {@code version} is the latest version, {@code false} otherwise
* @see #getCurrentVersion()
* @see #updateConfigFile()
*/
protected boolean isLatestConfigVersion(int version) {
return version == getCurrentVersion();
}
/**
* Returns the current version of the configurations, that is, the version of running code.
* <p>
* The version number should be a positive integer, incremented (by one) for change(s) done between releases. It only needs
* to be incremented for configuration changes (i.e. not releases of the add-on).
*
* @return the current version of the configurations
*/
protected abstract int getCurrentVersion();
/**
* Called when the configuration version in the file is different than the version of the running code.
* <p>
* If the given {@code fileVersion} is:
* <ul>
* <li>< current version - expected case, the configurations are changed/updated to the current version by calling the
* method {@code updateConfigsImpl(int)}. After calling the method the version in the configuration file is updated to the
* current version.</li>
* <li>> current version - no changes/updates are made, the method logs a warn and returns;</li>
* <li>{@code NO_CONFIG_VERSION} - only the current version is written to the configuration file (Note: the method
* {@code updateConfigsImpl(int)} is still called);</li>
* <li>{@code ERROR_READING_CONFIG_VERSION} - no changes/updates are made, the method logs a warn and returns.</li>
* </ul>
* <p>
* <strong>Note:</strong> It shouldn't be overridden in normal conditions.
*
* @param fileVersion the version of the configurations in the file
* @see #getCurrentVersion()
* @see #NO_CONFIG_VERSION
* @see #ERROR_READING_CONFIG_VERSION
* @see #updateConfigsImpl(int)
* @see #updateConfigFile()
*/
protected void updateConfigsFromVersion(int fileVersion) {
if (isLatestConfigVersion(fileVersion)) {
return;
}
if (fileVersion == ERROR_READING_CONFIG_VERSION) {
// There's not much that can be done (quickly and easily)... log and return.
logger.warn("Configurations might not be in expected state, errors might happen...");
return;
}
if (fileVersion != NO_CONFIG_VERSION) {
if (fileVersion > getCurrentVersion()) {
logger.warn("Configurations will not be updated, file version (v" + fileVersion
+ ") is greater than the version of running code (v" + getCurrentVersion()
+ "), errors might happen...");
return;
}
logger.info("Updating configurations from v" + fileVersion + " to v" + getCurrentVersion());
}
updateConfigsImpl(fileVersion);
getConfig().setProperty(getConfigVersionKey(), Integer.valueOf(getCurrentVersion()));
}
/**
* Called when the configuration version in the file is different than the version of the running code.
* <p>
* Any required configuration changes/updates should be added to this method. For example: <blockquote>
*
* <pre>
* switch (fileVersion) {
* case NO_CONFIG_VERSION:
* // No updates/changes needed, the configurations were not previously persisted
* // and the current version is already written at the end of the previous method.
* break;
* case 1:
* // Change the type of option X
* ...
* break; // if previous changes are required for following versions the break statement
* // would be removed to achieve an incremental update
* case 2:
* // Remove option Y
* ...
* }
* </pre>
*
* </blockquote>
*
* @param fileVersion the version of the configurations in the file
*/
protected abstract void updateConfigsImpl(int fileVersion);
}