1   /*
2    * SPDX-FileCopyrightText: none
3    * SPDX-License-Identifier: CC0-1.0
4    */
5   
6   package gov.nist.secauto.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 gov.nist.secauto.metaschema.core.datatype.IDataTypeAdapter;
13  import gov.nist.secauto.metaschema.core.model.IAssemblyDefinition;
14  import gov.nist.secauto.metaschema.core.model.IDefinition;
15  import gov.nist.secauto.metaschema.core.model.IFieldDefinition;
16  import gov.nist.secauto.metaschema.core.model.IFlagDefinition;
17  import gov.nist.secauto.metaschema.core.model.IFlagInstance;
18  import gov.nist.secauto.metaschema.core.model.IModelInstanceAbsolute;
19  import gov.nist.secauto.metaschema.core.model.IModule;
20  import gov.nist.secauto.metaschema.core.model.INamedModelInstanceGrouped;
21  import gov.nist.secauto.metaschema.core.model.IValuedDefinition;
22  import gov.nist.secauto.metaschema.core.qname.IEnhancedQName;
23  import gov.nist.secauto.metaschema.schemagen.IGenerationState;
24  
25  import edu.umd.cs.findbugs.annotations.NonNull;
26  import edu.umd.cs.findbugs.annotations.Nullable;
27  
28  public interface IJsonGenerationState extends IGenerationState<JsonGenerator> {
29    /**
30     * Get the module this data is associated with.
31     *
32     * @return the module
33     */
34    @Override
35    @NonNull
36    IModule getModule();
37  
38    /**
39     * Get the JSON schema information for the provided definition.
40     * <p>
41     * This will return a cached value. The same instance will be returned if this
42     * method is called multiple times.
43     *
44     * @param definition
45     *          the flag definition to get the JSON schema information for
46     * @return the JSON schema information
47     */
48    @NonNull
49    IJsonSchemaDefinition getFlagDefinition(@NonNull IFlagDefinition definition);
50  
51    /**
52     * Get the JSON schema information for the provided definition.
53     * <p>
54     * This will return a cached value. The same instance will be returned if this
55     * method is called multiple times.
56     * <p>
57     * If a JSON key is provided, a definition that is unique for this JSON key will
58     * be returned.
59     *
60     * @param definition
61     *          the flag definition to get the JSON schema information for
62     * @param jsonKeyName
63     *          the JSON key to use with the definition or {@code null} if no JSON
64     *          key is used
65     * @return the JSON schema information
66     */
67    @NonNull
68    IJsonSchemaDefinitionField getFieldDefinition(
69        @NonNull IFieldDefinition definition,
70        @Nullable IEnhancedQName jsonKeyName);
71  
72    /**
73     * Get the JSON schema information for the provided definition.
74     * <p>
75     * This will return a cached value on subsequent calls with the same definition.
76     * The same object will be returned if this method is called multiple times.
77     * <p>
78     * If a JSON key is provided, a definition that is unique for this JSON key will
79     * be returned.
80     *
81     * @param definition
82     *          the flag definition to get the JSON schema information for
83     * @param jsonKeyName
84     *          the JSON key to use with the definition or {@code null} if no JSON
85     *          key is used
86     * @return the JSON schema information
87     */
88    @NonNull
89    IJsonSchemaDefinitionAssembly getAssemblyDefinition(
90        @NonNull IAssemblyDefinition definition,
91        @Nullable IEnhancedQName jsonKeyName);
92  
93    /**
94     * Get the JSON schema information for the provided instance.
95     * <p>
96     * This will return a cached value on subsequent calls with the same instance.
97     * The same object will be returned if this method is called multiple times.
98     *
99     * @param instance
100    *          the flag instance to get the JSON schema information for
101    * @return the JSON schema information
102    */
103   @NonNull
104   IJsonSchemaPropertyFlag getJsonSchemaPropertyFlag(@NonNull IFlagInstance instance);
105 
106   /**
107    * Get the JSON schema information for the provided instance.
108    * <p>
109    * This will return a cached value on subsequent calls with the same instance.
110    * The same object will be returned if this method is called multiple times.
111    *
112    * @param instance
113    *          the model instance to get the JSON schema information for
114    * @return the JSON schema information
115    */
116   @NonNull
117   IJsonSchemaPropertyNamed getJsonSchemaPropertyModel(@NonNull IModelInstanceAbsolute instance);
118 
119   /**
120    * Get the JSON schema information for the provided instance.
121    * <p>
122    * This will return a cached value on subsequent calls with the same instance.
123    * The same object will be returned if this method is called multiple times.
124    *
125    * @param instance
126    *          the grouped instance to get the JSON schema information for
127    * @return the JSON schema information
128    */
129   @NonNull
130   IJsonSchemaPropertyGrouped getJsonSchemaPropertyGrouped(@NonNull INamedModelInstanceGrouped instance);
131 
132   void generateDataTypeDefinitions(@NonNull ObjectNode definitionsNode);
133 
134   @NonNull
135   JsonNodeFactory getJsonNodeFactory();
136 
137   @NonNull
138   IDataTypeJsonSchema getSchema(@NonNull IDataTypeAdapter<?> datatype);
139 
140   @NonNull
141   IDataTypeJsonSchema getDataTypeSchemaForDefinition(@NonNull IValuedDefinition definition);
142 
143   @NonNull
144   default String toFlagName(@NonNull IEnhancedQName jsonKeyFlagName) {
145     return jsonKeyFlagName.toEQName();
146   }
147 
148   /**
149    * Generate a JSON schema definition name based on the provided values.
150    *
151    * @param definition
152    *          the definition to produce the name for
153    * @param jsonKeyFlagName
154    *          an optional JSON property key flag name
155    * @param suffix
156    *          an extra value used to make the name unique
157    * @return the JSON schema definition name
158    */
159   @NonNull
160   default String generateJsonSchemaDefinitionName(
161       @NonNull IDefinition definition,
162       @Nullable String jsonKeyFlagName,
163       @Nullable String suffix) {
164     return generateJsonSchemaDefinitionName(definition, jsonKeyFlagName, null, null, suffix);
165   }
166 
167   /**
168    * Generate a JSON schema definition name based on the provided values.
169    *
170    * @param definition
171    *          the definition to produce the name for
172    * @param jsonKeyFlagName
173    *          an optional JSON property key flag name
174    * @param discriminatorProperty
175    *          the JSON property name used to identify the object type
176    * @param discriminatorValue
177    *          the JSON property value used to identify the object type
178    * @param suffix
179    *          an extra value used to make the name unique
180    * @return the JSON schema definition name
181    */
182   @SuppressWarnings("PMD.UseObjectForClearerAPI")
183   @NonNull
184   String generateJsonSchemaDefinitionName(
185       @NonNull IDefinition definition,
186       @Nullable String jsonKeyFlagName,
187       @Nullable String discriminatorProperty,
188       @Nullable String discriminatorValue,
189       @Nullable String suffix);
190 }