1   /*
2    * SPDX-FileCopyrightText: none
3    * SPDX-License-Identifier: CC0-1.0
4    */
5   
6   package gov.nist.secauto.metaschema.core.model;
7   
8   import edu.umd.cs.findbugs.annotations.NonNull;
9   import edu.umd.cs.findbugs.annotations.Nullable;
10  
11  /**
12   * Represents a field definition in a Metaschema module.
13   * <p>
14   * A field is a structured data object that may have flags (attributes) and a
15   * simple typed value. Field definitions specify the allowed flags, value type,
16   * and JSON serialization behavior for field instances.
17   */
18  public interface IFieldDefinition extends IModelDefinition, IValuedDefinition, IField {
19  
20    @Override
21    default boolean isInline() {
22      // not inline by default
23      return false;
24    }
25  
26    @Override
27    default IFieldInstance getInlineInstance() {
28      // not inline by default
29      return null;
30    }
31  
32    /**
33     * Retrieves the key to use as the field name for this field's value in JSON.
34     *
35     * @return a string or a FlagInstance value
36     */
37    @Nullable
38    default Object getJsonValueKey() {
39      Object retval = getJsonValueKeyFlagInstance();
40      if (retval == null) {
41        retval = getEffectiveJsonValueKeyName();
42      }
43      return retval;
44    }
45  
46    /**
47     * Check if a JSON value key flag is configured.
48     *
49     * @return {@code true} if a JSON value key flag is configured, or {@code false}
50     *         otherwise
51     */
52    default boolean hasJsonValueKeyFlagInstance() {
53      return getJsonValueKeyFlagInstance() != null;
54    }
55  
56    /**
57     * Retrieves the flag instance whose value will be used as the "value key".
58     *
59     * @return the configured flag instance, or {@code null} if a flag is not
60     *         configured as the "value key"
61     */
62    @Nullable
63    IFlagInstance getJsonValueKeyFlagInstance();
64  
65    /**
66     * Retrieves the configured static label to use as the value key, or the type
67     * specific name if a label is not configured.
68     *
69     * @return the value key label
70     */
71    @Nullable
72    String getJsonValueKeyName();
73  
74    /**
75     * Retrieves the configured static label to use as the value key, or the type
76     * specific name if a label is not configured.
77     *
78     * @return the value key label
79     */
80    @NonNull
81    default String getEffectiveJsonValueKeyName() {
82      String retval = getJsonValueKeyName();
83      if (retval == null || retval.isEmpty()) {
84        retval = getJavaTypeAdapter().getDefaultJsonValueKey();
85      }
86      return retval;
87    }
88  
89    /**
90     * Get the value of the field's value from the field item object.
91     *
92     * @param item
93     *          the field item
94     * @return the field's value or {@code null} if it has no value
95     */
96    default Object getFieldValue(@NonNull Object item) {
97      // no value by default
98      return null;
99    }
100 
101   /**
102    * A visitor callback.
103    *
104    * @param <CONTEXT>
105    *          the type of the context parameter
106    * @param <RESULT>
107    *          the type of the visitor result
108    * @param visitor
109    *          the calling visitor
110    * @param context
111    *          a parameter used to pass contextual information between visitors
112    * @return the visitor result
113    */
114   @Override
115   default <CONTEXT, RESULT> RESULT accept(@NonNull IModelElementVisitor<CONTEXT, RESULT> visitor, CONTEXT context) {
116     return visitor.visitFieldDefinition(this, context);
117   }
118 }