001/*
002 * Copyright © 2025 CUI-OpenSource-Software (info@cuioss.de)
003 *
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 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
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.generator.domain;
017
018import de.cuioss.test.generator.TypedGenerator;
019import lombok.AccessLevel;
020import lombok.RequiredArgsConstructor;
021
022import static de.cuioss.test.generator.Generators.fixedValues;
023import static de.cuioss.test.generator.Generators.strings;
024
025/**
026 * Provides a collection of name generators for testing purposes.
027 * Includes both German and English names, separated by gender and usage context.
028 * 
029 * <p>Available generators for German names:</p>
030 * <ul>
031 *   <li>{@link #FIRSTNAMES_MALE_GERMAN} - Top 10 male names in Germany (2014)</li>
032 *   <li>{@link #FIRSTNAMES_FEMALE_GERMAN} - Top 10 female names in Germany (2014)</li>
033 *   <li>{@link #FIRSTNAMES_ANY_GERMAN} - Combined German names</li>
034 *   <li>{@link #FAMILY_NAMES_GERMAN} - Top 10 German family names</li>
035 * </ul>
036 * 
037 * <p>Available generators for English names:</p>
038 * <ul>
039 *   <li>{@link #FIRSTNAMES_MALE_ENGLISH} - Top 10 male names in US (2014)</li>
040 *   <li>{@link #FIRSTNAMES_FEMALE_ENGLISH} - Top 10 female names in US (2014)</li>
041 *   <li>{@link #FIRSTNAMES_ANY_ENGLISH} - Combined English names</li>
042 *   <li>{@link #FAMILY_NAMES_ENGLISH} - Top 10 US family names</li>
043 * </ul>
044 * 
045 * <p>Special generators:</p>
046 * <ul>
047 *   <li>{@link #UNIT_TESTS} - Technical string generator for unit testing</li>
048 * </ul>
049 * 
050 * <p><em>Example usage:</em></p>
051 * <pre>
052 * {@code TypedGenerator<String> generator = NameGenerators.FIRSTNAMES_MALE_ENGLISH.generator();}
053 * String name = generator.next(); // Returns a common English male first name
054 * </pre>
055 *
056 * @author Oliver Wolff
057 */
058@RequiredArgsConstructor(access = AccessLevel.PRIVATE)
059public enum NameGenerators {
060
061    // German
062    /** Top 10 male names in Germany (2014) */
063    FIRSTNAMES_MALE_GERMAN(fixedValues(NameLibrary.FIRSTNAMES_MALE_GERMAN)),
064
065    /** Top 10 female names in Germany (2014) */
066    FIRSTNAMES_FEMALE_GERMAN(fixedValues(NameLibrary.FIRSTNAMES_FEMALE_GERMAN)),
067
068    /** Combined set of male and female German names */
069    FIRSTNAMES_ANY_GERMAN(fixedValues(NameLibrary.FIRSTNAMES_ANY_GERMAN)),
070
071    /** Top 10 German family names from Wikipedia */
072    FAMILY_NAMES_GERMAN(fixedValues(NameLibrary.LAST_NAMES_GERMAN)),
073
074    // English
075    /** Top 10 male names in US (2014) */
076    FIRSTNAMES_MALE_ENGLISH(fixedValues(NameLibrary.FIRSTNAMES_MALE_ENGLISH)),
077
078    /** Top 10 female names in US (2014) */
079    FIRSTNAMES_FEMALE_ENGLISH(fixedValues(NameLibrary.FIRSTNAMES_FEMALE_ENGLISH)),
080
081    /** Combined set of male and female English names */
082    FIRSTNAMES_ANY_ENGLISH(fixedValues(NameLibrary.FIRSTNAMES_ANY_ENGLISH)),
083
084    /** Top 10 family names from U.S. Census Bureau */
085    FAMILY_NAMES_ENGLISH(fixedValues(NameLibrary.LAST_NAMES_ENGLISH)),
086
087    /** 
088     * Technical string generator for unit testing.
089     * Generates random strings between 1 and 256 characters.
090     */
091    UNIT_TESTS(strings(1, 256));
092
093    private final TypedGenerator<String> generator;
094
095    /**
096     * Provides access to the underlying name generator.
097     *
098     * @return A {@link TypedGenerator} that generates names according to the enum constant's specification
099     */
100    public TypedGenerator<String> generator() {
101        return generator;
102    }
103
104}