flink-core/src/main/java/org/apache/flink/configuration/ConfigOption.java

/*
 * 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.
 */

package org.apache.flink.configuration;

import org.apache.flink.annotation.PublicEvolving;

import java.util.Arrays;
import java.util.Collections;

import static org.apache.flink.util.Preconditions.checkNotNull;

/**
 * A {@code ConfigOption} describes a configuration parameter. It encapsulates
 * the configuration key, deprecated older versions of the key, and an optional
 * default value for the configuration parameter.
 *
 * <p>{@code ConfigOptions} are built via the {@link ConfigOptions} class.
 * Once created, a config option is immutable.
 *
 * @param <T> The type of value associated with the configuration option.
 */
@PublicEvolving
public class ConfigOption<T> {

	private static final String[] EMPTY = new String[0];

	// ------------------------------------------------------------------------

	/** The current key for that config option. */
	private final String key;

	/** The list of deprecated keys, in the order to be checked. */
	private final String[] deprecatedKeys;

	/** The default value for this option. */
	private final T defaultValue;

	/** The description for this option. */
	private final String description;

	// ------------------------------------------------------------------------

	/**
	 * Creates a new config option with no deprecated keys.
	 *
	 * @param key             The current key for that config option
	 * @param defaultValue    The default value for this option
	 */
	ConfigOption(String key, T defaultValue) {
		this.key = checkNotNull(key);
		this.description = "";
		this.defaultValue = defaultValue;
		this.deprecatedKeys = EMPTY;
	}

	/**
	 * Creates a new config option with deprecated keys.
	 *
	 * @param key             The current key for that config option
	 * @param defaultValue    The default value for this option
	 * @param deprecatedKeys  The list of deprecated keys, in the order to be checked
	 */
	ConfigOption(String key, String description, T defaultValue, String... deprecatedKeys) {
		this.key = checkNotNull(key);
		this.description = description;
		this.defaultValue = defaultValue;
		this.deprecatedKeys = deprecatedKeys == null || deprecatedKeys.length == 0 ? EMPTY : deprecatedKeys;
	}

	// ------------------------------------------------------------------------

	/**
	 * Creates a new config option, using this option's key and default value, and
	 * adding the given deprecated keys.
	 *
	 * <p>When obtaining a value from the configuration via {@link Configuration#getValue(ConfigOption)},
	 * the deprecated keys will be checked in the order provided to this method. The first key for which
	 * a value is found will be used - that value will be returned.
	 *
	 * @param deprecatedKeys The deprecated keys, in the order in which they should be checked.
	 * @return A new config options, with the given deprecated keys.
	 */
	public ConfigOption<T> withDeprecatedKeys(String... deprecatedKeys) {
		return new ConfigOption<>(key, description, defaultValue, deprecatedKeys);
	}

	/**
	 * Creates a new config option, using this option's key and default value, and
	 * adding the given description. The given description is used when generation the configuration documention.
	 *
	 * <p><b>NOTE:</b> You can use html to format the output of the generated cell.
	 *
	 * @param description The description for this option.
	 * @return A new config option, with given description.
	 */
	public ConfigOption<T> withDescription(final String description) {
		return new ConfigOption<>(key, description, defaultValue, deprecatedKeys);
	}

	// ------------------------------------------------------------------------

	/**
	 * Gets the configuration key.
	 * @return The configuration key
	 */
	public String key() {
		return key;
	}

	/**
	 * Checks if this option has a default value.
	 * @return True if it has a default value, false if not.
	 */
	public boolean hasDefaultValue() {
		return defaultValue != null;
	}

	/**
	 * Returns the default value, or null, if there is no default value.
	 * @return The default value, or null.
	 */
	public T defaultValue() {
		return defaultValue;
	}

	/**
	 * Checks whether this option has deprecated keys.
	 * @return True if the option has deprecated keys, false if not.
	 */
	public boolean hasDeprecatedKeys() {
		return deprecatedKeys != EMPTY;
	}

	/**
	 * Gets the deprecated keys, in the order to be checked.
	 * @return The option's deprecated keys.
	 */
	public Iterable<String> deprecatedKeys() {
		return deprecatedKeys == EMPTY ? Collections.<String>emptyList() : Arrays.asList(deprecatedKeys);
	}

	/**
	 * Returns the description of this option.
	 * @return The option's description.
	 */
	public String description() {
		return description;
	}

	// ------------------------------------------------------------------------

	@Override
	public boolean equals(Object o) {
		if (this == o) {
			return true;
		}
		else if (o != null && o.getClass() == ConfigOption.class) {
			ConfigOption<?> that = (ConfigOption<?>) o;
			return this.key.equals(that.key) &&
					Arrays.equals(this.deprecatedKeys, that.deprecatedKeys) &&
					(this.defaultValue == null ? that.defaultValue == null :
							(that.defaultValue != null && this.defaultValue.equals(that.defaultValue)));
		}
		else {
			return false;
		}
	}

	@Override
	public int hashCode() {
		return 31 * key.hashCode() +
				17 * Arrays.hashCode(deprecatedKeys) +
				(defaultValue != null ? defaultValue.hashCode() : 0);
	}

	@Override
	public String toString() {
		return String.format("Key: '%s' , default: %s (deprecated keys: %s)",
				key, defaultValue, Arrays.toString(deprecatedKeys));
	}
}