001/*
002 * Copyright 2023 the original author or authors.
003 * <p>
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 * <p>
008 * https://www.apache.org/licenses/LICENSE-2.0
009 * <p>
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package de.cuioss.test.valueobjects.util;
017
018import java.util.ArrayList;
019import java.util.List;
020
021import de.cuioss.test.generator.TypedGenerator;
022import de.cuioss.test.valueobjects.api.generator.PropertyGenerator;
023import de.cuioss.test.valueobjects.api.property.PropertyConfig;
024import de.cuioss.test.valueobjects.generator.TypedGeneratorRegistry;
025import de.cuioss.test.valueobjects.property.PropertyMetadata;
026
027/**
028 * Interface providing the capability for handling the
029 * {@link TypedGeneratorRegistry} programmatically. Implementors of this
030 * interface, usually the base test-classes, are supposed to take care about the
031 * runtime handling of the {@link TypedGeneratorRegistry} The runtime handling
032 * consists of three steps
033 * <ul>
034 * <li>Initialize {@link TypedGeneratorRegistry} with the basic Java-types, by
035 * calling {@link TypedGeneratorRegistry#registerBasicTypes()} usually called
036 * before all tests.</li>
037 * <li>Pick up all additional configured {@link TypedGenerator} and register
038 * them to the {@link TypedGeneratorRegistry}, see Configuration</li>
039 * <li>Tear down / clear {@link TypedGeneratorRegistry} by calling
040 * {@link TypedGeneratorRegistry#clear()} using called in the context after all
041 * tests.</li>
042 * </ul>
043 * <h2>Configuration</h2>
044 * <ul>
045 * <li>{@link PropertyMetadata}: The actual property values are generated using
046 * {@link TypedGenerator}s, see {@link PropertyConfig#generator()} . They can be
047 * tweaked in multiple ways, see
048 * {@link de.cuioss.test.valueobjects.api.generator} for details</li>
049 * <li>In case the actual test-class implements {@link TypedGenerator} itself it
050 * will implicitly registered as {@link TypedGenerator} at
051 * {@link TypedGeneratorRegistry}</li>
052 * <li>In cases you can not use the {@link PropertyGenerator} annotation, e.g.
053 * if you have instances of {@link TypedGenerator} but not types you can
054 * override {@link #registerAdditionalGenerators()}.</li>
055 * </ul>
056 *
057 * @author Oliver Wolff
058 */
059public interface GeneratorRegistry {
060
061    /**
062     * Callback method for registering additional generator, in cases you can not
063     * use the {@link PropertyGenerator} annotation, e.g. if you have instances of
064     * {@link TypedGenerator} but not types. The default implementation solely
065     * return a mutable empty {@link List}, must therefore not be considered using
066     * super
067     *
068     * @return A list of {@link TypedGenerator}s to be registered
069     */
070    @SuppressWarnings("squid:S1452") // owolff: No type information available at this level,
071                                     // therefore the wildcard is needed
072    default List<TypedGenerator<?>> registerAdditionalGenerators() {
073        return new ArrayList<>();
074    }
075
076}