1 /**
2 * Copyright 2006-2016 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 * http://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
20 import org.mybatis.generator.api.dom.java.CompilationUnit;
21 import org.mybatis.generator.api.dom.java.Field;
22 import org.mybatis.generator.api.dom.java.InnerClass;
23 import org.mybatis.generator.api.dom.java.InnerEnum;
24 import org.mybatis.generator.api.dom.java.Method;
25 import org.mybatis.generator.api.dom.java.TopLevelClass;
26 import org.mybatis.generator.api.dom.xml.XmlElement;
27
28 /**
29 * Implementations of this interface are used to generate comments for the
30 * various artifacts.
31 *
32 * @author Jeff Butler
33 */
34 public interface CommentGenerator {
35
36 /**
37 * Adds properties for this instance from any properties configured in the
38 * CommentGenerator configuration.
39 *
40 * This method will be called before any of the other methods.
41 *
42 * @param properties
43 * All properties from the configuration
44 */
45 void addConfigurationProperties(Properties properties);
46
47 /**
48 * This method should add a Javadoc comment to the specified field. The field is related to the specified table and
49 * is used to hold the value of the specified column.
50 * <p>
51 *
52 * <b>Important:</b> This method should add a the nonstandard JavaDoc tag "@mbggenerated" to the comment. Without
53 * this tag, the Eclipse based Java merge feature will fail.
54 *
55 * @param field
56 * the field
57 * @param introspectedTable
58 * the introspected table
59 * @param introspectedColumn
60 * the introspected column
61 */
62 void addFieldComment(Field field,
63 IntrospectedTable introspectedTable,
64 IntrospectedColumn introspectedColumn);
65
66 /**
67 * Adds the field comment.
68 *
69 * @param field
70 * the field
71 * @param introspectedTable
72 * the introspected table
73 */
74 void addFieldComment(Field field, IntrospectedTable introspectedTable);
75
76 /**
77 * Adds a comment for a model class. The Java code merger should
78 * be notified not to delete the entire class in case any manual
79 * changes have been made. So this method will always use the
80 * "do not delete" annotation.
81 *
82 * Because of difficulties with the Java file merger, the default implementation
83 * of this method should NOT add comments. Comments should only be added if
84 * specifically requested by the user (for example, by enabling table remark comments).
85 *
86 * @param topLevelClass
87 * the top level class
88 * @param introspectedTable
89 * the introspected table
90 */
91 void addModelClassComment(TopLevelClass topLevelClass,
92 IntrospectedTable introspectedTable);
93
94 /**
95 * Adds the inner class comment.
96 *
97 * @param innerClass
98 * the inner class
99 * @param introspectedTable
100 * the introspected table
101 */
102 void addClassComment(InnerClass innerClass,
103 IntrospectedTable introspectedTable);
104
105 /**
106 * Adds the inner class comment.
107 *
108 * @param innerClass
109 * the inner class
110 * @param introspectedTable
111 * the introspected table
112 * @param markAsDoNotDelete
113 * the mark as do not delete
114 */
115 void addClassComment(InnerClass innerClass,
116 IntrospectedTable introspectedTable, boolean markAsDoNotDelete);
117
118 /**
119 * Adds the enum comment.
120 *
121 * @param innerEnum
122 * the inner enum
123 * @param introspectedTable
124 * the introspected table
125 */
126 void addEnumComment(InnerEnum innerEnum,
127 IntrospectedTable introspectedTable);
128
129 /**
130 * Adds the getter comment.
131 *
132 * @param method
133 * the method
134 * @param introspectedTable
135 * the introspected table
136 * @param introspectedColumn
137 * the introspected column
138 */
139 void addGetterComment(Method method,
140 IntrospectedTable introspectedTable,
141 IntrospectedColumn introspectedColumn);
142
143 /**
144 * Adds the setter comment.
145 *
146 * @param method
147 * the method
148 * @param introspectedTable
149 * the introspected table
150 * @param introspectedColumn
151 * the introspected column
152 */
153 void addSetterComment(Method method,
154 IntrospectedTable introspectedTable,
155 IntrospectedColumn introspectedColumn);
156
157 /**
158 * Adds the general method comment.
159 *
160 * @param method
161 * the method
162 * @param introspectedTable
163 * the introspected table
164 */
165 void addGeneralMethodComment(Method method,
166 IntrospectedTable introspectedTable);
167
168 /**
169 * This method is called to add a file level comment to a generated java file. This method could be used to add a
170 * general file comment (such as a copyright notice). However, note that the Java file merge function in Eclipse
171 * does not deal with this comment. If you run the generator repeatedly, you will only retain the comment from the
172 * initial run.
173 * <p>
174 *
175 * The default implementation does nothing.
176 *
177 * @param compilationUnit
178 * the compilation unit
179 */
180 void addJavaFileComment(CompilationUnit compilationUnit);
181
182 /**
183 * This method should add a suitable comment as a child element of the specified xmlElement to warn users that the
184 * element was generated and is subject to regeneration.
185 *
186 * @param xmlElement
187 * the xml element
188 */
189 void addComment(XmlElement xmlElement);
190
191 /**
192 * This method is called to add a comment as the first child of the root element. This method could be used to add a
193 * general file comment (such as a copyright notice). However, note that the XML file merge function does not deal
194 * with this comment. If you run the generator repeatedly, you will only retain the comment from the initial run.
195 * <p>
196 *
197 * The default implementation does nothing.
198 *
199 * @param rootElement
200 * the root element
201 */
202 void addRootComment(XmlElement rootElement);
203 }