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.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 * <p>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 * <p>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 * <p>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 *
56 * @return the directory (must exist)
57 *
58 * @throws ShellException
59 * if the project/package cannot be resolved into a directory on the file system. In this case, the
60 * generator will not save the file it is currently working on. The generator will add the exception
61 * message to the list of warnings automatically.
62 */
63 File getDirectory(String targetProject, String targetPackage)
64 throws ShellException;
65
66 /**
67 * This method is called if a newly generated Java file would
68 * overwrite an existing file. This method should return the merged source
69 * (formatted). The generator will write the merged source as-is to the file
70 * system.
71 *
72 * <p>A merge typically follows these steps:
73 * <ol>
74 * <li>Delete any methods/fields in the existing file that have the
75 * specified JavaDoc tag</li>
76 * <li>Add any new super interfaces from the new file into the existing file
77 * </li>
78 * <li>Make sure that the existing file's super class matches the new file</li>
79 * <li>Make sure that the existing file is of the same type as the existing
80 * file (either interface or class)</li>
81 * <li>Add any new imports from the new file into the existing file</li>
82 * <li>Add all methods and fields from the new file into the existing file</li>
83 * <li>Format the resulting source string</li>
84 * </ol>
85 *
86 * <p>This method is called only if you return <code>true</code> from
87 * <code>isMergeSupported()</code>.
88 *
89 * @param newFileSource
90 * the source of the newly generated Java file
91 * @param existingFile
92 * the existing Java file
93 * @param javadocTags
94 * the JavaDoc tags that denotes which methods and fields in the
95 * old file to delete (if the Java element has any of these tags,
96 * the element is eligible for merge)
97 * @param fileEncoding
98 * the file encoding for reading existing Java files. Can be null,
99 * in which case the platform default encoding will be used.
100 * @return the merged source, properly formatted. The source will be saved
101 * exactly as returned from this method.
102 * @throws ShellException
103 * if the file cannot be merged for some reason. If this
104 * exception is thrown, nothing will be saved and the
105 * existing file will remain undisturbed. The generator will add the
106 * exception message to the list of warnings automatically.
107 */
108 default String mergeJavaFile(String newFileSource, File existingFile,
109 String[] javadocTags, String fileEncoding) throws ShellException {
110 throw new UnsupportedOperationException();
111 }
112
113 /**
114 * After all files are saved to the file system, this method is called
115 * once for each unique project that was affected by the generation
116 * run. This method is useful if your IDE needs to be informed that file
117 * system objects have been created or updated. If you are running
118 * outside of an IDE, your implementation need not do anything in this
119 * method.
120 *
121 * @param project
122 * the project to be refreshed
123 */
124 default void refreshProject(String project) {}
125
126 /**
127 * Return true if the callback supports Java merging, otherwise false.
128 * The <code>mergeJavaFile()</code> method will be called only if this
129 * method returns <code>true</code>.
130 *
131 * @return a boolean specifying whether Java merge is supported or not
132 */
133 default boolean isMergeSupported() {
134 return false;
135 }
136
137 /**
138 * Return true if the generator should overwrite an existing file if one exists.
139 * This method will be called only if <code>isMergeSupported()</code>
140 * returns <code>false</code> and a file exists that would be overwritten by
141 * a generated file. If you return <code>true</code>, then we will log a
142 * warning specifying what file was overwritten.
143 *
144 * @return true if you want to overwrite existing files
145 */
146 boolean isOverwriteEnabled();
147 }