1 /*
2 * Copyright 2006-2023 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.Method;
27 import org.mybatis.generator.api.dom.java.TopLevelClass;
28 import org.mybatis.generator.api.dom.kotlin.KotlinFile;
29 import org.mybatis.generator.api.dom.kotlin.KotlinFunction;
30 import org.mybatis.generator.api.dom.kotlin.KotlinProperty;
31 import org.mybatis.generator.api.dom.kotlin.KotlinType;
32 import org.mybatis.generator.api.dom.xml.XmlElement;
33
34 /**
35 * Implementations of this interface are used to generate comments for the
36 * various artifacts.
37 *
38 * @author Jeff Butler
39 */
40 public interface CommentGenerator {
41
42 /**
43 * Adds properties for this instance from any properties configured in the
44 * CommentGenerator configuration.
45 *
46 * <p>This method will be called before any of the other methods.
47 *
48 * @param properties
49 * All properties from the configuration
50 */
51 void addConfigurationProperties(Properties properties);
52
53 /**
54 * This method should add a Javadoc comment to the specified field. The field is related to the
55 * specified table and is used to hold the value of the specified column.
56 *
57 * <p><b>Important:</b> This method should add a the nonstandard JavaDoc tag "@mbg.generated" to
58 * the comment. Without this tag, the Eclipse based Java merge feature will fail.
59 *
60 * @param field
61 * the field
62 * @param introspectedTable
63 * the introspected table
64 * @param introspectedColumn
65 * the introspected column
66 */
67 default void addFieldComment(Field field,
68 IntrospectedTable introspectedTable,
69 IntrospectedColumn introspectedColumn) {}
70
71 /**
72 * Adds the field comment.
73 *
74 * @param field
75 * the field
76 * @param introspectedTable
77 * the introspected table
78 */
79 default void addFieldComment(Field field, IntrospectedTable introspectedTable) {}
80
81 /**
82 * Adds a comment for a model class. The Java code merger should
83 * be notified not to delete the entire class in case any manual
84 * changes have been made. So this method will always use the
85 * "do not delete" annotation.
86 *
87 * <p>Because of difficulties with the Java file merger, the default implementation
88 * of this method should NOT add comments. Comments should only be added if
89 * specifically requested by the user (for example, by enabling table remark comments).
90 *
91 * @param topLevelClass
92 * the top level class
93 * @param introspectedTable
94 * the introspected table
95 */
96 default void addModelClassComment(TopLevelClass topLevelClass,
97 IntrospectedTable introspectedTable) {}
98
99 /**
100 * Adds a comment for a model class.
101 *
102 * @param modelClass
103 * the generated KotlinType for the model
104 * @param introspectedTable
105 * the introspected table
106 */
107 default void addModelClassComment(KotlinType modelClass,
108 IntrospectedTable introspectedTable) {}
109
110 /**
111 * Adds the inner class comment.
112 *
113 * @param innerClass
114 * the inner class
115 * @param introspectedTable
116 * the introspected table
117 */
118 default void addClassComment(InnerClass innerClass,
119 IntrospectedTable introspectedTable) {}
120
121 /**
122 * Adds the inner class comment.
123 *
124 * @param innerClass
125 * the inner class
126 * @param introspectedTable
127 * the introspected table
128 * @param markAsDoNotDelete
129 * the mark as do not delete
130 */
131 default void addClassComment(InnerClass innerClass,
132 IntrospectedTable introspectedTable, boolean markAsDoNotDelete) {}
133
134 /**
135 * Adds the enum comment.
136 *
137 * @param innerEnum
138 * the inner enum
139 * @param introspectedTable
140 * the introspected table
141 */
142 default void addEnumComment(InnerEnum innerEnum,
143 IntrospectedTable introspectedTable) {}
144
145 /**
146 * Adds the getter comment.
147 *
148 * @param method
149 * the method
150 * @param introspectedTable
151 * the introspected table
152 * @param introspectedColumn
153 * the introspected column
154 */
155 default void addGetterComment(Method method,
156 IntrospectedTable introspectedTable,
157 IntrospectedColumn introspectedColumn) {}
158
159 /**
160 * Adds the setter comment.
161 *
162 * @param method
163 * the method
164 * @param introspectedTable
165 * the introspected table
166 * @param introspectedColumn
167 * the introspected column
168 */
169 default void addSetterComment(Method method,
170 IntrospectedTable introspectedTable,
171 IntrospectedColumn introspectedColumn) {}
172
173 /**
174 * Adds the general method comment.
175 *
176 * @param method
177 * the method
178 * @param introspectedTable
179 * the introspected table
180 */
181 default void addGeneralMethodComment(Method method,
182 IntrospectedTable introspectedTable) {}
183
184 /**
185 * This method is called to add a file level comment to a generated java file. This method
186 * could be used to add a general file comment (such as a copyright notice). However, note
187 * that the Java file merge function in Eclipse does not deal with this comment. If you run
188 * the generator repeatedly, you will only retain the comment from the initial run.
189 *
190 * <p>The default implementation does nothing.
191 *
192 * @param compilationUnit
193 * the compilation unit
194 */
195 default void addJavaFileComment(CompilationUnit compilationUnit) {}
196
197 /**
198 * This method should add a suitable comment as a child element of the specified xmlElement to warn users that the
199 * element was generated and is subject to regeneration.
200 *
201 * @param xmlElement
202 * the xml element
203 */
204 default void addComment(XmlElement xmlElement) {}
205
206 /**
207 * This method is called to add a comment as the first child of the root element. This method
208 * could be used to add a general file comment (such as a copyright notice). However, note
209 * that the XML file merge function does not deal with this comment. If you run the generator
210 * repeatedly, you will only retain the comment from the initial run.
211 *
212 * <p>The default implementation does nothing.
213 *
214 * @param rootElement
215 * the root element
216 */
217 default void addRootComment(XmlElement rootElement) {}
218
219 /**
220 * Adds a @Generated annotation to a method.
221 *
222 * @param method
223 * the method
224 * @param introspectedTable
225 * the introspected table
226 * @param imports
227 * the comment generator may add a required imported type to this list
228 *
229 * @since 1.3.6
230 */
231 default void addGeneralMethodAnnotation(Method method, IntrospectedTable introspectedTable,
232 Set<FullyQualifiedJavaType> imports) {}
233
234 /**
235 * Adds a @Generated annotation to a method.
236 *
237 * @param method
238 * the method
239 * @param introspectedTable
240 * the introspected table
241 * @param introspectedColumn
242 * thr introspected column
243 * @param imports
244 * the comment generator may add a required imported type to this list
245 *
246 * @since 1.3.6
247 */
248 default void addGeneralMethodAnnotation(Method method, IntrospectedTable introspectedTable,
249 IntrospectedColumn introspectedColumn, Set<FullyQualifiedJavaType> imports) {}
250
251 /**
252 * Adds a @Generated annotation to a field.
253 *
254 * @param field
255 * the field
256 * @param introspectedTable
257 * the introspected table
258 * @param imports
259 * the comment generator may add a required imported type to this list
260 *
261 * @since 1.3.6
262 */
263 default void addFieldAnnotation(Field field, IntrospectedTable introspectedTable,
264 Set<FullyQualifiedJavaType> imports) {}
265
266 /**
267 * Adds a @Generated annotation to a field.
268 *
269 * @param field
270 * the field
271 * @param introspectedTable
272 * the introspected table
273 * @param introspectedColumn
274 * the introspected column
275 * @param imports
276 * the comment generator may add a required imported type to this list
277 *
278 * @since 1.3.6
279 */
280 default void addFieldAnnotation(Field field, IntrospectedTable introspectedTable,
281 IntrospectedColumn introspectedColumn, Set<FullyQualifiedJavaType> imports) {}
282
283 /**
284 * Adds a @Generated annotation to a class.
285 *
286 * @param innerClass
287 * the class
288 * @param introspectedTable
289 * the introspected table
290 * @param imports
291 * the comment generator may add a required imported type to this list
292 *
293 * @since 1.3.6
294 */
295 default void addClassAnnotation(InnerClass innerClass, IntrospectedTable introspectedTable,
296 Set<FullyQualifiedJavaType> imports) {}
297
298 /**
299 * This method is called to add a file level comment to a generated Kotlin file. This method
300 * could be used to add a general file comment (such as a copyright notice).
301 *
302 * <p>The default implementation does nothing.
303 *
304 * @param kotlinFile
305 * the Kotlin file
306 */
307 default void addFileComment(KotlinFile kotlinFile) {}
308
309 default void addGeneralFunctionComment(KotlinFunction kf, IntrospectedTable introspectedTable,
310 Set<String> imports) {}
311
312 default void addGeneralPropertyComment(KotlinProperty property, IntrospectedTable introspectedTable,
313 Set<String> imports) {}
314 }