1 /*
2 * Copyright 2006-2026 the original author or authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * https://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.mybatis.generator.api;
17
18 import java.util.Properties;
19 import java.util.Set;
20
21 import org.mybatis.generator.api.dom.java.CompilationUnit;
22 import org.mybatis.generator.api.dom.java.Field;
23 import org.mybatis.generator.api.dom.java.FullyQualifiedJavaType;
24 import org.mybatis.generator.api.dom.java.InnerClass;
25 import org.mybatis.generator.api.dom.java.InnerEnum;
26 import org.mybatis.generator.api.dom.java.InnerRecord;
27 import org.mybatis.generator.api.dom.java.Method;
28 import org.mybatis.generator.api.dom.java.TopLevelClass;
29 import org.mybatis.generator.api.dom.kotlin.KotlinFile;
30 import org.mybatis.generator.api.dom.kotlin.KotlinFunction;
31 import org.mybatis.generator.api.dom.kotlin.KotlinProperty;
32 import org.mybatis.generator.api.dom.kotlin.KotlinType;
33 import org.mybatis.generator.api.dom.xml.XmlElement;
34
35 /**
36 * Implementations of this interface are used to generate comments for the
37 * various artifacts.
38 *
39 * @author Jeff Butler
40 */
41 public interface CommentGenerator {
42
43 /**
44 * Adds properties for this instance from any properties configured in the
45 * CommentGenerator configuration.
46 *
47 * <p>This method will be called before any of the other methods.
48 *
49 * @param properties
50 * All properties from the configuration
51 */
52 void addConfigurationProperties(Properties properties);
53
54 /**
55 * Adds a comment for a model class. The Java code merger should
56 * be notified not to delete the entire class in case any manual
57 * changes have been made. So this method will always use the
58 * "do not delete" annotation.
59 *
60 * <p>Because of difficulties with the Java file merger, the default implementation
61 * of this method should NOT add comments. Comments should only be added if
62 * specifically requested by the user (for example, by enabling table remark comments).
63 *
64 * @param topLevelClass
65 * the top level class
66 * @param introspectedTable
67 * the introspected table
68 */
69 default void addModelClassComment(TopLevelClass topLevelClass, IntrospectedTable introspectedTable) {}
70
71 /**
72 * Adds a comment for a model class.
73 *
74 * @param modelClass
75 * the generated KotlinType for the model
76 * @param introspectedTable
77 * the introspected table
78 */
79 default void addModelClassComment(KotlinType modelClass, IntrospectedTable introspectedTable) {}
80
81 /**
82 * This method is called to add a file level comment to a generated java file. This method
83 * could be used to add a general file comment (such as a copyright notice). However, note
84 * that the Java file merge function may not preserve this comment. If you run
85 * the generator repeatedly, you will only retain the comment from the initial run.
86 *
87 * <p>The default implementation does nothing.
88 *
89 * @param compilationUnit
90 * the compilation unit
91 */
92 default void addJavaFileComment(CompilationUnit compilationUnit) {}
93
94 /**
95 * This method should add a suitable comment as a child element of the specified xmlElement to warn users that the
96 * element was generated and is subject to regeneration.
97 *
98 * @param xmlElement
99 * the xml element
100 */
101 default void addComment(XmlElement xmlElement) {}
102
103 /**
104 * This method is called to add a comment as the first child of the root element. This method
105 * could be used to add a general file comment (such as a copyright notice). However, note
106 * that the XML file merge function does not deal with this comment. If you run the generator
107 * repeatedly, you will only retain the comment from the initial run.
108 *
109 * <p>The default implementation does nothing.
110 *
111 * @param rootElement
112 * the root element
113 */
114 default void addRootComment(XmlElement rootElement) {}
115
116 /**
117 * Adds a @Generated annotation to a method.
118 *
119 * @param method
120 * the method
121 * @param introspectedTable
122 * the introspected table
123 * @param imports
124 * the comment generator may add a required imported type to this list
125 *
126 * @since 1.3.6
127 */
128 default void addGeneralMethodAnnotation(Method method, IntrospectedTable introspectedTable,
129 Set<FullyQualifiedJavaType> imports) {}
130
131 /**
132 * Adds a @Generated annotation to a method.
133 *
134 * @param method
135 * the method
136 * @param introspectedTable
137 * the introspected table
138 * @param introspectedColumn
139 * the introspected column
140 * @param imports
141 * the comment generator may add a required imported type to this list
142 *
143 * @since 1.3.6
144 */
145 default void addGeneralMethodAnnotation(Method method, IntrospectedTable introspectedTable,
146 IntrospectedColumn introspectedColumn, Set<FullyQualifiedJavaType> imports) {}
147
148 /**
149 * Adds a @Generated annotation to a field.
150 *
151 * @param field
152 * the field
153 * @param introspectedTable
154 * the introspected table
155 * @param imports
156 * the comment generator may add a required imported type to this list
157 *
158 * @since 1.3.6
159 */
160 default void addFieldAnnotation(Field field, IntrospectedTable introspectedTable,
161 Set<FullyQualifiedJavaType> imports) {}
162
163 /**
164 * Adds a @Generated annotation to a field.
165 *
166 * @param field
167 * the field
168 * @param introspectedTable
169 * the introspected table
170 * @param introspectedColumn
171 * the introspected column
172 * @param imports
173 * the comment generator may add a required imported type to this list
174 *
175 * @since 1.3.6
176 */
177 default void addFieldAnnotation(Field field, IntrospectedTable introspectedTable,
178 IntrospectedColumn introspectedColumn, Set<FullyQualifiedJavaType> imports) {}
179
180 /**
181 * Adds a @Generated annotation to a class.
182 *
183 * @param innerClass
184 * the class
185 * @param introspectedTable
186 * the introspected table
187 * @param imports
188 * the comment generator may add a required imported type to this list
189 *
190 * @since 1.3.6
191 */
192 default void addClassAnnotation(InnerClass innerClass, IntrospectedTable introspectedTable,
193 Set<FullyQualifiedJavaType> imports) {}
194
195 /**
196 * Adds a @Generated annotation to a class and marks it as do not delete. This means that the class should survive
197 * a Java merge operation even if a newly generated method matches it (the new method will be discarded).
198 *
199 * @param innerClass the class
200 * @param introspectedTable the introspected table
201 * @param imports
202 * the comment generator may add a required imported type to this list
203 */
204 default void addClassAnnotationAndMarkAsDoNotDelete(InnerClass innerClass, IntrospectedTable introspectedTable,
205 Set<FullyQualifiedJavaType> imports) { }
206
207 /**
208 * Adds a @Generated annotation to a record.
209 *
210 * @param innerRecord
211 * the record
212 * @param introspectedTable
213 * the introspected table
214 * @param imports
215 * the comment generator may add a required imported type to this list
216 *
217 * @since 2.0.0
218 */
219 default void addRecordAnnotation(InnerRecord innerRecord, IntrospectedTable introspectedTable,
220 Set<FullyQualifiedJavaType> imports) {}
221
222 /**
223 * Adds a @Generated annotation to an enum.
224 *
225 * @param innerEnum the enum
226 * @param introspectedTable the introspected table
227 * @param imports
228 * the comment generator may add a required imported type to this list
229 *
230 * @since 2.0.0
231 */
232 default void addEnumAnnotation(InnerEnum innerEnum, IntrospectedTable introspectedTable,
233 Set<FullyQualifiedJavaType> imports) {}
234
235 /**
236 * This method is called to add a file level comment to a generated Kotlin file. This method
237 * could be used to add a general file comment (such as a copyright notice).
238 *
239 * <p>The default implementation does nothing.
240 *
241 * @param kotlinFile
242 * the Kotlin file
243 */
244 default void addFileComment(KotlinFile kotlinFile) {}
245
246 default void addGeneralFunctionComment(KotlinFunction kf, IntrospectedTable introspectedTable,
247 Set<String> imports) {}
248
249 default void addGeneralPropertyComment(KotlinProperty property, IntrospectedTable introspectedTable,
250 Set<String> imports) {}
251 }