1 /*
2 Copyright (c) 2008 Sonatype, Inc. All rights reserved.
3
4 This program is licensed to you under the Apache License Version 2.0,
5 and you may not use this file except in compliance with the Apache License Version 2.0.
6 You may obtain a copy of the Apache License Version 2.0 at http://www.apache.org/licenses/LICENSE-2.0.
7
8 Unless required by applicable law or agreed to in writing,
9 software distributed under the Apache License Version 2.0 is distributed on an
10 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11 See the Apache License Version 2.0 for the specific language governing permissions and limitations there under.
12 */
13 package org.codehaus.plexus.build;
14
15 import java.io.File;
16 import java.io.IOException;
17 import java.io.OutputStream;
18 import java.util.List;
19
20 import org.codehaus.plexus.util.Scanner;
21
22 /**
23 * <p>BuildContext interface.</p>
24 */
25 public interface BuildContext {
26 /** Constant <code>SEVERITY_WARNING=1</code> */
27 int SEVERITY_WARNING = 1;
28
29 /** Constant <code>SEVERITY_ERROR=2</code> */
30 int SEVERITY_ERROR = 2;
31
32 /**
33 * Returns <code>true</code> if file or folder identified by <code>relpath</code> has
34 * changed since last build.
35 *
36 * @param relpath is path relative to build context basedir
37 * @return a boolean.
38 */
39 boolean hasDelta(String relpath);
40
41 /**
42 * Returns <code>true</code> if the file has changed since last build or is not
43 * under basedir.
44 *
45 * @since 0.0.5
46 * @param file a {@link java.io.File} object.
47 * @return a boolean.
48 */
49 boolean hasDelta(File file);
50
51 /**
52 * Returns <code>true</code> if any file or folder identified by <code>relpaths</code> has
53 * changed since last build.
54 *
55 * @param relpaths paths relative to build context basedir
56 * @return a boolean.
57 */
58 boolean hasDelta(List<String> relpaths);
59
60 /**
61 * Indicates that the file or folder content has been modified during the build.
62 *
63 * @see #newFileOutputStream(File)
64 * @param file a {@link java.io.File} object.
65 */
66 void refresh(File file);
67
68 /**
69 * Returns new OutputStream that writes to the <code>file</code>.
70 *
71 * Files changed using OutputStream returned by this method do not need to be
72 * explicitly refreshed using {@link #refresh(File)}.
73 *
74 * As an optional optimisation, OutputStreams created by incremental build
75 * context will attempt to avoid writing to the file if file content
76 * has not changed.
77 *
78 * @param file a {@link java.io.File} object.
79 * @return a {@link java.io.OutputStream} object.
80 * @throws java.io.IOException if any.
81 */
82 OutputStream newFileOutputStream(File file) throws IOException;
83
84 /**
85 * Convenience method, fully equal to newScanner(basedir, false)
86 *
87 * @param basedir a {@link java.io.File} object.
88 * @return a {@link org.codehaus.plexus.util.Scanner} object.
89 */
90 Scanner newScanner(File basedir);
91
92 /**
93 * Returned Scanner scans <code>basedir</code> for files and directories
94 * deleted since last build. Returns empty Scanner if <code>basedir</code>
95 * is not under this build context basedir.
96 *
97 * @param basedir a {@link java.io.File} object.
98 * @return a {@link org.codehaus.plexus.util.Scanner} object.
99 */
100 Scanner newDeleteScanner(File basedir);
101
102 /**
103 * Returned Scanner scans files and folders under <code>basedir</code>.
104 *
105 * If this is an incremental build context and <code>ignoreDelta</code>
106 * is <code>false</code>, the scanner will only "see" files and folders with
107 * content changes since last build.
108 *
109 * If <code>ignoreDelta</code> is <code>true</code>, the scanner will "see" all
110 * files and folders.
111 *
112 * Please beware that ignoreDelta=false does NOT work reliably for operations
113 * that copy resources from source to target locations. Returned Scanner
114 * only scans changed source resources and it does not consider changed or deleted
115 * target resources. This results in missing or stale target resources.
116 * Starting with 0.5.0, recommended way to process resources is to use
117 * #newScanner(basedir,true) to locate all source resources and {@link #isUptodate(File, File)}
118 * to optimized processing of uptodate target resources.
119 *
120 * Returns empty Scanner if <code>basedir</code> is not under this build context basedir.
121 *
122 * https://issues.apache.org/jira/browse/MSHARED-125
123 *
124 * @param basedir a {@link java.io.File} object.
125 * @param ignoreDelta a boolean.
126 * @return a {@link org.codehaus.plexus.util.Scanner} object.
127 */
128 Scanner newScanner(File basedir, boolean ignoreDelta);
129
130 /**
131 * Returns <code>true</code> if this build context is incremental.
132 *
133 * Scanners created by {@link #newScanner(File)} of an incremental build context
134 * will ignore files and folders that were not changed since last build.
135 * Additionally, {@link #newDeleteScanner(File)} will scan files and directories
136 * deleted since last build.
137 *
138 * @return a boolean.
139 */
140 boolean isIncremental();
141
142 /**
143 * Associate specified <code>key</code> with specified <code>value</code>
144 * in the build context.
145 *
146 * Primary (and the only) purpose of this method is to allow preservation of
147 * state needed for proper incremental behaviour between consecutive executions
148 * of the same mojo needed to.
149 *
150 * For example, maven-plugin-plugin:descriptor mojo
151 * can store collection of extracted MojoDescritpor during first invocation. Then
152 * on each consecutive execution maven-plugin-plugin:descriptor will only need
153 * to extract MojoDescriptors for changed files.
154 *
155 * @see #getValue(String)
156 * @param key a {@link java.lang.String} object.
157 * @param value a {@link java.lang.Object} object.
158 */
159 void setValue(String key, Object value);
160
161 /**
162 * Returns value associated with <code>key</code> during previous mojo execution.
163 *
164 * This method always returns <code>null</code> for non-incremental builds
165 * (i.e., {@link #isIncremental()} returns <code>false</code>) and mojos are
166 * expected to fall back to full, non-incremental behaviour.
167 *
168 * @see #setValue(String, Object)
169 * @see #isIncremental()
170 * @param key a {@link java.lang.String} object.
171 * @return a {@link java.lang.Object} object.
172 */
173 Object getValue(String key);
174
175 /**
176 * <p>addWarning.</p>
177 *
178 * @deprecated Use addMessage with severity=SEVERITY_ERROR instead
179 * @since 0.0.5
180 * @param file a {@link java.io.File} object.
181 * @param line a int.
182 * @param column a int.
183 * @param message a {@link java.lang.String} object.
184 * @param cause a {@link java.lang.Throwable} object.
185 */
186 void addWarning(File file, int line, int column, String message, Throwable cause);
187
188 /**
189 * <p>addError.</p>
190 *
191 * @deprecated Use addMessage with severity=SEVERITY_WARNING instead
192 * @since 0.0.5
193 * @param file a {@link java.io.File} object.
194 * @param line a int.
195 * @param column a int.
196 * @param message a {@link java.lang.String} object.
197 * @param cause a {@link java.lang.Throwable} object.
198 */
199 void addError(File file, int line, int column, String message, Throwable cause);
200
201 /**
202 * Adds a message to the build context. The message is associated with a file and a location inside that file.
203 *
204 * @param file The file or folder with which the message is associated. Should not be null and it is recommended to be
205 * an absolute path.
206 * @param line The line number inside the file. Use 1 (not 0) for the first line. Use 0 for unknown/unspecified.
207 * @param column The column number inside the file. Use 1 (not 0) for the first column. Use 0 for unknown/unspecified.
208 * @param severity The severity of the message: SEVERITY_WARNING or SEVERITY_ERROR.
209 * @param cause A Throwable object associated with the message. Can be null.
210 * @since 0.0.7
211 * @param message a {@link java.lang.String} object.
212 * @deprecated Use {@link org.codehaus.plexus.build.messages.Messages} API instead
213 */
214 @Deprecated
215 void addMessage(File file, int line, int column, String message, int severity, Throwable cause);
216
217 /**
218 * Removes all messages associated with a file or folder during a previous build. It does not affect the messages
219 * added during the current build.
220 *
221 * @since 0.0.7
222 * @param file a {@link java.io.File} object.
223 * @deprecated Use {@link org.codehaus.plexus.build.messages.Messages#clear(java.nio.file.Path)} instead
224 */
225 @Deprecated
226 void removeMessages(File file);
227
228 /**
229 * Returns true, if the target file exists and is uptodate compared to the source file.
230 *
231 * More specifically, this method returns true when both target and source files exist,
232 * do not have changes since last incremental build and the target file was last modified
233 * later than the source file. Returns false in all other cases.
234 *
235 * @since 0.0.5
236 * @param target a {@link java.io.File} object.
237 * @param source a {@link java.io.File} object.
238 * @return a boolean.
239 */
240 boolean isUptodate(File target, File source);
241 }