io.inverno.mod.configuration.DefaultingStrategy Maven / Gradle / Ivy
Show all versions of inverno-configuration Show documentation
/*
* Copyright 2022 Jeremy KUHN
*
* 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 io.inverno.mod.configuration;
import io.inverno.mod.configuration.internal.LookupDefaultingStrategy;
import io.inverno.mod.configuration.internal.NoOpDefaultingStrategy;
import io.inverno.mod.configuration.internal.WildcardDefaultingStrategy;
import java.util.List;
/**
*
* A defaulting strategy is used in a {@link DefaultableConfigurationSource} to implement defaulting configuration mechanism.
*
*
*
* A defaulting strategy derives a list of queries from an original query whose order specifies result priorities. The source shall retain the first non-empty result from that list or the empty result
* if no result is returned for any of the queries returned by the strategy.
*
*
* @author Jeremy Kuhn
* @since 1.5
*/
public interface DefaultingStrategy {
/**
*
* Returns a NoOp defaulting strategy.
*
*
*
* The NoOp defaulting strategy does not support defaulting and simply returns the original query.
*
*
* @return a NoOp defaulting strategy
*/
static DefaultingStrategy noOp() {
return NoOpDefaultingStrategy.INSTANCE;
}
/**
*
* Returns a lookup defaulting strategy.
*
*
*
* A lookup defaulting strategy support defaulting by prioritizing parameters from left to right: the best matching property is the one matching the most continuous parameters from left to right.
*
*
*
* If we consider query key {@code property[p1=v1,...pn=vn]}, it supersedes key {@code property[p1=v1,...pn-1=vn-1]} which supersedes key {@code property[p1=v1,...pn-2=vn-2]}... which supersedes key
* {@code property[]}. It basically tells the source to lookup by successively removing the rightmost parameter if no exact result exists for a particular query.
*
*
*
* As a result, an original query with {@code n} parameters results in {@code n+1} potential queries to execute for the source. The query result is then the first non-empty result or the empty result.
*
*
*
* The order into which parameters are defined in the original query is then significant: {@code property[p1=v1,p2=v2] != property[p2=v2,p1=v1]}.
*
*
*
* When listing properties, this strategy includes the parent properties which are obtained by successively removing the rightmost parameter from the original query.
*
*
* @return a lookup defaulting strategy
*/
static DefaultingStrategy lookup() {
return LookupDefaultingStrategy.INSTANCE;
}
/**
*
* Returns a wildcard defaulting strategy.
*
*
*
* If we consider query key {@code property[p1=v1,...pn=vn]}, the most precise result is the one defining parameters {@code [p1=v1,...pn=vn]}, it supersedes results that define {@code n-1} query
* parameters, which supersedes results that define {@code n-2} query parameters... which supersedes results that define no query parameters. Conflicts may arise when a source defines a property
* with different set of query parameters with the same cardinality (e.g. when it defines properties {@code property[p1=v1,p2=v2]} and {@code property[p1=v1,p3=v3]}). In such situation, priority
* is always given to parameters from left to right (therefore {@code property[p1=v1,p2=v2]} supersedes {@code property[p1=v1,p3=v3]})
*
*
*
* An original query with {@code n} parameters then results in {@code 2^n} potential queries to execute for the source (the sum of the k-combinations from 0 to n). The query result is the first
* non-empty result or the empty result.
*
*
*
* The order into which parameters are defined in the original query is then significant: {@code property[p1=v1,p2=v2] != property[p2=v2,p1=v1]}.
*
*
*
* When listing properties, this strategy includes all properties that could match the query parameters.
*
*
* @return a wildcard defaulting strategy
*/
static DefaultingStrategy wildcard() {
return WildcardDefaultingStrategy.INSTANCE;
}
/**
*
* Derives a list of queries from the specified original query.
*
*
*
* The order of the returned queries must determine the result priorities. The source must consider queries in that order to determine the best matching result for the original query.
*
*
* @param queryKey the original query
*
* @return a list of configuration queries
*/
List getDefaultingKeys(ConfigurationKey queryKey);
/**
*
* Derives a list of keys that defines the set of properties that must be retained in a list query.
*
*
*
* A source shall use these keys to determine whether a given property must be included in the results of a list query.
*
*
*
* Note that in case of a {@link ListConfigurationQuery#executeAll()} operation, the source shall only include properties with extra parameters that only match the first key so as to exclude
* properties inconsistent with the orignal query.
*
*
* @param queryKey the original query
*
* @return a list of configuration keys
*/
List getListDefaultingKeys(ConfigurationKey queryKey);
}