001/*
002 * ============================================================================
003 *  Copyright © 2002-2024 by Thomas Thrien.
004 *  All Rights Reserved.
005 * ============================================================================
006 *  Licensed to the public under the agreements of the GNU Lesser General Public
007 *  License, version 3.0 (the "License"). You may obtain a copy of the License at
008 *
009 *       http://www.gnu.org/licenses/lgpl.html
010 *
011 *  Unless required by applicable law or agreed to in writing, software
012 *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
013 *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
014 *  License for the specific language governing permissions and limitations
015 *  under the License.
016 */
017
018package org.tquadrat.foundation.config.ap.impl;
019
020import static org.apiguardian.api.API.Status.MAINTAINED;
021import static org.apiguardian.api.API.Status.STABLE;
022import static org.tquadrat.foundation.config.ap.ConfigAnnotationProcessor.METHODNAME_ConfigBeanSpec_AddListener;
023import static org.tquadrat.foundation.config.ap.ConfigAnnotationProcessor.METHODNAME_ConfigBeanSpec_GetResourceBundle;
024import static org.tquadrat.foundation.config.ap.ConfigAnnotationProcessor.METHODNAME_ConfigBeanSpec_InitData;
025
026import org.apiguardian.api.API;
027import org.tquadrat.foundation.annotation.ClassVersion;
028import org.tquadrat.foundation.config.ap.CodeGenerationConfiguration;
029import org.tquadrat.foundation.javacomposer.FieldSpec;
030import org.tquadrat.foundation.javacomposer.JavaComposer;
031import org.tquadrat.foundation.javacomposer.MethodSpec;
032
033/**
034 *  An API to the internals of the code builders.
035 *
036 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
037 *  @version $Id: CodeBuilder.java 1085 2024-01-05 16:23:28Z tquadrat $
038 *  @UMLGraph.link
039 *  @since 0.1.0
040 */
041@ClassVersion( sourceVersion = "$Id: CodeBuilder.java 1085 2024-01-05 16:23:28Z tquadrat $" )
042@API( status = STABLE, since = "0.1.0" )
043public interface CodeBuilder
044{
045        /*---------------*\
046    ====** Inner Classes **====================================================
047        \*---------------*/
048    /**
049     *  The standard fields.
050     *
051     *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
052     *  @version $Id: CodeBuilder.java 1085 2024-01-05 16:23:28Z tquadrat $
053     *  @since 0.2.0
054     *
055     *  @UMLGraph.link
056     */
057    @ClassVersion( sourceVersion = "$Id: CodeBuilder.java 1085 2024-01-05 16:23:28Z tquadrat $" )
058    @API( status = MAINTAINED, since = "0.2.0" )
059    public enum StandardField
060    {
061            /*------------------*\
062        ====** Enum Declaration **=============================================
063            \*------------------*/
064        /**
065         *  The registry for the preferences accessors.
066         */
067        @API( status = MAINTAINED, since = "0.0.1" )
068        STD_FIELD_Accessors( "m_AccessorsRegistry" ),
069
070        /**
071         *  The CLI definitions.
072         */
073        @API( status = MAINTAINED, since = "0.0.1" )
074        STD_FIELD_CLIDefinitions( "m_CLIDefinitions" ),
075
076        /**
077         *  The CLI error.
078         */
079        @API( status = MAINTAINED, since = "0.0.1" )
080        STD_FIELD_CLIError( "m_CLIErrorMessage" ),
081
082        /**
083         *  The INIFile instance.
084         */
085        @API( status = MAINTAINED, since = "0.1.0" )
086        STD_FIELD_INIFile( "m_INIFile" ),
087
088        /**
089         *  The file name for the INIFile.
090         */
091        @API( status = MAINTAINED, since = "0.1.0" )
092        STD_FIELD_INIFileName( "m_INIFilePath" ),
093
094        /**
095         *  The listener support.
096         */
097        @API( status = MAINTAINED, since = "0.0.1" )
098        STD_FIELD_ListenerSupport( "m_ListenerSupport" ),
099
100        /**
101         *  The listener for preference changes.
102         */
103        @API( status = MAINTAINED, since = "0.1.0" )
104        STD_FIELD_PreferenceChangeListener( "m_PreferenceChangeListener" ),
105
106        /**
107         *  The preferences root.
108         */
109        @API( status = MAINTAINED, since = "0.0.1" )
110        STD_FIELD_PreferencesRoot( "m_PreferencesRoot" ),
111
112        /**
113         *  The read lock.
114         */
115        @API( status = MAINTAINED, since = "0.0.1" )
116        STD_FIELD_ReadLock( "m_ReadLock" ),
117
118        /**
119         *  The registry for the properties when the Map interface needs to be
120         *  implemented.
121         */
122        @API( status = MAINTAINED, since = "0.0.1" )
123        STD_FIELD_Registry( "m_ShadowMap" ),
124
125        /**
126         *  The
127         *  {@link java.util.Locale}
128         *  for the current resource bundle.
129         */
130        @API( status = MAINTAINED, since = "0.0.2" )
131        STD_FIELD_ResourceLocale( "m_CurrentResourceBundleLocale" ),
132
133        /**
134         *  The current
135         *  {@link java.util.ResourceBundle}.
136         */
137        @API( status = MAINTAINED, since = "0.0.2" )
138        STD_FIELD_ResourceBundle( "m_ResourceBundle" ),
139
140        /**
141         *  The user preferences.
142         */
143        @API( status = MAINTAINED, since = "0.0.1" )
144        STD_FIELD_UserPreferences( "m_UserPreferences" ),
145
146        /**
147         *  The "write" lock.
148         */
149        @API( status = MAINTAINED, since = "0.0.1" )
150        STD_FIELD_WriteLock( "m_WriteLock" );
151
152            /*------------*\
153        ====** Attributes **===================================================
154            \*------------*/
155        /**
156         *  The field name.
157         */
158        private final String m_FieldName;
159
160            /*--------------*\
161        ====** Constructors **=================================================
162            \*--------------*/
163        /**
164         *  Creates a new {@code StandardField} instance.
165         *
166         *  @param  fieldName   The field name.
167         */
168        private StandardField( final String fieldName )
169        {
170            m_FieldName = fieldName;
171        }   //  StandardField()
172
173            /*---------*\
174        ====** Methods **======================================================
175            \*---------*/
176        /**
177         *  Returns the field name for this standard field, as it is used in the
178         *  generated code.
179         *
180         *  @return The field name.
181         */
182        @Override
183        public final String toString() { return m_FieldName; }
184    }
185    //  enum StandardField
186
187    /**
188     *  The standard methods.
189     *
190     *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
191     *  @version $Id: CodeBuilder.java 1085 2024-01-05 16:23:28Z tquadrat $
192     *  @since 0.2.0
193     *
194     *  @UMLGraph.link
195     */
196    @ClassVersion( sourceVersion = "$Id: CodeBuilder.java 1085 2024-01-05 16:23:28Z tquadrat $" )
197    @API( status = MAINTAINED, since = "0.2.0" )
198    public enum StandardMethod
199    {
200            /*------------------*\
201        ====** Enum Declaration **=============================================
202            \*------------------*/
203        /**
204         *  The method to add listeners.
205         */
206        @API( status = MAINTAINED, since = "0.2.0" )
207        STD_METHOD_AddListener( METHODNAME_ConfigBeanSpec_AddListener ),
208
209        /**
210         *  The method that returns the message prefix.
211         */
212        @API( status = MAINTAINED, since = "0.2.0" )
213        STD_METHOD_GetMessagePrefix( "getMessagePrefix" ),
214
215        /**
216         *  The method that returns the ressource bundle for the messages.
217         */
218        @API( status = MAINTAINED, since = "0.2.0" )
219        STD_METHOD_GetRessourceBundle( METHODNAME_ConfigBeanSpec_GetResourceBundle ),
220
221        /**
222         *  The method that provides initialisation data.
223         */
224        @API( status = MAINTAINED, since = "0.2.0" )
225        STD_METHOD_InitData( METHODNAME_ConfigBeanSpec_InitData ),
226
227        /**
228         *  The method to remove listeners.
229         */
230        @API( status = MAINTAINED, since = "0.2.0" )
231        STD_METHOD_RemoveListener( "removeListener" ),
232
233        /**
234         *  The
235         *  {@link Object#toString()}
236         *  method.
237         */
238        @API( status = MAINTAINED, since = "0.2.0" )
239        STD_METHOD_ToString( "toString" );
240
241            /*------------*\
242        ====** Attributes **===================================================
243            \*------------*/
244        /**
245         *  The method name.
246         */
247        private final String m_MethodName;
248
249            /*--------------*\
250        ====** Constructors **=================================================
251            \*--------------*/
252        /**
253         *  Creates a new {@code StandardMethod} instance.
254         *
255         *  @param  methodName  The method name.
256         */
257        private StandardMethod( final String methodName )
258        {
259            m_MethodName = methodName;
260        }   //  StandardMethod()
261
262            /*---------*\
263        ====** Methods **======================================================
264            \*---------*/
265        /**
266         *  Returns the method name for this standard method, as it is used in the
267         *  generated code.
268         *
269         *  @return The method name.
270         */
271        @Override
272        public final String toString() { return m_MethodName; }
273    }
274    //  enum StandardMethod
275
276        /*---------*\
277    ====** Methods **==========================================================
278        \*---------*/
279    /**
280     *  Generates the relevant code.
281     */
282    public void build();
283
284    /**
285     *  Provides access to the composer.
286     *
287     *  @return The composer.
288     */
289    public JavaComposer getComposer();
290
291    /**
292     *  Provides access to the code builder configuration.
293     *
294     *  @return The configuration.
295     */
296    public CodeGenerationConfiguration getConfiguration();
297
298    /**
299     *  Returns the specification for a standard field.
300     *
301     *  @param  reference   The identifier for the standard field.
302     *  @return The field.
303     */
304    public FieldSpec getField( final StandardField reference );
305
306    /**
307     *  Returns the specification for a standard method.
308     *
309     *  @param  reference   The identifier for the standard method.
310     *  @return The method.
311     */
312    public MethodSpec getMethod( final StandardMethod reference );
313}
314//  interface CodeBuilder
315
316/*
317 *  End of File
318 */