ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jsk...@apache.org
Subject cvs commit: jakarta-ant/src/main/org/apache/tools/ant PathTokenizer.java NoBannerLogger.java Main.java Location.java
Date Sun, 24 Feb 2002 08:55:28 GMT
jskeet      02/02/24 00:55:28

  Modified:    src/main/org/apache/tools/ant PathTokenizer.java
                        NoBannerLogger.java Main.java Location.java
  Log:
  JavaDoc comments.
  
  Revision  Changes    Path
  1.7       +27 -5     jakarta-ant/src/main/org/apache/tools/ant/PathTokenizer.java
  
  Index: PathTokenizer.java
  ===================================================================
  RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/PathTokenizer.java,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- PathTokenizer.java	10 Jan 2002 11:21:19 -0000	1.6
  +++ PathTokenizer.java	24 Feb 2002 08:55:28 -0000	1.7
  @@ -1,7 +1,7 @@
   /*
    * The Apache Software License, Version 1.1
    *
  - * Copyright (c) 2000 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
  @@ -62,7 +62,7 @@
    * that path.
    *
    * The path can use path separators of either ':' or ';' and file separators
  - * of either '/' or '\'
  + * of either '/' or '\'.
    *
    * @author Conor MacNeill (conor@ieee.org)
    *
  @@ -74,21 +74,35 @@
       private StringTokenizer tokenizer;
       
       /**
  -     * A String which stores any path components which have been read ahead.
  +     * A String which stores any path components which have been read ahead
  +     * due to DOS filesystem compensation.
        */
       private String lookahead = null;
   
       /**
  -     * Flag to indicate whether we are running on a platform with a DOS style
  -     * filesystem
  +     * Flag to indicate whether or not we are running on a platform with a
  +     * DOS style filesystem
        */
       private boolean dosStyleFilesystem;
   
  +    /**
  +     * Constructs a path tokenizer for the specified path.
  +     * 
  +     * @param path The path to tokenize. Must not be <code>null</code>.
  +     */
       public PathTokenizer(String path) {
          tokenizer = new StringTokenizer(path, ":;", false);
          dosStyleFilesystem = File.pathSeparatorChar == ';'; 
       }
   
  +    /**
  +     * Tests if there are more path elements available from this tokenizer's
  +     * path. If this method returns <code>true</code>, then a subsequent call

  +     * to nextToken will successfully return a token.
  +     * 
  +     * @return <code>true</code> if and only if there is at least one token

  +     * in the string after the current position; <code>false</code> otherwise.
  +     */
       public boolean hasMoreTokens() {
           if (lookahead != null) {
               return true;
  @@ -97,6 +111,14 @@
           return tokenizer.hasMoreTokens();
       }
       
  +    /**
  +     * Returns the next path element from this tokenizer.
  +     * 
  +     * @return the next path element from this tokenizer.
  +     * 
  +     * @exception NoSuchElementException if there are no more elements in this 
  +     *            tokenizer's path.
  +     */
       public String nextToken() throws NoSuchElementException {
           String token = null;
           if (lookahead != null) {
  
  
  
  1.6       +29 -1     jakarta-ant/src/main/org/apache/tools/ant/NoBannerLogger.java
  
  Index: NoBannerLogger.java
  ===================================================================
  RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/NoBannerLogger.java,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- NoBannerLogger.java	10 Jan 2002 11:21:19 -0000	1.5
  +++ NoBannerLogger.java	24 Feb 2002 08:55:28 -0000	1.6
  @@ -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
  @@ -63,16 +63,44 @@
    */
   public class NoBannerLogger extends DefaultLogger {
   
  +    /** 
  +     * Name of the current target, if it should
  +     * be displayed on the next message. This is
  +     * set when a target starts building, and reset
  +     * to <code>null</code> after the first message for 
  +     * the target is logged.
  +     */
       protected String targetName;
   
  +    /** Sole constructor. */
  +    public NoBannerLogger() {
  +    }
  +
  +    /**
  +     * Notes the name of the target so it can be logged
  +     * if it generates any messages.
  +     * 
  +     * @param event A BuildEvent containing target information.
  +     *              Must not be <code>null</code>.
  +     */
       public void targetStarted(BuildEvent event) {
           targetName = event.getTarget().getName();
       }
   
  +    /** Resets the current target name to <code>null</code>. */
       public void targetFinished(BuildEvent event) {
           targetName = null;
       }
   
  +    /**
  +     * Logs a message for a target if it is of an appropriate
  +     * priority, also logging the name of the target if this
  +     * is the first message which needs to be logged for the
  +     * target.
  +     * 
  +     * @param event A BuildEvent containing message information.
  +     *              Must not be <code>null</code>.
  +     */
       public void messageLogged(BuildEvent event) {
   
           if( event.getPriority() > msgOutputLevel ||
  
  
  
  1.57      +126 -41   jakarta-ant/src/main/org/apache/tools/ant/Main.java
  
  Index: Main.java
  ===================================================================
  RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/Main.java,v
  retrieving revision 1.56
  retrieving revision 1.57
  diff -u -r1.56 -r1.57
  --- Main.java	2 Feb 2002 00:13:32 -0000	1.56
  +++ Main.java	24 Feb 2002 08:55:28 -0000	1.57
  @@ -78,57 +78,63 @@
    */
   public class Main {
   
  -    /** The default build file name */
  +    /** The default build file name. */
       public final static String DEFAULT_BUILD_FILENAME = "build.xml";
   
  -    /** Our current message output status. Follows Project.MSG_XXX */
  +    /** Our current message output status. Follows Project.MSG_XXX. */
       private int msgOutputLevel = Project.MSG_INFO;
   
  -    /** File that we are using for configuration */
  -    private File buildFile; /** null */
  +    /** File that we are using for configuration. */
  +    private File buildFile; /* null */
   
  -    /** Stream that we are using for logging */
  +    /** Stream to use for logging. */
       private PrintStream out = System.out;
   
  -    /** Stream that we are using for logging error messages */
  +    /** Stream that we are using for logging error messages. */
       private PrintStream err = System.err;
   
  -    /** The build targets */
  +    /** The build targets. */
       private Vector targets = new Vector(5);
   
  -    /** Set of properties that can be used by tasks */
  +    /** Set of properties that can be used by tasks. */
       private Properties definedProps = new Properties();
   
  -    /** Names of classes to add as listeners to project */
  +    /** Names of classes to add as listeners to project. */
       private Vector listeners = new Vector(5);
       
  -    /** File names of property files to load on startup */
  +    /** File names of property files to load on startup. */
       private Vector propertyFiles = new Vector(5);
  -
  +    
       /**
  -     * The Ant logger class. There may be only one logger. It will have the
  -     * right to use the 'out' PrintStream. The class must implements the BuildLogger
  -     * interface
  +     * The Ant logger class. There may be only one logger. It will have 
  +     * the right to use the 'out' PrintStream. The class must implements the 
  +     * BuildLogger interface.
        */
       private String loggerClassname = null;
   
       /**
  -     * Indicates whether output to the log is to be unadorned.
  +     * Whether or not output to the log is to be unadorned.
        */
       private boolean emacsMode = false;
   
       /**
  -     * Indicates if this ant should be run.
  +     * Whether or not this instance has successfully been
  +     * constructed and is ready to run.
        */
       private boolean readyToRun = false;
   
       /**
  -     * Indicates we should only parse and display the project help information
  +     * Whether or not we should only parse and display the project help 
  +     * information.
        */
       private boolean projectHelp = false;
   
       /**
  -     * Prints the message of the Throwable if it's not null.
  +     * Prints the message of the Throwable if it (the message) is not 
  +     * <code>null</code>.
  +     * 
  +     * @param t Throwable to print the message of.
  +     *          Must not be <code>null</code>.
        */
       private static void printMessage(Throwable t) {
           String message = t.getMessage();
  @@ -138,7 +144,16 @@
       }
   
       /**
  -     * Entry point method.
  +     * Creates a new instance of this class using the
  +     * arguments specified, gives it any extra user properties which have been
  +     * specified, and then runs the build using the classloader provided.
  +     * 
  +     * @param args Command line arguments. Must not be <code>null</code>.
  +     * @param additionalUserProperties Any extra properties to use in this 
  +     *        build. May be <code>null</code>, which is the equivalent to 
  +     *        passing in an empty set of properties.
  +     * @param coreLoader Classloader used for core classes. May be 
  +     *        <code>null</code> in which case the system classloader is used.
        */
       public static void start(String[] args, Properties additionalUserProperties,
                                ClassLoader coreLoader) {
  @@ -173,20 +188,31 @@
               System.exit(1);
           }
       }
  -                                 
  -    
  -    
  +                                        
       /**
        * Command line entry point. This method kicks off the building
        * of a project object and executes a build using either a given
        * target or the default target.
        *
  -     * @param args Command line args.
  +     * @param args Command line arguments. Must not be <code>null</code>.
        */
       public static void main(String[] args) {
           start(args, null, null);
       }
   
  +    // XXX: (Jon Skeet) Error handling appears to be inconsistent here.
  +    // Sometimes there's just a return statement, and sometimes a
  +    // BuildException is thrown. What's the rationale for when to do
  +    // what?
  +    /**
  +     * Sole constructor, which parses and deals with command line 
  +     * arguments.
  +     * 
  +     * @param args Command line arguments. Must not be <code>null</code>.
  +     * 
  +     * @exception BuildException if the specified build file doesn't exist
  +     *                           or is a directory.
  +     */
       protected Main(String[] args) throws BuildException {
   
           String searchForThis = null;
  @@ -253,7 +279,7 @@
   
                   /* Interestingly enough, we get to here when a user
                    * uses -Dname=value. However, in some cases, the JDK
  -                 * goes ahead * and parses this out to args
  +                 * goes ahead and parses this out to args
                    *   {"-Dname", "value"}
                    * so instead of parsing on "=", we just make the "-D"
                    * characters go away and skip one argument forward.
  @@ -383,10 +409,10 @@
   
       /**
        * Helper to get the parent file for a given file.
  +     * <p>
  +     * Added to simulate File.getParentFile() from JDK 1.2.
        *
  -     * <P>Added to simulate File.getParentFile() from JDK 1.2.
  -     *
  -     * @param file   File
  +     * @param file   File to find parent of. Must not be <code>null</code>.
        * @return       Parent file or null if none
        */
       private File getParentFile(File file) {
  @@ -403,16 +429,20 @@
   
       /**
        * Search parent directories for the build file.
  +     * <p>
  +     * Takes the given target as a suffix to append to each
  +     * parent directory in seach of a build file.  Once the
  +     * root of the file-system has been reached an exception
  +     * is thrown.
        *
  -     * <P>Takes the given target as a suffix to append to each
  -     *    parent directory in seach of a build file.  Once the
  -     *    root of the file-system has been reached an exception
  -     *    is thrown.
  +     * @param start  Leaf directory of search.
  +     *               Must not be <code>null</code>.
  +     * @param suffix  Suffix filename to look for in parents.
  +     *                Must not be <code>null</code>.
  +     * 
  +     * @return A handle to the build file if one is found
        *
  -     * @param suffix    Suffix filename to look for in parents.
  -     * @return          A handle to the build file
  -     *
  -     * @exception BuildException    Failed to locate a build file
  +     * @exception BuildException if no build file is found
        */
       private File findBuildFile(String start, String suffix) throws BuildException {
           if (msgOutputLevel >= Project.MSG_INFO) {
  @@ -441,7 +471,15 @@
       }
   
       /**
  -     * Executes the build.
  +     * Executes the build. If the constructor for this instance failed
  +     * (e.g. returned after issuing a warning), this method returns
  +     * immediately.
  +     * 
  +     * @param coreLoader The classloader to use to find core classes.
  +     *                   May be <code>null</code>, in which case the
  +     *                   system classloader is used.
  +     * 
  +     * @exception BuildException if the build fails
        */
       private void runBuild(ClassLoader coreLoader) throws BuildException {
   
  @@ -552,6 +590,13 @@
           }
       }
   
  +    /**
  +     * Adds the listeners specified in the command line arguments,
  +     * along with the default listener, to the specified project.
  +     * 
  +     * @param project The project to add listeners to.
  +     *                Must not be <code>null</code>.
  +     */
       protected void addBuildListeners(Project project) {
   
           // Add the default listener
  @@ -570,6 +615,10 @@
           }
       }
   
  +    // XXX: (Jon Skeet) Any reason for writing a message and then using a bare 
  +    // RuntimeException rather than just using a BuildException here? Is it
  +    // in case the message could end up being written to no loggers (as the loggers
  +    // could have failed to be created due to this failure)?
       /**
        *  Creates the default build logger for sending build events to the ant log.
        */
  @@ -603,7 +652,7 @@
       }
   
       /**
  -     * Prints the usage of how to use this class to System.out
  +     * Prints the usage information for this class to <code>System.out</code>.
        */
       private static void printUsage() {
           String lSep = System.getProperty("line.separator");
  @@ -629,12 +678,30 @@
           System.out.println(msg.toString());
       }
   
  +    /**
  +     * Prints the Ant version information to <code>System.out</code>.
  +     * 
  +     * @exception BuildException if the version information is unavailable
  +     */
       private static void printVersion() throws BuildException {
           System.out.println(getAntVersion());
       }
   
  +    /**
  +     * Cache of the Ant version information when it has been loaded.
  +     */
       private static String antVersion = null;
   
  +    /**
  +     * Returns the Ant version information, if available. Once the information
  +     * has been loaded once, it's cached and returned from the cache on future
  +     * calls.
  +     * 
  +     * @return the Ant version information as a String 
  +     *         (always non-<code>null</code>)
  +     * 
  +     * @exception BuildException if the version information is unavailable
  +     */
       public static synchronized String getAntVersion() throws BuildException {
           if (antVersion == null) {
               try {
  @@ -662,7 +729,11 @@
       }
   
        /**
  -      * Print the project description, if any
  +      * Prints the description of a project (if there is one) to 
  +      * <code>System.out</code>.
  +      * 
  +      * @param project The project to display a description of.
  +      *                Must not be <code>null</code>.
         */
       private static void printDescription(Project project) {
          if (project.getDescription() != null) {
  @@ -671,7 +742,13 @@
       }
   
       /**
  -     * Print out a list of all targets in the current buildfile
  +     * Prints a list of all targets in the specified project to 
  +     * <code>System.out</code>, optionally including subtargets.
  +     * 
  +     * @param project The project to display a description of.
  +     *                Must not be <code>null</code>.
  +     * @param printSubTargets Whether or not subtarget names should also be
  +     *                        printed.
        */
       private static void printTargets(Project project, boolean printSubTargets) {
           // find the target with the longest name
  @@ -717,7 +794,14 @@
       }
   
       /**
  -     * Search for the insert position to keep names a sorted list of Strings
  +     * Searches for the correct place to insert a name into a list so as
  +     * to keep the list sorted alphabetically.
  +     * 
  +     * @param names The current list of names. Must not be <code>null</code>.
  +     * @param name  The name to find a place for.
  +     *              Must not be <code>null</code>.
  +     * 
  +     * @return the correct place in the list for the given name
        */
       private static int findTargetPosition(Vector names, String name) {
           int res = names.size();
  @@ -730,7 +814,8 @@
       }
   
       /**
  -     * Output a formatted list of target names with an optional description
  +     * Writes a formatted list of target names to <code>System.out</code>
  +     * with an optional description
        */
       private static void printTargets(Vector names, Vector descriptions, String heading,
int maxlen) {
           // now, start printing the targets and their descriptions
  
  
  
  1.6       +33 -7     jakarta-ant/src/main/org/apache/tools/ant/Location.java
  
  Index: Location.java
  ===================================================================
  RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/Location.java,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- Location.java	10 Jan 2002 11:21:19 -0000	1.5
  +++ Location.java	24 Feb 2002 08:55:28 -0000	1.6
  @@ -1,7 +1,7 @@
   /*
    * The Apache Software License, Version 1.1
    *
  - * Copyright (c) 2000 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
  @@ -55,13 +55,20 @@
   package org.apache.tools.ant;
   
   /**
  - * Stores the file name and line number in a file.
  + * Stores the location of a piece of text within a file (file name,
  + * line number and column number). Note that the column number is
  + * currently ignored.
    */
   public class Location {
  +    
  +    /** Name of the file. */
       private String fileName;
  +    /** Line number within the file. */
       private int lineNumber;
  +    /** Column number within the file. */
       private int columnNumber;
   
  +    /** Location to use when one is needed but no information is available */
       public final static Location UNKNOWN_LOCATION = new Location();
   
       /**
  @@ -72,14 +79,28 @@
       }
   
       /**
  -     * Creates a location consisting of a file name but no line number.
  +     * Creates a location consisting of a file name but no line number or
  +     * column number.
  +     * 
  +     * @param fileName The name of the file. May be <code>null</code>,
  +     *                 in which case the location is equivalent to
  +     *                 {@link #UNKNOWN_LOCATION UNKNOWN_LOCATION}.
        */
       public Location(String fileName) {
           this(fileName, 0, 0);
       }
   
       /**
  -     * Creates a location consisting of a file name and line number.
  +     * Creates a location consisting of a file name, line number and
  +     * column number.
  +     * 
  +     * @param fileName The name of the file. May be <code>null</code>,
  +     *                 in which case the location is equivalent to
  +     *                 {@link #UNKNOWN_LOCATION UNKNOWN_LOCATION}.
  +     * 
  +     * @param lineNumber Line number within the file. Use 0 for unknown
  +     *                   positions within a file.
  +     * @param columnNumber Column number within the line.
        */
       public Location(String fileName, int lineNumber, int columnNumber) {
           this.fileName = fileName;
  @@ -88,9 +109,14 @@
       }
   
       /**
  -     * Returns the file name, line number and a trailing space. An error
  -     * message can be appended easily. For unknown locations, returns
  -     * an empty string.
  +     * Returns the file name, line number, a colon and a trailing space. 
  +     * An error message can be appended easily. For unknown locations, an 
  +     * empty string is returned.
  +     * 
  +     * @return a String of the form <code>"fileName: lineNumber: "</code>
  +     *         if both file name and line number are known,
  +     *         <code>"fileName: "</code> if only the file name is known,
  +     *         and the empty string for unknown locations.
        */
       public String toString() {
           StringBuffer buf = new StringBuffer();
  
  
  

--
To unsubscribe, e-mail:   <mailto:ant-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:ant-dev-help@jakarta.apache.org>


Mime
View raw message