diff --git a/src/main/org/apache/tools/ant/BuildLogger.java b/src/main/org/apache/tools/ant/BuildLogger.java index 22590377e..bdbb659be 100644 --- a/src/main/org/apache/tools/ant/BuildLogger.java +++ b/src/main/org/apache/tools/ant/BuildLogger.java @@ -68,10 +68,10 @@ import java.io.PrintStream; public interface BuildLogger extends BuildListener { /** - * Sets the msgOutputLevel this logger is to respond to. + * Sets the highest level of message this logger should respond to. * - * Only messages with a message level lower than or equal to the given - * level are output to the log. + * Only messages with a message level lower than or equal to the + * given level should be written to the log. *

* Constants for the message levels are in the * {@link Project Project} class. The order of the levels, from least @@ -94,8 +94,8 @@ public interface BuildLogger extends BuildListener { /** * Sets this logger to produce emacs (and other editor) friendly output. * - * @param emacsMode true if output is to be unadorned so that - * emacs and other editors can parse files names, etc. + * @param emacsMode true if output is to be unadorned so that + * emacs and other editors can parse files names, etc. */ void setEmacsMode(boolean emacsMode); @@ -103,7 +103,7 @@ public interface BuildLogger extends BuildListener { * Sets the output stream to which this logger is to send error messages. * * @param err The error stream for the logger. - * Must not be null. + * Must not be null. */ void setErrorPrintStream(PrintStream err); } diff --git a/src/main/org/apache/tools/ant/DefaultLogger.java b/src/main/org/apache/tools/ant/DefaultLogger.java index 73e6d4c86..c2af64a96 100644 --- a/src/main/org/apache/tools/ant/DefaultLogger.java +++ b/src/main/org/apache/tools/ant/DefaultLogger.java @@ -62,35 +62,52 @@ import org.apache.tools.ant.util.StringUtils; import org.apache.tools.ant.util.DateUtils; /** - * Writes build event to a PrintStream. Currently, it - * only writes which targets are being executed, and - * any messages that get logged. + * Writes build events to a PrintStream. Currently, it + * only writes which targets are being executed, and + * any messages that get logged. */ public class DefaultLogger implements BuildLogger { + /** + * Size of left-hand column for right-justified task name. + * @see #messageLogged(BuildEvent) + */ private static int LEFT_COLUMN_SIZE = 12; + /** PrintStream to write non-error messages to */ protected PrintStream out; + /** PrintStream to write error messages to */ protected PrintStream err; + /** Lowest level of message to write out */ protected int msgOutputLevel = Project.MSG_ERR; + /** Time of the start of the build */ private long startTime = System.currentTimeMillis(); - /** line separator */ + /** Line separator */ protected final static String lSep = StringUtils.LINE_SEP; - + + /** Whether or not to use emacs-style output */ protected boolean emacsMode = false; /** - * Set the msgOutputLevel this logger is to respond to. + * Sole constructor. + */ + public DefaultLogger() { + } + + /** + * Sets the highest level of message this logger should respond to. * - * Only messages with a message level lower than or equal to the given level are - * output to the log. + * Only messages with a message level lower than or equal to the + * given level should be written to the log. + *

+ * Constants for the message levels are in the + * {@link Project Project} class. The order of the levels, from least + * to most verbose, is MSG_ERR, MSG_WARN, + * MSG_INFO, MSG_VERBOSE, + * MSG_DEBUG. *

- * Constants for the message levels are in Project.java. The order of - * the levels, from least to most verbose, is MSG_ERR, MSG_WARN, - * MSG_INFO, MSG_VERBOSE, MSG_DEBUG. - * * The default message level for DefaultLogger is Project.MSG_ERR. - * + * * @param level the logging level for the logger. */ public void setMessageOutputLevel(int level) { @@ -98,40 +115,51 @@ public class DefaultLogger implements BuildLogger { } /** - * Set the output stream to which this logger is to send its output. + * Sets the output stream to which this logger is to send its output. * - * @param output the output stream for the logger. + * @param output The output stream for the logger. + * Must not be null. */ public void setOutputPrintStream(PrintStream output) { this.out = new PrintStream(output, true); } /** - * Set the output stream to which this logger is to send error messages. + * Sets the output stream to which this logger is to send error messages. * - * @param err the error stream for the logger. + * @param err The error stream for the logger. + * Must not be null. */ public void setErrorPrintStream(PrintStream err) { this.err = new PrintStream(err, true); } /** - * Set this logger to produce emacs (and other editor) friendly output. + * Sets this logger to produce emacs (and other editor) friendly output. * - * @param emacsMode true if output is to be unadorned so that emacs and other - * editors can parse files names, etc. + * @param emacsMode true if output is to be unadorned so that + * emacs and other editors can parse files names, etc. */ public void setEmacsMode(boolean emacsMode) { this.emacsMode = emacsMode; } + /** + * Responds to a build being started by just remembering the current time. + * + * @param event Ignored. + */ public void buildStarted(BuildEvent event) { startTime = System.currentTimeMillis(); } /** - * Prints whether the build succeeded or failed, and - * any errors the occured during the build. + * Prints whether the build succeeded or failed, + * any errors the occured during the build, and + * how long the build took. + * + * @param event An event with any relevant extra information. + * Must not be null. */ public void buildFinished(BuildEvent event) { Throwable error = event.getException(); @@ -172,6 +200,13 @@ public class DefaultLogger implements BuildLogger { log(msg); } + /** + * Logs a message to say that the target has started if this + * logger allows information-level messages. + * + * @param event An event with any relevant extra information. + * Must not be null. + */ public void targetStarted(BuildEvent event) { if (Project.MSG_INFO <= msgOutputLevel) { String msg = StringUtils.LINE_SEP + event.getTarget().getName() + ":"; @@ -180,12 +215,35 @@ public class DefaultLogger implements BuildLogger { } } - public void targetFinished(BuildEvent event) { - } + /** + * No-op implementation. + * + * @param event Ignored. + */ + public void targetFinished(BuildEvent event) {} + /** + * No-op implementation. + * + * @param event Ignored. + */ public void taskStarted(BuildEvent event) {} + + /** + * No-op implementation. + * + * @param event Ignored. + */ public void taskFinished(BuildEvent event) {} + /** + * Logs a message, if the priority is suitable. + * In non-emacs mode, task level messages are prefixed by the + * task name which is right-justified. + * + * @param event A BuildEvent containing message information. + * Must not be null. + */ public void messageLogged(BuildEvent event) { int priority = event.getPriority(); // Filter out messages based on priority @@ -216,10 +274,27 @@ public class DefaultLogger implements BuildLogger { } } + /** + * Convenience method to format a specified length of time. + * + * @param millis Length of time to format, in milliseonds. + * + * @see DateUtils#formatElapsedTime(long) + */ protected static String formatTime(final long millis) { return DateUtils.formatElapsedTime(millis); } + /** + * Prints a message to a PrintStream. + * + * @param message The message to print. + * Should not be null. + * @param stream A PrintStream to print the message to. + * Must not be null. + * @param priority The priority of the message. + * (Ignored in this implementation.) + */ protected void printMessage(final String message, final PrintStream stream, final int priority) { @@ -229,6 +304,8 @@ public class DefaultLogger implements BuildLogger { /** * Empty implementation which allows subclasses to receive the * same output that is generated here. + * + * @param message Message being logged. Should not be null. */ protected void log(String message) {} } diff --git a/src/main/org/apache/tools/ant/DemuxOutputStream.java b/src/main/org/apache/tools/ant/DemuxOutputStream.java index c6bf32151..f2deaa466 100644 --- a/src/main/org/apache/tools/ant/DemuxOutputStream.java +++ b/src/main/org/apache/tools/ant/DemuxOutputStream.java @@ -1,7 +1,7 @@ /* * The Apache Software License, Version 1.1 * - * Copyright (c) 2001 The Apache Software Foundation. All rights + * Copyright (c) 2001-2002 The Apache Software Foundation. All rights * reserved. * * Redistribution and use in source and binary forms, with or without @@ -59,22 +59,33 @@ import java.io.ByteArrayOutputStream; import java.io.IOException; import java.util.Hashtable; - /** * Logs content written by a thread and forwards the buffers onto the * project object which will forward the content to the appropriate - * task + * task. * * @author Conor MacNeill */ public class DemuxOutputStream extends OutputStream { + /** Maximum buffer size */ private final static int MAX_SIZE = 1024; - + /** Mapping from thread to buffer (Thread->ByteOutputStream) */ private Hashtable buffers = new Hashtable(); // private ByteArrayOutputStream buffer = new ByteArrayOutputStream(); + /** + * Whether the next line-terminator should be skipped in terms + * of processing the buffer or not. Used to avoid \r\n invoking + * processBuffer twice. + */ private boolean skip = false; + /** + * The project to send output to + */ private Project project; + /** + * Whether or not this stream represents an error stream + */ private boolean isErrorStream; /** @@ -88,6 +99,11 @@ public class DemuxOutputStream extends OutputStream { this.isErrorStream = isErrorStream; } + /** + * Returns the buffer associated with the current thread. + * + * @return a ByteArrayOutputStream for the current thread to write data to + */ private ByteArrayOutputStream getBuffer() { Thread current = Thread.currentThread(); ByteArrayOutputStream buffer = (ByteArrayOutputStream)buffers.get(current); @@ -98,14 +114,17 @@ public class DemuxOutputStream extends OutputStream { return buffer; } + /** + * Resets the buffer for the current thread. + */ private void resetBuffer() { Thread current = Thread.currentThread(); buffers.remove(current); } /** - * Write the data to the buffer and flush the buffer, if a line - * separator is detected. + * Writes the data to the buffer and flushes the buffer if a line + * separator is detected or if the buffer has reached its maximum size. * * @param cc data to log (byte). */ @@ -122,12 +141,21 @@ public class DemuxOutputStream extends OutputStream { processBuffer(); } } - skip = (c == '\r'); + // XXX: This isn't threadsafe. Consider two threads logging + // Hello\r\n + // and + // There\r\n + // at the same time, with the two '\r's both being sent before + // either '\n', and the '\n's coming in the opposite order (thread-wise) + // to the '\r's - one buffer will be processed twice, and the other won't + // be processed at all. + skip = (c == '\r'); } /** - * Converts the buffer to a string and sends it to processLine + * Converts the buffer to a string and sends it to + * {@link Project#demuxOutput(String,boolean) Project.demuxOutput}. */ protected void processBuffer() { String output = getBuffer().toString(); @@ -136,14 +164,15 @@ public class DemuxOutputStream extends OutputStream { } /** - * Writes all remaining + * Equivalent to calling {@link #flush flush} on the stream. */ public void close() throws IOException { flush(); } /** - * Writes all remaining + * Writes all remaining data in the buffer associated + * with the current thread to the project. */ public void flush() throws IOException { if (getBuffer().size() > 0) { diff --git a/src/main/org/apache/tools/ant/DirectoryScanner.java b/src/main/org/apache/tools/ant/DirectoryScanner.java index ec4b953ce..843285013 100644 --- a/src/main/org/apache/tools/ant/DirectoryScanner.java +++ b/src/main/org/apache/tools/ant/DirectoryScanner.java @@ -59,7 +59,7 @@ import java.util.Vector; import java.util.StringTokenizer; /** - * Class for scanning a directory for files/directories that match a certain + * Class for scanning a directory for files/directories which match certain * criteria. *

* These criteria consist of a set of include and exclude patterns. With these @@ -68,8 +68,8 @@ import java.util.StringTokenizer; *

* The idea is simple. A given directory is recursively scanned for all files * and directories. Each file/directory is matched against a set of include - * and exclude patterns. Only files/directories that match at least one - * pattern of the include pattern list, and don't match a pattern of the + * and exclude patterns. Only files/directories which match at least one + * pattern of the include pattern list, and don't match any pattern of the * exclude pattern list will be placed in the list of files/directories found. *

* When no list of include patterns is supplied, "**" will be used, which @@ -80,16 +80,16 @@ import java.util.StringTokenizer; * The name to be matched is split up in path segments. A path segment is the * name of a directory or file, which is bounded by * File.separator ('/' under UNIX, '\' under Windows). - * E.g. "abc/def/ghi/xyz.java" is split up in the segments "abc", "def", "ghi" - * and "xyz.java". + * For example, "abc/def/ghi/xyz.java" is split up in the segments "abc", + * "def","ghi" and "xyz.java". * The same is done for the pattern against which should be matched. *

- * Then the segments of the name and the pattern will be matched against each - * other. When '**' is used for a path segment in the pattern, then it matches + * The segments of the name and the pattern are then matched against each + * other. When '**' is used for a path segment in the pattern, it matches * zero or more path segments of the name. *

- * There are special case regarding the use of File.separators at - * the beginningof the pattern and the string to match:
+ * There is a special case regarding the use of File.separators + * at the beginning of the pattern and the string to match:
* When a pattern starts with a File.separator, the string * to match must also start with a File.separator. * When a pattern does not start with a File.separator, the @@ -98,8 +98,8 @@ import java.util.StringTokenizer; * match. *

* When a name path segment is matched against a pattern path segment, the - * following special characters can be used: - * '*' matches zero or more characters, + * following special characters can be used:
+ * '*' matches zero or more characters
* '?' matches one character. *

* Examples: @@ -111,10 +111,10 @@ import java.util.StringTokenizer; *

* "**" matches everything in a directory tree. *

- * "**\test\**\XYZ*" matches all files/dirs that start with "XYZ" and where + * "**\test\**\XYZ*" matches all files/dirs which start with "XYZ" and where * there is a parent directory called test (e.g. "abc\test\def\ghi\XYZ123"). *

- * Case sensitivity may be turned off if necessary. By default, it is + * Case sensitivity may be turned off if necessary. By default, it is * turned on. *

* Example of usage: @@ -129,20 +129,21 @@ import java.util.StringTokenizer; * * System.out.println("FILES:"); * String[] files = ds.getIncludedFiles(); - * for (int i = 0; i < files.length;i++) { + * for (int i = 0; i < files.length; i++) { * System.out.println(files[i]); * } * * This will scan a directory called test for .class files, but excludes all - * .class files in all directories under a directory called "modules" + * files in all proper subdirectories of a directory called "modules" * - * @author Arnout J. Kuiper ajkuiper@wxs.nl + * @author Arnout J. Kuiper + * ajkuiper@wxs.nl * @author Magesh Umasankar */ public class DirectoryScanner implements FileScanner { /** - * Patterns that should be excluded by default. + * Patterns which should be excluded by default. * * @see #addDefaultExcludes() */ @@ -160,103 +161,93 @@ public class DirectoryScanner implements FileScanner { "**/vssver.scc" }; - /** - * The base directory which should be scanned. - */ + /** The base directory to be scanned. */ protected File basedir; - /** - * The patterns for the files that should be included. - */ + /** The patterns for the files to be included. */ protected String[] includes; - /** - * The patterns for the files that should be excluded. - */ + /** The patterns for the files to be excluded. */ protected String[] excludes; - /** - * The files that where found and matched at least one includes, and matched - * no excludes. - */ + /** The files which matched at least one include and no excludes. */ protected Vector filesIncluded; - /** - * The files that where found and did not match any includes. - */ + /** The files which did not match any includes. */ protected Vector filesNotIncluded; - /** - * The files that where found and matched at least one includes, and also - * matched at least one excludes. + /** + * The files which matched at least one include and at least + * one exclude. */ protected Vector filesExcluded; - /** - * The directories that where found and matched at least one includes, and - * matched no excludes. - */ + /** The directories which matched at least one include and no excludes. */ protected Vector dirsIncluded; - /** - * The directories that where found and did not match any includes. - */ + /** The directories which were found and did not match any includes. */ protected Vector dirsNotIncluded; - /** - * The files that where found and matched at least one includes, and also - * matched at least one excludes. + /** + * The directories which matched at least one include and at least one + * exclude. */ protected Vector dirsExcluded; - /** - * Have the Vectors holding our results been built by a slow scan? - */ + /** Whether or not our results were built by a slow scan. */ protected boolean haveSlowResults = false; - /** - * Should the file system be treated as a case sensitive one? + /** + * Whether or not the file system should be treated as a case sensitive + * one. */ protected boolean isCaseSensitive = true; - /** - * Is everything we've seen so far included? - */ + /** Whether or not everything tested so far has been included. */ protected boolean everythingIncluded = true; /** - * Constructor. + * Sole constructor. */ public DirectoryScanner() { } - /** - * Does the path match the start of this pattern up to the first "**". - * - *

This is not a general purpose test and should only be used if you - * can live with false positives.

- * - *

pattern=**\\a and str=b will yield true. + * Tests whether or not a given path matches the start of a given + * pattern up to the first "**". + *

+ * This is not a general purpose test and should only be used if you + * can live with false positives. For example, pattern=**\a + * and str=b will yield true. * - * @param pattern the (non-null) pattern to match against - * @param str the (non-null) string (path) to match + * @param pattern The pattern to match against. Must not be + * null. + * @param str The path to match, as a String. Must not be + * null. + * + * @return whether or not a given path matches the start of a given + * pattern up to the first "**". */ protected static boolean matchPatternStart(String pattern, String str) { return matchPatternStart(pattern, str, true); } - /** - * Does the path match the start of this pattern up to the first "**". - * - *

This is not a general purpose test and should only be used if you - * can live with false positives.

- * - *

pattern=**\\a and str=b will yield true. + * Tests whether or not a given path matches the start of a given + * pattern up to the first "**". + *

+ * This is not a general purpose test and should only be used if you + * can live with false positives. For example, pattern=**\a + * and str=b will yield true. * - * @param pattern the (non-null) pattern to match against - * @param str the (non-null) string (path) to match - * @param isCaseSensitive must matches be case sensitive? + * @param pattern The pattern to match against. Must not be + * null. + * @param str The path to match, as a String. Must not be + * null. + * @param isCaseSensitive Whether or not matching should be performed + * case sensitively. + * + * @return whether or not a given path matches the start of a given + * pattern up to the first "**". */ protected static boolean matchPatternStart(String pattern, String str, boolean isCaseSensitive) { @@ -269,17 +260,8 @@ public class DirectoryScanner implements FileScanner { return false; } - Vector patDirs = new Vector(); - StringTokenizer st = new StringTokenizer(pattern,File.separator); - while (st.hasMoreTokens()) { - patDirs.addElement(st.nextToken()); - } - - Vector strDirs = new Vector(); - st = new StringTokenizer(str,File.separator); - while (st.hasMoreTokens()) { - strDirs.addElement(st.nextToken()); - } + Vector patDirs = tokenizePath (pattern); + Vector strDirs = tokenizePath (str); int patIdxStart = 0; int patIdxEnd = patDirs.size()-1; @@ -313,27 +295,32 @@ public class DirectoryScanner implements FileScanner { } /** - * Matches a path against a pattern. + * Tests whether or not a given path matches a given pattern. * - * @param pattern the (non-null) pattern to match against - * @param str the (non-null) string (path) to match + * @param pattern The pattern to match against. Must not be + * null. + * @param str The path to match, as a String. Must not be + * null. * - * @return true when the pattern matches against the string. - * false otherwise. + * @return true if the pattern matches against the string, + * or false otherwise. */ protected static boolean matchPath(String pattern, String str) { return matchPath(pattern, str, true); } /** - * Matches a path against a pattern. + * Tests whether or not a given path matches a given pattern. * - * @param pattern the (non-null) pattern to match against - * @param str the (non-null) string (path) to match - * @param isCaseSensitive must a case sensitive match be done? + * @param pattern The pattern to match against. Must not be + * null. + * @param str The path to match, as a String. Must not be + * null. + * @param isCaseSensitive Whether or not matching should be performed + * case sensitively. * - * @return true when the pattern matches against the string. - * false otherwise. + * @return true if the pattern matches against the string, + * or false otherwise. */ protected static boolean matchPath(String pattern, String str, boolean isCaseSensitive) { // When str starts with a File.separator, pattern has to start with a @@ -345,17 +332,8 @@ public class DirectoryScanner implements FileScanner { return false; } - Vector patDirs = new Vector(); - StringTokenizer st = new StringTokenizer(pattern,File.separator); - while (st.hasMoreTokens()) { - patDirs.addElement(st.nextToken()); - } - - Vector strDirs = new Vector(); - st = new StringTokenizer(str,File.separator); - while (st.hasMoreTokens()) { - strDirs.addElement(st.nextToken()); - } + Vector patDirs = tokenizePath (pattern); + Vector strDirs = tokenizePath (str); int patIdxStart = 0; int patIdxEnd = patDirs.size()-1; @@ -460,37 +438,40 @@ strLoop: return true; } - /** - * Matches a string against a pattern. The pattern contains two special - * characters: - * '*' which means zero or more characters, - * '?' which means one and only one character. + * Tests whether or not a string matches against a pattern. + * The pattern may contain two special characters:
+ * '*' means zero or more characters
+ * '?' means one and only one character + * + * @param pattern The pattern to match against. + * Must not be null. + * @param str The string which must be matched against the pattern. + * Must not be null. * - * @param pattern the (non-null) pattern to match against - * @param str the (non-null) string that must be matched against the - * pattern - * - * @return true when the string matches against the pattern, - * false otherwise. + * @return true if the string matches against the pattern, + * or false otherwise. */ public static boolean match(String pattern, String str) { return match(pattern, str, true); } - /** - * Matches a string against a pattern. The pattern contains two special - * characters: - * '*' which means zero or more characters, - * '?' which means one and only one character. + * Tests whether or not a string matches against a pattern. + * The pattern may contain two special characters:
+ * '*' means zero or more characters
+ * '?' means one and only one character + * + * @param pattern The pattern to match against. + * Must not be null. + * @param str The string which must be matched against the pattern. + * Must not be null. + * @param isCaseSensitive Whether or not matching should be performed + * case sensitively. * - * @param pattern the (non-null) pattern to match against - * @param str the (non-null) string that must be matched against the - * pattern * - * @return true when the string matches against the pattern, - * false otherwise. + * @return true if the string matches against the pattern, + * or false otherwise. */ protected static boolean match(String pattern, String str, boolean isCaseSensitive) { char[] patArr = pattern.toCharArray(); @@ -640,63 +621,79 @@ strLoop: return true; } - - /** - * Sets the basedir for scanning. This is the directory that is scanned - * recursively. All '/' and '\' characters are replaced by - * File.separatorChar. So the separator used need not match + * Breaks a path up into a Vector of path elements, tokenizing on + * File.separator. + * + * @param path Path to tokenize. Must not be null. + * + * @return a Vector of path elements from the tokenized path + */ + private static Vector tokenizePath (String path) { + Vector ret = new Vector(); + StringTokenizer st = new StringTokenizer(path,File.separator); + while (st.hasMoreTokens()) { + ret.addElement(st.nextToken()); + } + return ret; + } + + /** + * Sets the base directory to be scanned. This is the directory which is + * scanned recursively. All '/' and '\' characters are replaced by + * File.separatorChar, so the separator used need not match * File.separatorChar. * - * @param basedir the (non-null) basedir for scanning + * @param basedir The base directory to scan. + * Must not be null. */ public void setBasedir(String basedir) { setBasedir(new File(basedir.replace('/',File.separatorChar).replace('\\',File.separatorChar))); } - - /** - * Sets the basedir for scanning. This is the directory that is scanned - * recursively. + * Sets the base directory to be scanned. This is the directory which is + * scanned recursively. * - * @param basedir the basedir for scanning + * @param basedir The base directory for scanning. + * Should not be null. */ public void setBasedir(File basedir) { this.basedir = basedir; } - - /** - * Gets the basedir that is used for scanning. This is the directory that - * is scanned recursively. + * Returns the base directory to be scanned. + * This is the directory which is scanned recursively. * - * @return the basedir that is used for scanning + * @return the base directory to be scanned */ public File getBasedir() { return basedir; } - - /** - * Sets the case sensitivity of the file system + * Sets whether or not the file system should be regarded as case sensitive. * - * @param specifies if the filesystem is case sensitive + * @param isCaseSensitive whether or not the file system should be + * regarded as a case sensitive one */ public void setCaseSensitive(boolean isCaseSensitive) { this.isCaseSensitive = isCaseSensitive; } /** - * Sets the set of include patterns to use. All '/' and '\' characters are - * replaced by File.separatorChar. So the separator used need - * not match File.separatorChar. + * Sets the list of include patterns to use. All '/' and '\' characters + * are replaced by File.separatorChar, so the separator used + * need not match File.separatorChar. *

* When a pattern ends with a '/' or '\', "**" is appended. * - * @param includes list of include patterns + * @param includes A list of include patterns. + * May be null, indicating that all files + * should be included. If a non-null + * list is given, all elements must be + * non-null. */ public void setIncludes(String[] includes) { if (includes == null) { @@ -714,16 +711,17 @@ strLoop: } } - - /** - * Sets the set of exclude patterns to use. All '/' and '\' characters are - * replaced by File.separatorChar. So the separator used need - * not match File.separatorChar. + * Sets the list of exclude patterns to use. All '/' and '\' characters + * are replaced by File.separatorChar, so the separator used + * need not match File.separatorChar. *

* When a pattern ends with a '/' or '\', "**" is appended. * - * @param excludes list of exclude patterns + * @param excludes A list of exclude patterns. + * May be null, indicating that no files + * should be excluded. If a non-null list is + * given, all elements must be non-null. */ public void setExcludes(String[] excludes) { if (excludes == null) { @@ -742,22 +740,23 @@ strLoop: } /** - * Has the scanner excluded or omitted any files or directories it - * came accross? + * Returns whether or not the scanner has included all the files or + * directories it has come across so far. * - * @return true if all files and directories that have been found, - * are included. + * @return true if all files and directories which have + * been found so far have been included. */ public boolean isEverythingIncluded() { return everythingIncluded; } - /** - * Scans the base directory for files that match at least one include - * pattern, and don't match any exclude patterns. + * Scans the base directory for files which match at least one include + * pattern and don't match any exclude patterns. * - * @exception IllegalStateException when basedir was set incorrecly + * @exception IllegalStateException if the base directory was set + * incorrectly (i.e. if it is null, doesn't exist, + * or isn't a directory). */ public void scan() { if (basedir == null) { @@ -801,9 +800,12 @@ strLoop: } /** - * Toplevel invocation for the scan. - * - *

Returns immediately if a slow scan has already been requested. + * Top level invocation for a slow scan. A slow scan builds up a full + * list of excluded/included files/directories, whereas a fast scan + * will only have full results for included files, as it ignores + * directories which can't possibly hold any included files/directories. + *

+ * Returns immediately if a slow scan has already been completed. */ protected void slowScan() { if (haveSlowResults) { @@ -833,16 +835,17 @@ strLoop: haveSlowResults = true; } - /** - * Scans the passed dir for files and directories. Found files and + * Scans the given directory for files and directories. Found files and * directories are placed in their respective collections, based on the * matching of includes and excludes. When a directory is found, it is * scanned recursively. * - * @param dir the directory to scan - * @param vpath the path relative to the basedir (needed to prevent - * problems with an absolute path when using dir) + * @param dir The directory to scan. Must not be null. + * @param vpath The path relative to the base directory (needed to + * prevent problems with an absolute path when using + * dir). Must not be null. + * @param fast Whether or not this call is part of a fast scan. * * @see #filesIncluded * @see #filesNotIncluded @@ -850,6 +853,7 @@ strLoop: * @see #dirsIncluded * @see #dirsNotIncluded * @see #dirsExcluded + * @see #slowScan */ protected void scandir(File dir, String vpath, boolean fast) { String[] newfiles = dir.list(); @@ -909,18 +913,17 @@ strLoop: } } - - /** - * Tests whether a name matches against at least one include pattern. + * Tests whether or not a name matches against at least one include + * pattern. * - * @param name the name to match + * @param name The name to match. Must not be null. * @return true when the name matches against at least one - * include pattern, false otherwise. + * include pattern, or false otherwise. */ protected boolean isIncluded(String name) { for (int i = 0; i < includes.length; i++) { - if (matchPath(includes[i],name, isCaseSensitive)) { + if (matchPath(includes[i], name, isCaseSensitive)) { return true; } } @@ -928,11 +931,12 @@ strLoop: } /** - * Tests whether a name matches the start of at least one include pattern. + * Tests whether or not a name matches the start of at least one include + * pattern. * - * @param name the name to match - * @return true when the name matches against at least one - * include pattern, false otherwise. + * @param name The name to match. Must not be null. + * @return true when the name matches against the start of at + * least one include pattern, or false otherwise. */ protected boolean couldHoldIncluded(String name) { for (int i = 0; i < includes.length; i++) { @@ -944,11 +948,12 @@ strLoop: } /** - * Tests whether a name matches against at least one exclude pattern. + * Tests whether or not a name matches against at least one exclude + * pattern. * - * @param name the name to match + * @param name The name to match. Must not be null. * @return true when the name matches against at least one - * exclude pattern, false otherwise. + * exclude pattern, or false otherwise. */ protected boolean isExcluded(String name) { for (int i = 0; i < excludes.length; i++) { @@ -959,13 +964,13 @@ strLoop: return false; } - /** - * Get the names of the files that matched at least one of the include - * patterns, and matched none of the exclude patterns. - * The names are relative to the basedir. + * Returns the names of the files which matched at least one of the + * include patterns and none of the exclude patterns. + * The names are relative to the base directory. * - * @return the names of the files + * @return the names of the files which matched at least one of the + * include patterns and none of the exclude patterns. */ public String[] getIncludedFiles() { int count = filesIncluded.size(); @@ -976,13 +981,15 @@ strLoop: return files; } - - /** - * Get the names of the files that matched at none of the include patterns. - * The names are relative to the basedir. + * Returns the names of the files which matched none of the include + * patterns. The names are relative to the base directory. This involves + * performing a slow scan if one has not already been completed. * - * @return the names of the files + * @return the names of the files which matched none of the include + * patterns. + * + * @see #slowScan */ public String[] getNotIncludedFiles() { slowScan(); @@ -994,14 +1001,16 @@ strLoop: return files; } - - /** - * Get the names of the files that matched at least one of the include - * patterns, an matched also at least one of the exclude patterns. - * The names are relative to the basedir. + * Returns the names of the files which matched at least one of the + * include patterns and at least one of the exclude patterns. + * The names are relative to the base directory. This involves + * performing a slow scan if one has not already been completed. * - * @return the names of the files + * @return the names of the files which matched at least one of the + * include patterns and at at least one of the exclude patterns. + * + * @see #slowScan */ public String[] getExcludedFiles() { slowScan(); @@ -1013,14 +1022,13 @@ strLoop: return files; } - - /** - * Get the names of the directories that matched at least one of the include - * patterns, an matched none of the exclude patterns. - * The names are relative to the basedir. + * Returns the names of the directories which matched at least one of the + * include patterns and none of the exclude patterns. + * The names are relative to the base directory. * - * @return the names of the directories + * @return the names of the directories which matched at least one of the + * include patterns and none of the exclude patterns. */ public String[] getIncludedDirectories() { int count = dirsIncluded.size(); @@ -1031,14 +1039,15 @@ strLoop: return directories; } - - /** - * Get the names of the directories that matched at none of the include - * patterns. - * The names are relative to the basedir. + * Returns the names of the directories which matched none of the include + * patterns. The names are relative to the base directory. This involves + * performing a slow scan if one has not already been completed. * - * @return the names of the directories + * @return the names of the directories which matched none of the include + * patterns. + * + * @see #slowScan */ public String[] getNotIncludedDirectories() { slowScan(); @@ -1050,14 +1059,16 @@ strLoop: return directories; } - - /** - * Get the names of the directories that matched at least one of the include - * patterns, an matched also at least one of the exclude patterns. - * The names are relative to the basedir. - * - * @return the names of the directories + * Returns the names of the directories which matched at least one of the + * include patterns and at least one of the exclude patterns. + * The names are relative to the base directory. This involves + * performing a slow scan if one has not already been completed. + * + * @return the names of the directories which matched at least one of the + * include patterns and at least one of the exclude patterns. + * + * @see #slowScan */ public String[] getExcludedDirectories() { slowScan(); @@ -1069,11 +1080,8 @@ strLoop: return directories; } - - /** - * Adds the array with default exclusions to the current exclusions set. - * + * Adds default exclusions to the current exclusions set. */ public void addDefaultExcludes() { int excludesLength = excludes == null ? 0 : excludes.length; @@ -1087,5 +1095,4 @@ strLoop: } excludes = newExcludes; } - } diff --git a/src/main/org/apache/tools/ant/ExitException.java b/src/main/org/apache/tools/ant/ExitException.java index 09618e333..063681376 100644 --- a/src/main/org/apache/tools/ant/ExitException.java +++ b/src/main/org/apache/tools/ant/ExitException.java @@ -1,7 +1,7 @@ /* * The Apache Software License, Version 1.1 * - * Copyright (c) 2001 The Apache Software Foundation. All rights + * Copyright (c) 2001-2002 The Apache Software Foundation. All rights * reserved. * * Redistribution and use in source and binary forms, with or without @@ -62,6 +62,7 @@ package org.apache.tools.ant; */ public class ExitException extends SecurityException { + /** Status code */ private int status; /** diff --git a/src/main/org/apache/tools/ant/FileScanner.java b/src/main/org/apache/tools/ant/FileScanner.java index 86075a1a5..e3224819e 100644 --- a/src/main/org/apache/tools/ant/FileScanner.java +++ b/src/main/org/apache/tools/ant/FileScanner.java @@ -1,7 +1,7 @@ /* * The Apache Software License, Version 1.1 * - * Copyright (c) 2000-2001 The Apache Software Foundation. All rights + * Copyright (c) 2000-2002 The Apache Software Foundation. All rights * reserved. * * Redistribution and use in source and binary forms, with or without @@ -56,107 +56,138 @@ package org.apache.tools.ant; import java.io.File; /** - * An interface used to describe the actions required by any type of + * An interface used to describe the actions required of any type of * directory scanner. */ public interface FileScanner { /** - * Adds an array with default exclusions to the current exclusions set. - * + * Adds default exclusions to the current exclusions set. */ void addDefaultExcludes(); + /** - * Gets the basedir that is used for scanning. This is the directory that - * is scanned recursively. + * Returns the base directory to be scanned. + * This is the directory which is scanned recursively. * - * @return the basedir that is used for scanning + * @return the base directory to be scanned */ File getBasedir(); + /** - * Get the names of the directories that matched at least one of the include - * patterns, an matched also at least one of the exclude patterns. - * The names are relative to the basedir. - * - * @return the names of the directories + * Returns the names of the directories which matched at least one of the + * include patterns and at least one of the exclude patterns. + * The names are relative to the base directory. + * + * @return the names of the directories which matched at least one of the + * include patterns and at least one of the exclude patterns. */ String[] getExcludedDirectories(); + /** - * Get the names of the files that matched at least one of the include - * patterns, an matched also at least one of the exclude patterns. - * The names are relative to the basedir. + * Returns the names of the files which matched at least one of the + * include patterns and at least one of the exclude patterns. + * The names are relative to the base directory. * - * @return the names of the files - */ + * @return the names of the files which matched at least one of the + * include patterns and at at least one of the exclude patterns. + * + */ String[] getExcludedFiles(); + /** - * Get the names of the directories that matched at least one of the include - * patterns, an matched none of the exclude patterns. - * The names are relative to the basedir. + * Returns the names of the directories which matched at least one of the + * include patterns and none of the exclude patterns. + * The names are relative to the base directory. * - * @return the names of the directories + * @return the names of the directories which matched at least one of the + * include patterns and none of the exclude patterns. */ String[] getIncludedDirectories(); + /** - * Get the names of the files that matched at least one of the include - * patterns, an matched none of the exclude patterns. - * The names are relative to the basedir. + * Returns the names of the files which matched at least one of the + * include patterns and none of the exclude patterns. + * The names are relative to the base directory. * - * @return the names of the files + * @return the names of the files which matched at least one of the + * include patterns and none of the exclude patterns. */ String[] getIncludedFiles(); + /** - * Get the names of the directories that matched at none of the include - * patterns. - * The names are relative to the basedir. + * Returns the names of the directories which matched none of the include + * patterns. The names are relative to the base directory. * - * @return the names of the directories - */ + * @return the names of the directories which matched none of the include + * patterns. + */ String[] getNotIncludedDirectories(); + /** - * Get the names of the files that matched at none of the include patterns. - * The names are relative to the basedir. + * Returns the names of the files which matched none of the include + * patterns. The names are relative to the base directory. * - * @return the names of the files + * @return the names of the files which matched none of the include + * patterns. */ String[] getNotIncludedFiles(); + /** - * Scans the base directory for files that match at least one include - * pattern, and don't match any exclude patterns. + * Scans the base directory for files which match at least one include + * pattern and don't match any exclude patterns. * - * @exception IllegalStateException when basedir was set incorrecly + * @exception IllegalStateException if the base directory was set + * incorrectly (i.e. if it is null, doesn't exist, + * or isn't a directory). */ void scan(); + /** - * Sets the basedir for scanning. This is the directory that is scanned - * recursively. + * Sets the base directory to be scanned. This is the directory which is + * scanned recursively. All '/' and '\' characters should be replaced by + * File.separatorChar, so the separator used need not match + * File.separatorChar. * - * @param basedir the (non-null) basedir for scanning + * @param basedir The base directory to scan. + * Must not be null. */ void setBasedir(String basedir); + /** - * Sets the basedir for scanning. This is the directory that is scanned - * recursively. + * Sets the base directory to be scanned. This is the directory which is + * scanned recursively. * - * @param basedir the basedir for scanning + * @param basedir The base directory for scanning. + * Should not be null. */ void setBasedir(File basedir); + /** - * Sets the set of exclude patterns to use. + * Sets the list of exclude patterns to use. * - * @param excludes list of exclude patterns - */ + * @param excludes A list of exclude patterns. + * May be null, indicating that no files + * should be excluded. If a non-null list is + * given, all elements must be non-null. + */ void setExcludes(String[] excludes); + /** - * Sets the set of include patterns to use. + * Sets the list of include patterns to use. * - * @param includes list of include patterns + * @param includes A list of include patterns. + * May be null, indicating that all files + * should be included. If a non-null + * list is given, all elements must be + * non-null. */ void setIncludes(String[] includes); /** - * Sets the case sensitivity of the file system + * Sets whether or not the file system should be regarded as case sensitive. * - * @param specifies if the filesystem is case sensitive + * @param isCaseSensitive whether or not the file system should be + * regarded as a case sensitive one */ void setCaseSensitive(boolean isCaseSensitive); }