1   /*
2    * SPDX-FileCopyrightText: none
3    * SPDX-License-Identifier: CC0-1.0
4    */
5   
6   package dev.metaschema.schemagen.xml.impl;
7   
8   import org.codehaus.stax2.XMLStreamWriter2;
9   
10  import javax.xml.stream.XMLStreamException;
11  
12  import dev.metaschema.core.datatype.IDataTypeAdapter;
13  import dev.metaschema.core.model.IDefinition;
14  import dev.metaschema.core.model.IModelElement;
15  import dev.metaschema.core.model.IValuedDefinition;
16  import dev.metaschema.schemagen.ModuleIndex;
17  import dev.metaschema.schemagen.xml.impl.schematype.IXmlSimpleType;
18  import dev.metaschema.schemagen.xml.impl.schematype.IXmlType;
19  import edu.umd.cs.findbugs.annotations.NonNull;
20  
21  /**
22   * Provides XML generation state operations needed by schema type classes.
23   * <p>
24   * This interface defines the contract for XML generation state that schema type
25   * implementations depend on. The {@code xml.impl.schematype} classes import
26   * this interface from the parent {@code xml.impl} package.
27   */
28  public interface IXmlGenerationState {
29  
30    /**
31     * Retrieves the underlying XML stream writer.
32     *
33     * @return the XML stream writer
34     */
35    @NonNull
36    XMLStreamWriter2 getXMLStreamWriter();
37  
38    /**
39     * Retrieves the default XML namespace for this schema.
40     *
41     * @return the default namespace URI
42     */
43    @NonNull
44    String getDefaultNS();
45  
46    /**
47     * Retrieves the module index for this generation state.
48     *
49     * @return the module index
50     */
51    @NonNull
52    ModuleIndex getMetaschemaIndex();
53  
54    /**
55     * Determines if a definition should be generated inline.
56     *
57     * @param definition
58     *          the definition to check
59     * @return {@code true} if the definition should be inlined, {@code false}
60     *         otherwise
61     */
62    boolean isInline(@NonNull IDefinition definition);
63  
64    /**
65     * Retrieves or creates the XML type representation for a definition.
66     *
67     * @param definition
68     *          the definition to get the XML type for
69     * @return the XML type representing the definition
70     */
71    @NonNull
72    IXmlType getXmlForDefinition(@NonNull IDefinition definition);
73  
74    /**
75     * Retrieves or creates a simple type for a data type adapter.
76     *
77     * @param dataType
78     *          the data type adapter
79     * @return the XML simple type representation
80     */
81    @NonNull
82    IXmlSimpleType getSimpleType(@NonNull IDataTypeAdapter<?> dataType);
83  
84    /**
85     * Retrieves or creates a simple type for a valued definition.
86     *
87     * @param definition
88     *          the valued definition
89     * @return the XML simple type representation
90     */
91    @NonNull
92    IXmlSimpleType getSimpleType(@NonNull IValuedDefinition definition);
93  
94    /**
95     * Writes an attribute to the current element.
96     *
97     * @param localName
98     *          the local name of the attribute
99     * @param value
100    *          the value of the attribute
101    * @throws XMLStreamException
102    *           if an error occurs while writing
103    */
104   void writeAttribute(@NonNull String localName, @NonNull String value) throws XMLStreamException;
105 
106   /**
107    * Writes a start element with the given prefix, local name, and namespace.
108    *
109    * @param prefix
110    *          the namespace prefix for the element
111    * @param localName
112    *          the local name of the element
113    * @param namespaceUri
114    *          the namespace URI for the element
115    * @throws XMLStreamException
116    *           if an error occurs while writing
117    */
118   void writeStartElement(
119       @NonNull String prefix,
120       @NonNull String localName,
121       @NonNull String namespaceUri) throws XMLStreamException;
122 
123   /**
124    * Writes a start element with the given namespace and local name.
125    *
126    * @param namespaceUri
127    *          the namespace URI for the element
128    * @param localName
129    *          the local name of the element
130    * @throws XMLStreamException
131    *           if an error occurs while writing
132    */
133   void writeStartElement(@NonNull String namespaceUri, @NonNull String localName) throws XMLStreamException;
134 
135   /**
136    * Writes an end element for the current element.
137    *
138    * @throws XMLStreamException
139    *           if an error occurs while writing
140    */
141   void writeEndElement() throws XMLStreamException;
142 
143   /**
144    * Retrieves the XML namespace for the given model element.
145    *
146    * @param modelElement
147    *          the model element to get the namespace for
148    * @return the XML namespace URI
149    */
150   @NonNull
151   String getNS(@NonNull IModelElement modelElement);
152 
153   /**
154    * Writes character content to the current element.
155    *
156    * @param text
157    *          the text content to write
158    * @throws XMLStreamException
159    *           if an error occurs while writing
160    */
161   void writeCharacters(@NonNull String text) throws XMLStreamException;
162 
163   /**
164    * Writes a namespace declaration.
165    *
166    * @param prefix
167    *          the namespace prefix
168    * @param namespaceUri
169    *          the namespace URI
170    * @throws XMLStreamException
171    *           if an error occurs while writing
172    */
173   void writeNamespace(@NonNull String prefix, @NonNull String namespaceUri) throws XMLStreamException;
174 }