1   /*
2    * SPDX-FileCopyrightText: none
3    * SPDX-License-Identifier: CC0-1.0
4    */
5   
6   package dev.metaschema.schemagen.json.impl;
7   
8   import com.fasterxml.jackson.core.JsonGenerator;
9   import com.fasterxml.jackson.databind.node.JsonNodeFactory;
10  import com.fasterxml.jackson.databind.node.ObjectNode;
11  
12  import dev.metaschema.core.datatype.IDataTypeAdapter;
13  import dev.metaschema.core.model.IAssemblyDefinition;
14  import dev.metaschema.core.model.IDefinition;
15  import dev.metaschema.core.model.IFieldDefinition;
16  import dev.metaschema.core.model.IFlagDefinition;
17  import dev.metaschema.core.model.IFlagInstance;
18  import dev.metaschema.core.model.IModelInstanceAbsolute;
19  import dev.metaschema.core.model.IModule;
20  import dev.metaschema.core.model.INamedModelInstanceGrouped;
21  import dev.metaschema.core.model.IValuedDefinition;
22  import dev.metaschema.core.qname.IEnhancedQName;
23  import dev.metaschema.schemagen.IGenerationState;
24  import edu.umd.cs.findbugs.annotations.NonNull;
25  import edu.umd.cs.findbugs.annotations.Nullable;
26  
27  /**
28   * Represents the state information used during JSON schema generation.
29   * <p>
30   * This interface extends {@link IGenerationState} with JSON-specific operations
31   * for managing schema definitions, properties, and datatype mappings.
32   */
33  public interface IJsonGenerationState extends IGenerationState<JsonGenerator> {
34    /**
35     * Get the module this data is associated with.
36     *
37     * @return the module
38     */
39    @Override
40    @NonNull
41    IModule getModule();
42  
43    /**
44     * Get the JSON schema information for the provided definition.
45     * <p>
46     * This will return a cached value. The same instance will be returned if this
47     * method is called multiple times.
48     *
49     * @param definition
50     *          the flag definition to get the JSON schema information for
51     * @return the JSON schema information
52     */
53    @NonNull
54    IJsonSchemaDefinition getFlagDefinition(@NonNull IFlagDefinition definition);
55  
56    /**
57     * Get the JSON schema information for the provided definition.
58     * <p>
59     * This will return a cached value. The same instance will be returned if this
60     * method is called multiple times.
61     * <p>
62     * If a JSON key is provided, a definition that is unique for this JSON key will
63     * be returned.
64     *
65     * @param definition
66     *          the flag definition to get the JSON schema information for
67     * @param jsonKeyName
68     *          the JSON key to use with the definition or {@code null} if no JSON
69     *          key is used
70     * @return the JSON schema information
71     */
72    @NonNull
73    IJsonSchemaDefinitionField getFieldDefinition(
74        @NonNull IFieldDefinition definition,
75        @Nullable IEnhancedQName jsonKeyName);
76  
77    /**
78     * Get the JSON schema information for the provided definition.
79     * <p>
80     * This will return a cached value on subsequent calls with the same definition.
81     * The same object will be returned if this method is called multiple times.
82     * <p>
83     * If a JSON key is provided, a definition that is unique for this JSON key will
84     * be returned.
85     *
86     * @param definition
87     *          the flag definition to get the JSON schema information for
88     * @param jsonKeyName
89     *          the JSON key to use with the definition or {@code null} if no JSON
90     *          key is used
91     * @return the JSON schema information
92     */
93    @NonNull
94    IJsonSchemaDefinitionAssembly getAssemblyDefinition(
95        @NonNull IAssemblyDefinition definition,
96        @Nullable IEnhancedQName jsonKeyName);
97  
98    /**
99     * Get the JSON schema information for the provided instance.
100    * <p>
101    * This will return a cached value on subsequent calls with the same instance.
102    * The same object will be returned if this method is called multiple times.
103    *
104    * @param instance
105    *          the flag instance to get the JSON schema information for
106    * @return the JSON schema information
107    */
108   @NonNull
109   IJsonSchemaPropertyFlag getJsonSchemaPropertyFlag(@NonNull IFlagInstance instance);
110 
111   /**
112    * Get the JSON schema information for the provided instance.
113    * <p>
114    * This will return a cached value on subsequent calls with the same instance.
115    * The same object will be returned if this method is called multiple times.
116    *
117    * @param instance
118    *          the model instance to get the JSON schema information for
119    * @return the JSON schema information
120    */
121   @NonNull
122   IJsonSchemaPropertyNamed getJsonSchemaPropertyModel(@NonNull IModelInstanceAbsolute instance);
123 
124   /**
125    * Get the JSON schema information for the provided instance.
126    * <p>
127    * This will return a cached value on subsequent calls with the same instance.
128    * The same object will be returned if this method is called multiple times.
129    *
130    * @param instance
131    *          the grouped instance to get the JSON schema information for
132    * @return the JSON schema information
133    */
134   @NonNull
135   IJsonSchemaPropertyGrouped getJsonSchemaPropertyGrouped(@NonNull INamedModelInstanceGrouped instance);
136 
137   /**
138    * Generate JSON schema definitions for all used datatypes and add them to the
139    * provided definitions node.
140    *
141    * @param definitionsNode
142    *          the JSON object node to add datatype definitions to
143    */
144   void generateDataTypeDefinitions(@NonNull ObjectNode definitionsNode);
145 
146   /**
147    * Get the JSON node factory used for creating JSON schema nodes.
148    *
149    * @return the JSON node factory
150    */
151   @NonNull
152   JsonNodeFactory getJsonNodeFactory();
153 
154   /**
155    * Get the JSON schema representation for the provided datatype adapter.
156    *
157    * @param datatype
158    *          the datatype adapter to get the schema for
159    * @return the JSON schema representation for the datatype
160    */
161   @NonNull
162   IDataTypeJsonSchema getSchema(@NonNull IDataTypeAdapter<?> datatype);
163 
164   /**
165    * Get the JSON schema representation for the datatype of the provided valued
166    * definition.
167    *
168    * @param definition
169    *          the valued definition to get the datatype schema for
170    * @return the JSON schema representation for the definition's datatype
171    */
172   @NonNull
173   IDataTypeJsonSchema getDataTypeSchemaForDefinition(@NonNull IValuedDefinition definition);
174 
175   /**
176    * Convert a JSON key flag name to its string representation.
177    *
178    * @param jsonKeyFlagName
179    *          the qualified name of the JSON key flag
180    * @return the string representation of the flag name
181    */
182   @NonNull
183   default String toFlagName(@NonNull IEnhancedQName jsonKeyFlagName) {
184     return jsonKeyFlagName.toEQName();
185   }
186 
187   /**
188    * Generate a JSON schema definition name based on the provided values.
189    *
190    * @param definition
191    *          the definition to produce the name for
192    * @param jsonKeyFlagName
193    *          an optional JSON property key flag name
194    * @param suffix
195    *          an extra value used to make the name unique
196    * @return the JSON schema definition name
197    */
198   @NonNull
199   default String generateJsonSchemaDefinitionName(
200       @NonNull IDefinition definition,
201       @Nullable String jsonKeyFlagName,
202       @Nullable String suffix) {
203     return generateJsonSchemaDefinitionName(definition, jsonKeyFlagName, null, null, suffix);
204   }
205 
206   /**
207    * Generate a JSON schema definition name based on the provided values.
208    *
209    * @param definition
210    *          the definition to produce the name for
211    * @param jsonKeyFlagName
212    *          an optional JSON property key flag name
213    * @param discriminatorProperty
214    *          the JSON property name used to identify the object type
215    * @param discriminatorValue
216    *          the JSON property value used to identify the object type
217    * @param suffix
218    *          an extra value used to make the name unique
219    * @return the JSON schema definition name
220    */
221   @SuppressWarnings("PMD.UseObjectForClearerAPI")
222   @NonNull
223   String generateJsonSchemaDefinitionName(
224       @NonNull IDefinition definition,
225       @Nullable String jsonKeyFlagName,
226       @Nullable String discriminatorProperty,
227       @Nullable String discriminatorValue,
228       @Nullable String suffix);
229 }