From 88e1208306a1cf415715a172da65980378a4fe7a Mon Sep 17 00:00:00 2001 From: Matthew Jason Benson Date: Fri, 10 Dec 2004 18:28:45 +0000 Subject: [PATCH] Javadoc and LOC bumming git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@277168 13f79535-47bb-0310-9956-ffa450edef68 --- .../tools/ant/types/AbstractFileSet.java | 203 +++++++++--------- 1 file changed, 99 insertions(+), 104 deletions(-) diff --git a/src/main/org/apache/tools/ant/types/AbstractFileSet.java b/src/main/org/apache/tools/ant/types/AbstractFileSet.java index 402b3631d..52da4f33b 100644 --- a/src/main/org/apache/tools/ant/types/AbstractFileSet.java +++ b/src/main/org/apache/tools/ant/types/AbstractFileSet.java @@ -66,10 +66,18 @@ public abstract class AbstractFileSet extends DataType implements Cloneable, private boolean isCaseSensitive = true; private boolean followSymlinks = true; + /** + * Construct a new AbstractFileSet. + */ public AbstractFileSet() { super(); } + /** + * Construct a new AbstractFileSet, shallowly cloned + * from the specified AbstractFileSet. + * @param fileset the AbstractFileSet to use as a template. + */ protected AbstractFileSet(AbstractFileSet fileset) { this.dir = fileset.dir; this.defaultPatterns = fileset.defaultPatterns; @@ -86,6 +94,7 @@ public abstract class AbstractFileSet extends DataType implements Cloneable, * *

You must not set another attribute or nest elements inside * this element if you make it a reference.

+ * @param r the Reference to use. */ public void setRefid(Reference r) throws BuildException { if (dir != null || defaultPatterns.hasPatterns(getProject())) { @@ -102,17 +111,20 @@ public abstract class AbstractFileSet extends DataType implements Cloneable, /** * Sets the base-directory for this instance. + * @param dir the directory's File instance. */ public void setDir(File dir) throws BuildException { if (isReference()) { throw tooManyAttributes(); } - this.dir = dir; } /** * Retrieves the base-directory for this instance. + * @param p the Project against which the + * reference is resolved, if set. + * @return File. */ public File getDir(Project p) { if (isReference()) { @@ -123,6 +135,7 @@ public abstract class AbstractFileSet extends DataType implements Cloneable, /** * Creates a nested patternset. + * @return PatternSet. */ public PatternSet createPatternSet() { if (isReference()) { @@ -134,7 +147,8 @@ public abstract class AbstractFileSet extends DataType implements Cloneable, } /** - * add a name entry on the include list + * Add a name entry to the include list. + * @return PatternSet.NameEntry. */ public PatternSet.NameEntry createInclude() { if (isReference()) { @@ -144,7 +158,8 @@ public abstract class AbstractFileSet extends DataType implements Cloneable, } /** - * add a name entry on the include files list + * Add a name entry to the include files list. + * @return PatternSet.NameEntry. */ public PatternSet.NameEntry createIncludesFile() { if (isReference()) { @@ -154,7 +169,8 @@ public abstract class AbstractFileSet extends DataType implements Cloneable, } /** - * add a name entry on the exclude list + * Add a name entry to the exclude list. + * @return PatternSet.NameEntry. */ public PatternSet.NameEntry createExclude() { if (isReference()) { @@ -164,7 +180,8 @@ public abstract class AbstractFileSet extends DataType implements Cloneable, } /** - * add a name entry on the excludes files list + * Add a name entry to the excludes files list. + * @return PatternSet.NameEntry. */ public PatternSet.NameEntry createExcludesFile() { if (isReference()) { @@ -175,15 +192,15 @@ public abstract class AbstractFileSet extends DataType implements Cloneable, /** * Creates a single file fileset. + * @param file the single File included in this + * AbstractFileSet. */ public void setFile(File file) { if (isReference()) { throw tooManyAttributes(); } setDir(file.getParentFile()); - - PatternSet.NameEntry include = createInclude(); - include.setName(file.getName()); + createInclude().setName(file.getName()); } /** @@ -192,13 +209,12 @@ public abstract class AbstractFileSet extends DataType implements Cloneable, * *

Patterns may be separated by a comma or a space.

* - * @param includes the string containing the include patterns + * @param includes the String containing the include patterns. */ public void setIncludes(String includes) { if (isReference()) { throw tooManyAttributes(); } - defaultPatterns.setIncludes(includes); } @@ -208,62 +224,55 @@ public abstract class AbstractFileSet extends DataType implements Cloneable, * *

Patterns may be separated by a comma or a space.

* - * @param excludes the string containing the exclude patterns + * @param excludes the String containing the exclude patterns. */ public void setExcludes(String excludes) { if (isReference()) { throw tooManyAttributes(); } - defaultPatterns.setExcludes(excludes); } /** - * Sets the name of the file containing the includes patterns. + * Sets the File containing the includes patterns. * - * @param incl The file to fetch the include patterns from. + * @param incl File instance. */ public void setIncludesfile(File incl) throws BuildException { if (isReference()) { throw tooManyAttributes(); } - defaultPatterns.setIncludesfile(incl); } /** - * Sets the name of the file containing the excludes patterns. + * Sets the File containing the excludes patterns. * - * @param excl The file to fetch the exclude patterns from. + * @param excl File instance. */ public void setExcludesfile(File excl) throws BuildException { if (isReference()) { throw tooManyAttributes(); } - defaultPatterns.setExcludesfile(excl); } /** * Sets whether default exclusions should be used or not. * - * @param useDefaultExcludes "true"|"on"|"yes" when default exclusions - * should be used, "false"|"off"|"no" when they - * shouldn't be used. + * @param useDefaultExcludes boolean. */ public void setDefaultexcludes(boolean useDefaultExcludes) { if (isReference()) { throw tooManyAttributes(); } - this.useDefaultExcludes = useDefaultExcludes; } /** - * Sets case sensitivity of the file system + * Sets case sensitivity of the file system. * - * @param isCaseSensitive "true"|"on"|"yes" if file system is case - * sensitive, "false"|"off"|"no" when not. + * @param isCaseSensitive boolean. */ public void setCaseSensitive(boolean isCaseSensitive) { if (isReference()) { @@ -275,7 +284,7 @@ public abstract class AbstractFileSet extends DataType implements Cloneable, /** * Sets whether or not symbolic links should be followed. * - * @param followSymlinks whether or not symbolic links should be followed + * @param followSymlinks whether or not symbolic links should be followed. */ public void setFollowSymlinks(boolean followSymlinks) { if (isReference()) { @@ -285,22 +294,21 @@ public abstract class AbstractFileSet extends DataType implements Cloneable, } /** - * find out if the fileset wants to follow symbolic links + * Find out if the fileset wants to follow symbolic links. * - * @return flag indicating whether or not symbolic links should be followed + * @return boolean indicating whether symbolic links + * should be followed. * - * @since ant 1.6 + * @since Ant 1.6 */ public boolean isFollowSymlinks() { - if (isReference()) { - return getRef(getProject()).isFollowSymlinks(); - } else { - return followSymlinks; - } + return (isReference()) + ? getRef(getProject()).isFollowSymlinks() : followSymlinks; } /** - * sets the name used for this datatype instance. + * Gets as descriptive as possible a name used for this datatype instance. + * @return String name. */ protected String getDataTypeName() { // look up the types in project and see if they match this class @@ -315,29 +323,22 @@ public abstract class AbstractFileSet extends DataType implements Cloneable, } } } - String classname = getClass().getName(); - - int dotIndex = classname.lastIndexOf("."); - if (dotIndex == -1) { - return classname; - } - return classname.substring(dotIndex + 1); + return classname.substring(classname.lastIndexOf('.') + 1); } /** * Returns the directory scanner needed to access the files to process. + * @return a DirectoryScanner instance. */ public DirectoryScanner getDirectoryScanner(Project p) { if (isReference()) { return getRef(p).getDirectoryScanner(p); } - if (dir == null) { throw new BuildException("No directory specified for " + getDataTypeName() + "."); } - if (!dir.exists()) { throw new BuildException(dir.getAbsolutePath() + " not found."); } @@ -345,7 +346,6 @@ public abstract class AbstractFileSet extends DataType implements Cloneable, throw new BuildException(dir.getAbsolutePath() + " is not a directory."); } - DirectoryScanner ds = new DirectoryScanner(); setupDirectoryScanner(ds, p); ds.setFollowSymlinks(followSymlinks); @@ -353,16 +353,19 @@ public abstract class AbstractFileSet extends DataType implements Cloneable, return ds; } + /** + * Set up the specified directory scanner against the specified project. + * @param ds a FileScanner instance. + * @param p an Ant Project instance. + */ public void setupDirectoryScanner(FileScanner ds, Project p) { if (isReference()) { getRef(p).setupDirectoryScanner(ds, p); return; } - if (ds == null) { throw new IllegalArgumentException("ds cannot be null"); } - ds.setBasedir(dir); final int count = additionalPatterns.size(); @@ -370,7 +373,6 @@ public abstract class AbstractFileSet extends DataType implements Cloneable, Object o = additionalPatterns.elementAt(i); defaultPatterns.append((PatternSet) o, p); } - p.log(getDataTypeName() + ": Setup scanner in dir " + dir + " with " + defaultPatterns, Project.MSG_DEBUG); @@ -380,7 +382,6 @@ public abstract class AbstractFileSet extends DataType implements Cloneable, SelectorScanner ss = (SelectorScanner) ds; ss.setSelectors(getSelectors(p)); } - if (useDefaultExcludes) { ds.addDefaultExcludes(); } @@ -397,7 +398,6 @@ public abstract class AbstractFileSet extends DataType implements Cloneable, stk.push(this); dieOnCircularReference(stk, p); } - Object o = getRefid().getReferencedObject(p); if (!getClass().isAssignableFrom(o.getClass())) { String msg = getRefid().getRefId() + " doesn\'t denote a " @@ -413,7 +413,7 @@ public abstract class AbstractFileSet extends DataType implements Cloneable, /** * Indicates whether there are any selectors here. * - * @return whether any selectors are in this container + * @return whether any selectors are in this container. */ public boolean hasSelectors() { if (isReference() && getProject() != null) { @@ -425,17 +425,15 @@ public abstract class AbstractFileSet extends DataType implements Cloneable, /** * Indicates whether there are any patterns here. * - * @return whether any patterns are in this container + * @return whether any patterns are in this container. */ public boolean hasPatterns() { if (isReference() && getProject() != null) { return getRef(getProject()).hasPatterns(); } - if (defaultPatterns.hasPatterns(getProject())) { return true; } - Enumeration e = additionalPatterns.elements(); while (e.hasMoreElements()) { PatternSet ps = (PatternSet) e.nextElement(); @@ -443,14 +441,13 @@ public abstract class AbstractFileSet extends DataType implements Cloneable, return true; } } - return false; } /** - * Gives the count of the number of selectors in this container + * Gives the count of the number of selectors in this container. * - * @return the number of selectors in this container + * @return the number of selectors in this container as an int. */ public int selectorCount() { if (isReference() && getProject() != null) { @@ -462,22 +459,20 @@ public abstract class AbstractFileSet extends DataType implements Cloneable, /** * Returns the set of selectors as an array. * - * @return an array of selectors in this container + * @return a FileSelector[] of the selectors in this container. */ public FileSelector[] getSelectors(Project p) { if (isReference()) { return getRef(p).getSelectors(p); - } else { - FileSelector[] result = new FileSelector[selectors.size()]; - selectors.copyInto(result); - return result; } + return (FileSelector[])(selectors.toArray( + new FileSelector[selectors.size()])); } /** * Returns an enumerator for accessing the set of selectors. * - * @return an enumerator that goes through each of the selectors + * @return an Enumeration of selectors. */ public Enumeration selectorElements() { if (isReference() && getProject() != null) { @@ -489,7 +484,7 @@ public abstract class AbstractFileSet extends DataType implements Cloneable, /** * Add a new selector into this container. * - * @param selector the new selector to add + * @param selector the new FileSelector to add. */ public void appendSelector(FileSelector selector) { if (isReference()) { @@ -501,144 +496,144 @@ public abstract class AbstractFileSet extends DataType implements Cloneable, /* Methods below all add specific selectors */ /** - * add a "Select" selector entry on the selector list - * @param selector the selector to add + * Add a "Select" selector entry on the selector list. + * @param selector the SelectSelector to add. */ public void addSelector(SelectSelector selector) { appendSelector(selector); } /** - * add an "And" selector entry on the selector list - * @param selector the selector to add + * Add an "And" selector entry on the selector list. + * @param selector the AndSelector to add. */ public void addAnd(AndSelector selector) { appendSelector(selector); } /** - * add an "Or" selector entry on the selector list - * @param selector the selector to add + * Add an "Or" selector entry on the selector list. + * @param selector the OrSelector to add. */ public void addOr(OrSelector selector) { appendSelector(selector); } /** - * add a "Not" selector entry on the selector list - * @param selector the selector to add + * Add a "Not" selector entry on the selector list. + * @param selector the NotSelector to add. */ public void addNot(NotSelector selector) { appendSelector(selector); } /** - * add a "None" selector entry on the selector list - * @param selector the selector to add + * Add a "None" selector entry on the selector list. + * @param selector the NoneSelector to add. */ public void addNone(NoneSelector selector) { appendSelector(selector); } /** - * add a majority selector entry on the selector list - * @param selector the selector to add + * Add a majority selector entry on the selector list. + * @param selector the MajoritySelector to add. */ public void addMajority(MajoritySelector selector) { appendSelector(selector); } /** - * add a selector date entry on the selector list - * @param selector the selector to add + * Add a selector date entry on the selector list. + * @param selector the DateSelector to add. */ public void addDate(DateSelector selector) { appendSelector(selector); } /** - * add a selector size entry on the selector list - * @param selector the selector to add + * Add a selector size entry on the selector list. + * @param selector the SizeSelector to add. */ public void addSize(SizeSelector selector) { appendSelector(selector); } /** - * add a DifferentSelector entry on the selector list - * @param selector the selector to add + * Add a DifferentSelector entry on the selector list. + * @param selector the DifferentSelector to add. */ public void addDifferent(DifferentSelector selector) { appendSelector(selector); } /** - * add a selector filename entry on the selector list - * @param selector the selector to add + * Add a selector filename entry on the selector list. + * @param selector the FilenameSelector to add. */ public void addFilename(FilenameSelector selector) { appendSelector(selector); } /** - * add a selector type entry on the selector list - * @param selector the selector to add + * Add a selector type entry on the selector list. + * @param selector the TypeSelector to add. */ public void addType(TypeSelector selector) { appendSelector(selector); } /** - * add an extended selector entry on the selector list - * @param selector the selector to add + * Add an extended selector entry on the selector list. + * @param selector the ExtendSelector to add. */ public void addCustom(ExtendSelector selector) { appendSelector(selector); } /** - * add a contains selector entry on the selector list - * @param selector the selector to add + * Add a contains selector entry on the selector list. + * @param selector the ContainsSelector to add. */ public void addContains(ContainsSelector selector) { appendSelector(selector); } /** - * add a present selector entry on the selector list - * @param selector the selector to add + * Add a present selector entry on the selector list. + * @param selector the PresentSelector to add. */ public void addPresent(PresentSelector selector) { appendSelector(selector); } /** - * add a depth selector entry on the selector list - * @param selector the selector to add + * Add a depth selector entry on the selector list. + * @param selector the DepthSelector to add. */ public void addDepth(DepthSelector selector) { appendSelector(selector); } /** - * add a depends selector entry on the selector list - * @param selector the selector to add + * Add a depends selector entry on the selector list. + * @param selector the DependSelector to add. */ public void addDepend(DependSelector selector) { appendSelector(selector); } /** - * add a regular expression selector entry on the selector list - * @param selector the selector to add + * Add a regular expression selector entry on the selector list. + * @param selector the ContainsRegexpSelector to add. */ public void addContainsRegexp(ContainsRegexpSelector selector) { appendSelector(selector); } /** - * add the modified selector - * @param selector the selector to add + * Add the modified selector. + * @param selector the ModifiedSelector to add. * @since ant 1.6 */ public void addModified(ModifiedSelector selector) { @@ -646,8 +641,8 @@ public abstract class AbstractFileSet extends DataType implements Cloneable, } /** - * add an arbitary selector - * @param selector the selector to add + * Add an arbitary selector. + * @param selector the FileSelector to add. * @since Ant 1.6 */ public void add(FileSelector selector) { @@ -655,9 +650,9 @@ public abstract class AbstractFileSet extends DataType implements Cloneable, } /** - * Returns included files as a list of semicolon-separated filenames + * Returns included files as a list of semicolon-separated filenames. * - * @return String object with included filenames + * @return a String of included filenames. */ public String toString() { DirectoryScanner ds = getDirectoryScanner(getProject());