001package Torello.Browser;
002
003import Torello.Java.ReadOnly.ReadOnlyList;
004import Torello.Java.ReadOnly.ReadOnlyMap;
005
006import javax.json.JsonObject;
007import javax.json.stream.JsonGenerator;
008import java.util.stream.IntStream;
009
010/**
011 * Defines the singleton helper contract that supplies metadata, validation, and JSON conversion
012 * logic for a nested CDP type, event, or command-return class.
013 *
014 * <EMBED CLASS='external-html' DATA-FILE-ID=NestedHelper.top>
015 */
016@Torello.JavaDoc.Annotations.JDHeaderBackgroundImg(EmbedTagFileID="INTERNAL_USE_JDHBI")
017public interface NestedHelper<DOMAIN_NESTED extends BaseType<DOMAIN_NESTED>>
018{
019    /**
020     * Returns the descriptor singleton that describes the field layout and CDP metadata of the
021     * nested class.
022     *
023     * <EMBED CLASS='external-html' DATA-FILE-ID=NestedHelper.descriptor>
024     */
025    public NestedDescriptor<DOMAIN_NESTED> descriptor();
026
027    /**
028     * Builds the read-only {@code isPresent} list for a concrete instance by recording which fields
029     * are currently considered present.
030     *
031     * <EMBED CLASS='external-html' DATA-FILE-ID=NestedHelper.generateIsPresentList>
032     */
033    public ReadOnlyList<Boolean> generateIsPresentList(DOMAIN_NESTED THIS);
034
035    /**
036     * A method that must be implemented by a singleton helper which performs the commonly seen,
037     * standard Java {@code 'equals'} method.
038     */
039    public boolean equals(DOMAIN_NESTED THIS, Object other);
040
041    /**
042     * A method that must be implemented by a singleton helper which performs the commonly seen,
043     * standard Java {@code 'hashCode'} method.
044     */
045    public int hashCode(DOMAIN_NESTED THIS);
046
047    /**
048     * Writes a concrete nested instance into the supplied JSON generator, optionally as a named
049     * property of a larger JSON object.
050     *
051     * <EMBED CLASS='external-html' DATA-FILE-ID=NestedHelper.toJSON>
052     */
053    public void toJSON(DOMAIN_NESTED THIS, String name, JsonGenerator jGen);
054
055    /**
056     * Parses a {@link JsonObject} and creates the corresponding concrete type, event, or
057     * command-return instance.
058     */
059    public DOMAIN_NESTED fromJSON(JsonObject jo);
060
061    /**
062     * Returns the indices of any string fields whose values do not match their allowed enumerated
063     * constants.
064     *
065     * <EMBED CLASS='external-html' DATA-FILE-ID=NestedHelper.enumStrValidate>
066     *
067     * @see BaseType#enumStrValidate()
068     * @see BaseType#enumStrValidateThrow()
069     */
070    public IntStream enumStrValidate(DOMAIN_NESTED THIS);
071
072    /**
073     * Retrieves a {@link ReadOnlyMap} mapping field names to a {@link ReadOnlyList} of valid
074     * {@code String} values for each field in the map.
075     * 
076     * <EMBED CLASS='external-html' DATA-FILE-ID=BaseType.allEnumStrROLs>
077     *
078     * @see BaseType#allEnumStrROLs()
079     */
080    public ReadOnlyMap<String, ReadOnlyList<String>> allEnumStrROLs();
081}