001/*
002 * ============================================================================
003 * Copyright © 2015 Square, Inc.
004 * Copyright for the modifications © 2018-2024 by Thomas Thrien.
005 * ============================================================================
006 *
007 * Licensed under the Apache License, Version 2.0 (the "License");
008 * you may not use this file except in compliance with the License.
009 * You may obtain a copy of the License at
010 *
011 * http://www.apache.org/licenses/LICENSE-2.0
012 *
013 * Unless required by applicable law or agreed to in writing, software
014 * distributed under the License is distributed on an "AS IS" BASIS,
015 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
016 * See the License for the specific language governing permissions and
017 * limitations under the License.
018 */
019
020package org.tquadrat.foundation.javacomposer;
021
022import static org.apiguardian.api.API.Status.STABLE;
023
024import javax.annotation.processing.Filer;
025import javax.tools.JavaFileObject;
026import java.io.File;
027import java.io.IOException;
028import java.nio.file.Path;
029
030import org.apiguardian.api.API;
031import org.tquadrat.foundation.annotation.ClassVersion;
032import org.tquadrat.foundation.javacomposer.internal.JavaFileImpl;
033
034/**
035 *  The definition for a Java file containing a single top level class.
036 *
037 *  @author Square,Inc.
038 *  @modified Thomas Thrien - thomas.thrien@tquadrat.org
039 *  @version $Id: JavaFile.java 1085 2024-01-05 16:23:28Z tquadrat $
040 *  @since 0.0.5
041 *
042 *  @UMLGraph.link
043 */
044@ClassVersion( sourceVersion = "$Id: JavaFile.java 1085 2024-01-05 16:23:28Z tquadrat $" )
045@API( status = STABLE, since = "0.0.5" )
046public sealed interface JavaFile
047    permits JavaFileImpl
048{
049        /*---------------*\
050    ====** Inner Classes **====================================================
051        \*---------------*/
052    /**
053     *  The definition for a builder for an instance of an implementation of
054     *  {@link JavaFile}.
055     *
056     *  @author Square,Inc.
057     *  @modified Thomas Thrien - thomas.thrien@tquadrat.org
058     *  @version $Id: JavaFile.java 1085 2024-01-05 16:23:28Z tquadrat $
059     *  @since 0.0.5
060     *
061     *  @UMLGraph.link
062     */
063    @SuppressWarnings( "InnerClassOfInterface" )
064    @ClassVersion( sourceVersion = "$Id: JavaFile.java 1085 2024-01-05 16:23:28Z tquadrat $" )
065    @API( status = STABLE, since = "0.0.5" )
066    public static sealed interface Builder
067        permits JavaFileImpl.BuilderImpl
068    {
069            /*---------*\
070        ====** Methods **======================================================
071            \*---------*/
072        /**
073         *  Adds text to the file comment.
074         *
075         *  @param  format  The format.
076         *  @param  args    The arguments.
077         *  @return This {@code Builder} instance.
078         */
079        public Builder addFileComment( final String format, final Object... args );
080
081        /**
082         *  Adds a static import.
083         *
084         *  @param  clazz   The class.
085         *  @param  names   The names of the elements from the given class that
086         *      are to be imported.
087         *  @return This {@code Builder} instance.
088         */
089        public Builder addStaticImport( final Class<?> clazz, final String... names );
090
091        /**
092         *  Adds a static import.
093         *
094         *  @param  className   The class.
095         *  @param  names   The names of the elements from the given class that
096         *      are to be imported.
097         *  @return This {@code Builder} instance.
098         */
099        public Builder addStaticImport( final ClassName className, final String... names );
100
101        /**
102         *  Adds a static import for the given {@code enum} value.
103         *
104         *  @param  constant    The {@code enum} value.
105         *  @return This {@code Builder} instance.
106         */
107        public Builder addStaticImport( final Enum<?> constant );
108
109        /**
110         *  Builds an instance of
111         *  {@link JavaFile}
112         *  from this builder.
113         *
114         *  @return The {@code JavaFile} instance.
115         */
116        public JavaFile build();
117
118        /**
119         *  <p>{@summary Call this to omit imports for classes from the package
120         *  {@code java.lang}, such as
121         *  {@link String}
122         *  or
123         *  {@link Math}.}</p>
124         *  <p>By default, JavaComposer explicitly imports types in
125         *  {@code java.lang} to defend against naming conflicts. Suppose an
126         *  (ill-advised) class is named {@code com.example.String}. When
127         *  {@code java.lang} imports are skipped, generated code in
128         *  {@code com.example} that references {@code java.lang.String} will
129         *  get {@code com.example.String} instead.</p>
130         *
131         *  @param  flag    {@code true} means that the imports for classes
132         *      from the package {@code java.lang} are skipped, {@code false}
133         *      means that the imports are added explicitly.
134         *  @return This {@code Builder} instance.
135         */
136        public Builder skipJavaLangImports( final boolean flag );
137    }
138    //  interface Builder
139
140        /*---------*\
141    ====** Methods **==========================================================
142        \*---------*/
143    /**
144     *  {@inheritDoc}
145     */
146    @Override
147    public boolean equals( final Object o );
148
149    /**
150     *  {@inheritDoc}
151     */
152    @Override
153    public int hashCode();
154
155    /**
156     *  Returns a new builder that is initialised with this {@code JavaFile}
157     *  instance.
158     *
159     *  @return The new builder.
160     */
161    public Builder toBuilder();
162
163    /**
164     *  Creates a
165     *  {@link JavaFileObject}
166     *  from this instance of {@code JavaFile}.
167     *
168     *  @return The {@code JavaFileObject}.
169     */
170    public JavaFileObject toJavaFileObject();
171
172    /**
173     *  {@inheritDoc}
174     */
175    @Override
176    public String toString();
177
178    /**
179     *  Writes this {@code JavaFile} instance to the given
180     *  {@link Appendable}.
181     *
182     *  @param  out The output target.
183     *  @throws IOException A problem occurred when writing to the output
184     *      target.
185     */
186    public void writeTo( final Appendable out ) throws IOException;
187
188    /**
189     *  Writes this {@code JavaFile} instance to the given target folder as a
190     *  UTF-8 file, using the standard directory structure for the packages.
191     *
192     *  @param  directory   The target folder.
193     *  @throws IOException A problem occurred when writing to the output
194     *      target.
195     */
196    public void writeTo( final File directory ) throws IOException;
197
198    /**
199     *  Writes  {@code JavaFile} instance to the given
200     *  {@link Filer}
201     *  instance.
202     *
203     *  @param  filer   The target.
204     *  @throws IOException A problem occurred when writing to the output
205     *      target.
206     */
207    public void writeTo( final Filer filer ) throws IOException;
208
209    /**
210     *  Writes this {@code JavaFile} instance to the given target folder as a
211     *  UTF-8 file, using the standard directory structure for the packages.
212     *
213     *  @param  directory   The target folder.
214     *  @throws IOException A problem occurred when writing to the output
215     *      target.
216     */
217    public void writeTo( final Path directory ) throws IOException;
218}
219//  interface JavaFile
220
221/*
222 *  End of File
223 */