View Javadoc
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 }