001/*
002 * ============================================================================
003 * Copyright © 2015 Square, Inc.
004 * Copyright for the modifications © 2018-2023 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 org.apiguardian.api.API;
025import org.tquadrat.foundation.annotation.ClassVersion;
026import org.tquadrat.foundation.javacomposer.internal.AnnotationSpecImpl;
027
028/**
029 *  The specification for a generated annotation on a declaration.
030 *
031 *  @author Square,Inc.
032 *  @modified Thomas Thrien - thomas.thrien@tquadrat.org
033 *  @version $Id: AnnotationSpec.java 1085 2024-01-05 16:23:28Z tquadrat $
034 *  @since 0.0.5
035 *
036 *  @UMLGraph.link
037 */
038@ClassVersion( sourceVersion = "$Id: AnnotationSpec.java 1085 2024-01-05 16:23:28Z tquadrat $" )
039@API( status = STABLE, since = "0.0.5" )
040public sealed interface AnnotationSpec
041    permits AnnotationSpecImpl
042{
043        /*---------------*\
044    ====** Inner Classes **====================================================
045        \*---------------*/
046    /**
047     *  The specification of a builder for an instance of an implementation of
048     *  {@link AnnotationSpec}.
049     *
050     *  @author Square,Inc.
051     *  @modified Thomas Thrien - thomas.thrien@tquadrat.org
052     *  @version $Id: AnnotationSpec.java 1085 2024-01-05 16:23:28Z tquadrat $
053     *  @since 0.0.5
054     *
055     *  @UMLGraph.link
056     */
057    @SuppressWarnings( "InnerClassOfInterface" )
058    @ClassVersion( sourceVersion = "$Id: AnnotationSpec.java 1085 2024-01-05 16:23:28Z tquadrat $" )
059    @API( status = STABLE, since = "0.0.5" )
060    public static sealed interface Builder
061        permits AnnotationSpecImpl.BuilderImpl
062    {
063            /*---------*\
064        ====** Methods **======================================================
065            \*---------*/
066        /**
067         *  Adds a building block.
068         *
069         *  @param  name    The name.
070         *  @param  format  The format for the
071         *      {@link CodeBlock}.
072         *  @param  args  The arguments for the
073         *      {@link CodeBlock}.
074         *  @return This {@code Builder} instance.
075         *
076         *  @see JavaComposer#codeBlockOf(String, Object...)
077         */
078        public Builder addMember( final CharSequence name, final String format, final Object... args );
079
080        /**
081         *  Adds a building block.
082         *
083         *  @param  name    The name.
084         *  @param  codeBlock   The
085         *      {@link CodeBlock}
086         *      representing the new member.
087         *  @return This {@code Builder} instance.
088         */
089        public Builder addMember( final CharSequence name, final CodeBlock codeBlock );
090
091        /**
092         *  Creates the {@code AnnotationSpec} instance from the added members.
093         *
094         *  @return The built instance.
095         */
096        public AnnotationSpec build();
097
098        /**
099         *  Sets a flag that forces the inline presentation of the
100         *  annotation.<br>
101         *  <br>Inline:<pre><code>@Column(name = "updated_at", nullable = false)</code></pre>
102         *
103         *  Not inline:<pre><code>  @Column(
104         *      name = "updated_at",
105         *      nullable = false
106         *  )</code></pre>
107         *
108         *  @param  flag    {@code true} for the forced inline presentation,
109         *      {@code false} for the multi-line presentation.
110         *  @return This {@code Builder} instance.
111         */
112        public Builder forceInline( boolean flag );
113    }
114    //  interface Builder
115
116        /*---------*\
117    ====** Methods **==========================================================
118        \*---------*/
119    /**
120     *  {@inheritDoc}
121     */
122    @Override
123    public boolean equals( final Object o );
124
125    /**
126     *  {@inheritDoc}
127     */
128    @Override
129    public int hashCode();
130
131    /**
132     *  Creates a new builder that is initialised with the components of this
133     *  annotation.
134     *
135     *  @return The new builder.
136     */
137    public Builder toBuilder();
138
139    /**
140     *  {@inheritDoc}
141     */
142    @Override
143    public String toString();
144}
145//  interface AnnotationSpec
146
147/*
148 *  End of File
149 */