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.io.File;
19  
20  import org.mybatis.generator.exception.ShellException;
21  
22  /**
23   * This interface defines methods that a shell should support to enable
24   * the generator
25   * to work. A "shell" is defined as the execution environment (i.e. an
26   * Eclipse plugin, and Ant task, a NetBeans plugin, etc.)
27   * 
28   * The default ShellCallback that is very low function and does
29   * not support the merging of Java files. The default shell callback is 
30   * appropriate for use in well controlled environments where no changes
31   * made to generated Java files.
32   * 
33   * @author Jeff Butler
34   */
35  public interface ShellCallback {
36      
37      /**
38       * This method is called to ask the shell to resolve a project/package combination into a directory on the file
39       * system. This method is called repeatedly (once for each generated file), so it would be wise for an implementing
40       * class to cache results.
41       * 
42       * The returned <code>java.io.File</code> object:
43       * <ul>
44       * <li>Must be a directory</li>
45       * <li>Must exist</li>
46       * </ul>
47       * 
48       * The default shell callback interprets both values as directories and simply concatenates the two values to
49       * generate the default directory.
50       *
51       * @param targetProject
52       *            the target project
53       * @param targetPackage
54       *            the target package
55       * @return the directory (must exist)
56       * @throws ShellException
57       *             if the project/package cannot be resolved into a directory on the file system. In this case, the
58       *             generator will not save the file it is currently working on. The generator will add the exception
59       *             message to the list of warnings automatically.
60       */
61      File getDirectory(String targetProject, String targetPackage)
62              throws ShellException;
63  
64      /**
65       * This method is called if a newly generated Java file would
66       * overwrite an existing file. This method should return the merged source
67       * (formatted). The generator will write the merged source as-is to the file
68       * system.
69       * 
70       * A merge typically follows these steps:
71       * <ol>
72       * <li>Delete any methods/fields in the existing file that have the
73       * specified JavaDoc tag</li>
74       * <li>Add any new super interfaces from the new file into the existing file
75       * </li>
76       * <li>Make sure that the existing file's super class matches the new file</li>
77       * <li>Make sure that the existing file is of the same type as the existing
78       * file (either interface or class)</li>
79       * <li>Add any new imports from the new file into the existing file</li>
80       * <li>Add all methods and fields from the new file into the existing file</li>
81       * <li>Format the resulting source string</li>
82       * </ol>
83       * 
84       * This method is called only if you return <code>true</code> from
85       * <code>isMergeSupported()</code>.
86       * 
87       * @param newFileSource
88       *            the source of the newly generated Java file
89       * @param existingFileFullPath
90       *            the fully qualified path name of the existing Java file
91       * @param javadocTags
92       *            the JavaDoc tags that denotes which methods and fields in the
93       *            old file to delete (if the Java element has any of these tags,
94       *            the element is eligible for merge)
95       * @param fileEncoding
96       *            the file encoding for reading existing Java files.  Can be null,
97       *            in which case the platform default encoding will be used.
98       * @return the merged source, properly formatted. The source will be saved
99       *         exactly as returned from this method.
100      * @throws ShellException
101      *             if the file cannot be merged for some reason. If this
102      *             exception is thrown, nothing will be saved and the
103      *             existing file will remain undisturbed. The generator will add the
104      *             exception message to the list of warnings automatically.
105      */
106     String mergeJavaFile(String newFileSource, String existingFileFullPath,
107             String[] javadocTags, String fileEncoding) throws ShellException;
108 
109     /**
110      * After all files are saved to the file system, this method is called
111      * once for each unique project that was affected by the generation
112      * run. This method is useful if your IDE needs to be informed that file
113      * system objects have been created or updated. If you are running 
114      * outside of an IDE, your implementation need not do anything in this
115      * method.
116      * 
117      * @param project
118      *            the project to be refreshed
119      */
120     void refreshProject(String project);
121 
122     /**
123      * Return true if the callback supports Java merging, otherwise false.
124      * The <code>mergeJavaFile()</code> method will be called only if this
125      * method returns <code>true</code>.
126      * 
127      * @return a boolean specifying whether Java merge is supported or not
128      */
129     boolean isMergeSupported();
130 
131     /**
132      * Return true if the generator should overwrite an existing file if one exists.
133      * This method will be called only if <code>isMergeSupported()</code>
134      * returns <code>false</code> and a file exists that would be overwritten by
135      * a generated file. If you return <code>true</code>, then we will log a
136      * warning specifying what file was overwritten.
137      * 
138      * @return true if you want to overwrite existing files
139      */
140     boolean isOverwriteEnabled();
141 }