1   /*
2    * SPDX-FileCopyrightText: none
3    * SPDX-License-Identifier: CC0-1.0
4    */
5   
6   package dev.metaschema.databind.codegen.typeinfo;
7   
8   import com.squareup.javapoet.FieldSpec;
9   import com.squareup.javapoet.MethodSpec;
10  import com.squareup.javapoet.TypeSpec;
11  
12  import java.util.Set;
13  
14  import dev.metaschema.core.model.IModelDefinition;
15  import edu.umd.cs.findbugs.annotations.NonNull;
16  import edu.umd.cs.findbugs.annotations.Nullable;
17  
18  public interface IPropertyTypeInfo extends ITypeInfo {
19    /**
20     * Determines if this property is unconditionally required to have a value.
21     *
22     * <p>
23     * For flags, this checks
24     * {@link dev.metaschema.core.model.IFlagInstance#isRequired()}. For model
25     * instances, this is based on minimum occurrence constraints.
26     *
27     * <p>
28     * <strong>Choice blocks:</strong> Properties inside Metaschema choice blocks
29     * always return {@code false}, regardless of their {@code min-occurs} value.
30     * The requirement is conditional on the choice branch being taken, so for
31     * null-safety purposes they are treated as optional.
32     *
33     * @return {@code true} if a value is unconditionally required, or {@code false}
34     *         otherwise
35     */
36    default boolean isRequired() {
37      return false;
38    }
39  
40    /**
41     * Determines if this property represents a collection (list or map).
42     *
43     * <p>
44     * Collections are model instances with maxOccurs greater than 1 or unbounded.
45     * Collection getters use lazy initialization and are always {@code @NonNull}.
46     *
47     * @return {@code true} if this property is a collection, or {@code false}
48     *         otherwise
49     */
50    default boolean isCollectionType() {
51      return false;
52    }
53  
54    /**
55     * Get the implementation class to use for lazy initialization of collections.
56     *
57     * <p>
58     * For list-based collections, this returns {@link java.util.LinkedList}. For
59     * map-based (keyed) collections, this returns {@link java.util.LinkedHashMap}.
60     * For non-collection properties, this returns {@code null}.
61     *
62     * <p>
63     * <strong>Contract:</strong> This method must return non-null if and only if
64     * {@link #isCollectionType()} returns {@code true}. Implementations must
65     * maintain this invariant.
66     *
67     * @return the collection implementation class, or {@code null} if not a
68     *         collection
69     * @see #isCollectionType()
70     */
71    @Nullable
72    default Class<?> getCollectionImplementationClass() {
73      return null;
74    }
75  
76    /**
77     * Generate the Java field associated with this property.
78     *
79     * @param builder
80     *          the containing class builder
81     * @return the set of definitions used by this field
82     */
83    Set<? extends IModelDefinition> build(@NonNull TypeSpec.Builder builder);
84  
85    /**
86     * Add the Javadoc for the current property's field.
87     *
88     * @param builder
89     *          the field builder to annotate with the Javadoc
90     */
91    default void buildFieldJavadoc(@NonNull FieldSpec.Builder builder) {
92      // do nothing by default
93    }
94  
95    /**
96     * Add the Javadoc for the current property's getter method.
97     *
98     * @param builder
99     *          the method builder to annotate with the Javadoc
100    */
101   default void buildGetterJavadoc(@NonNull MethodSpec.Builder builder) {
102     // do nothing by default
103   }
104 
105   /**
106    * Add the Javadoc for the current property's setter method.
107    *
108    * @param builder
109    *          the method builder to annotate with the Javadoc
110    * @param paramName
111    *          the name of the parameter
112    */
113   default void buildSetterJavadoc(@NonNull MethodSpec.Builder builder, @NonNull String paramName) {
114     // do nothing by default
115   }
116 }