• Home
• io.nosqlbench
• nb-api
• 4.15.88
• source code
• NBParams.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

io.nosqlbench.nb.api.config.params.NBParams Maven / Gradle / Ivy

package io.nosqlbench.nb.api.config.params;

import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;

/**
 * 
NB Params
 * 
NBParams is the main entry point into accessing parameters in a type-safe way.
 * It provides a reader interface which normalizes all access patterns for reading
 * configuration parameters from a variety of sources.
 * 

 * 
NBParams is not a general purpose data interface. It is a named parameter reading interface.
 * As such, all data which is presented for reading must be named at every level.
 * This means that index access such as '[3]' that you might see in other access
 * vernaculars is NOT supported.
 * 

 * 
However, multiplicity is allowed at the API level in order to support reading
 * zero or more of something when the number of provided elements is intended to
 * be configurable. In this usage, direct indexing is not intended nor allowed,
 * but order is preserved. This means that if there are any dependency relationships
 * within multiple elements at the same level, the developer can rely on them
 * being provided in the order specified by the user or underlying configuration source.
 * 

 * 
When configuration elements are named within the element definition, regardless
 * of the source, these names can be taken as naming structure. To enable this, simply
 * provide a name property on the element.
 * 

 *
 * 
Element Naming
 *
 * 
If an element contains a property named name, then the value of this property
 * is taken as the name of the element. This is useful in certain contexts when you
 * need to define a name at the source of a configuration element but expose it
 * to readers. This means that an element can be positioned with a hierarchic structure
 * simply by naming it appropriately.
 * 

 *
 * 
Element Views
 *
 * 
This API allows a developer to choose the structural model imposed on
 * configuration data. Specifically, you must choose whether or not to consume the
 * parameter data as a set of properties of one element instance, or as as set
 * of elements, each with their own properties.
 *
 * 
 *     
 *     
 *     
 * 
view
as single
view
as multiple
source is
single element
param name
ERROR
source is
multiple elements
using element name.param name
iterable
elements
 *
 * 

 *
 * This decision is made by which access method below is used. It is key that the
 * format of the provided data and the interpretation are in alignment. To ensure that
 * the consumer side of this API uses the configuration data appropriately, make
 * sure that users are well informed on valid formats. Basically, write good
 * docs and provide good examples in them.
 * 

 *
 * 
Single-Element View
 *
 * 
The one element access interface is mean to provide basic support for
 * parameterizing a single entity. The names of the parameters surfaced at the
 * top level should map directly to the names of properties as provided by the
 * underlying data source. This is irrespective of whatever other structure may
 * be contained within such properties. The key distinction is that the top level
 * names of the configuration object are available under the same top-level names
 * within the one element interface.
 * 

 * 
As data sources can provide either one or many style results, it is important
 * that each data source provide a clear explanation about how it distinguishes
 * reading a single element vs reading (possibly) multiple elements.
 * 

 * 
When explicitly reading a single element, the underlying data source must provide
 * exactly one element OR provide a series of elements of which some contain
 * name properties. Non-distinct names are allowed, although the last element
 * for a given name will be the only one visible to readers. It is an error for the
 * underlying data source in this mode to be null, empty, or otherwise provide zero
 * elements. When multiple elements are provided, It is also an error if
 * none of them has a name property. Otherwise, those with no name property are
 * silently ignored and the ones with a name property are exposed.
 * 

 * 
Element-List View
 * 
When accessing some elements, any number of elements may be provided, even zero.
 * 

 * 
Naming
 * 
A parameter can be read from a reader by simple name or by a hierarchic name.
 * hierarchic names are simply simple names concatenated by a dot '.'.
 */
public class NBParams {

    public static List some(Object source) {
        return DataSources.elements(source).stream().map(ElementImpl::new).collect(Collectors.toList());
    }

    public static Element one(Object source) {
        return one(null, source);
    }
    public static Element one(String givenName, Object source) {
        List some = DataSources.elements(givenName,source);
        if (some.size() == 0) {
            throw new RuntimeException("One param object expected, but none found in '" + source + "'");
        }
        if (some.size() > 1) {
            Map data = new LinkedHashMap<>();
            for (ElementData elementData : some) {
                String name = elementData.getName();
                if (name != null && !name.isBlank()) {
                    data.put(name, elementData);
                }
            }
            if (data.isEmpty()) {
                throw new RuntimeException("multiple elements found, but none contained a name for flattening to a map.");
            }
            return new ElementImpl(new MapBackedElement(givenName,data));
        }
        return new ElementImpl(some.get(0));
    }


}