commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sco...@apache.org
Subject cvs commit: jakarta-commons/net/src/java/org/apache/commons/net/ftp FTPClient.java FTPFileEntryParser.java FTPFileIterator.java FTPFileList.java FTPFileListParser.java FTPFileListParserImpl.java
Date Thu, 06 Mar 2003 12:38:43 GMT
scohen      2003/03/06 04:38:43

  Modified:    net/src/java/org/apache/commons/net/ftp FTPClient.java
                        FTPFileEntryParser.java FTPFileIterator.java
                        FTPFileList.java FTPFileListParser.java
                        FTPFileListParserImpl.java
  Log:
  Make the style gods happier.
  
  Revision  Changes    Path
  1.7       +38 -17    jakarta-commons/net/src/java/org/apache/commons/net/ftp/FTPClient.java
  
  Index: FTPClient.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/net/src/java/org/apache/commons/net/ftp/FTPClient.java,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- FTPClient.java	2 Mar 2003 18:15:24 -0000	1.6
  +++ FTPClient.java	6 Mar 2003 12:38:41 -0000	1.7
  @@ -2021,31 +2021,52 @@
       }
   
       /**
  -     * Using a programmer specified <code> FTPFileEntryParser </code>, 
  -     * initialize an object containing a raw file information for the 
  -     * current working directory.  This information is obtained through 
  -     * the LIST command.  This object is then capable of being iterated to 
  +     * Using a programmer specified <code> FTPFileEntryParser </code>,
  +     * initialize an object containing a raw file information for the
  +     * current working directory.  This information is obtained through
  +     * the LIST command.  This object is then capable of being iterated to
        * return a sequence of FTPFile objects with information filled in by the
        * <code> FTPFileEntryParser </code> used.
  +     * <p>
        * The server may or may not expand glob expressions.  You should avoid
        * using glob expressions because the return format for glob listings
        * differs from server to server and will likely cause this method to fail.
        * <p>
  +     * This method differs from using the listFiles() methods in that
  +     * expensive FTPFile objects are not created until needed which may be
  +     * an advantage on large lists.
  +     * 
        * @param parser The <code> FTPFileEntryParser </code> that should be
  -     *         used to parse each server file listing.   
  -     * @return An iteratable object that holds the raw information and is 
  -     * capable of providing parsed FTPFile objects, one for each file containing
  -     * information contained in the given path in the format determined by the 
  -     * <code> parser </code> parameter.   Null will be returned if a 
  -     * data connection cannot be opened.  If the current working directory 
  -     * contains no files, an empty array will be the return.
  +     *               used to parse each server file listing.
  +     * 
  +     * @return An iteratable object that holds the raw information and is
  +     *         capable of providing parsed FTPFile objects, one for each file containing
  +     *         information contained in the given path in the format determined by the
  +     *         <code> parser </code> parameter.   Null will be returned if
a
  +     *         data connection cannot be opened.  If the current working directory
  +     *         contains no files, an empty array will be the return.
  +     * @example <pre>
  +     *    FTPClient f=FTPClient();
  +     *    f.connect(server);
  +     *    f.login(username, password);
  +     *    FTPFileList list = createFTPFileList(directory, parser);
  +     *    FTPFileIterator iter = list.iterator();
  +     * 
  +     *    while (iter.hasNext()) {
  +     *       FTPFile[] files = iter.getNext(25);  // "page size" you want
  +     *       //do whatever you want with these files, display them, etc.
  +     *       //expensive FTPFile objects not created until needed.
  +     *    }
  +     * </pre>
  +     * 
        * @exception FTPConnectionClosedException
  -     *      If the FTP server prematurely closes the connection as a result
  -     *      of the client being idle or some other reason causing the server
  -     *      to send FTP reply code 421.  This exception may be caught either
  -     *      as an IOException or independently as itself.
  -     * @exception IOException  If an I/O error occurs while either sending a
  -     *      command to the server or receiving a reply from the server.
  +     *                   If the FTP server prematurely closes the connection as a result
  +     *                   of the client being idle or some other reason causing the server
  +     *                   to send FTP reply code 421.  This exception may be caught either
  +     *                   as an IOException or independently as itself.
  +     * @exception IOException
  +     *                   If an I/O error occurs while either sending a
  +     *                   command to the server or receiving a reply from the server.
        * @see FTPFileList
        */
       public FTPFileList createFileList(FTPFileEntryParser parser)
  
  
  
  1.4       +8 -6      jakarta-commons/net/src/java/org/apache/commons/net/ftp/FTPFileEntryParser.java
  
  Index: FTPFileEntryParser.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/net/src/java/org/apache/commons/net/ftp/FTPFileEntryParser.java,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- FTPFileEntryParser.java	3 Mar 2003 03:42:05 -0000	1.3
  +++ FTPFileEntryParser.java	6 Mar 2003 12:38:42 -0000	1.4
  @@ -1,6 +1,4 @@
   package org.apache.commons.net.ftp;
  -import java.io.BufferedReader;
  -import java.io.IOException;
   
   /* ====================================================================
    * The Apache Software License, Version 1.1
  @@ -56,6 +54,9 @@
    * <http://www.apache.org/>.
    */
   
  +import java.io.BufferedReader;
  +import java.io.IOException;
  +
   /**
    * FTPFileEntryParser defines the interface for parsing a single FTP file
    * listing and converting that information into an 
  @@ -81,7 +82,7 @@
        * @param listEntry A line of text from the file listing
        * @return An FTPFile instance corresponding to the supplied entry
        */
  -    public FTPFile parseFTPEntry(String listEntry);
  +    FTPFile parseFTPEntry(String listEntry);
   
       /**
        * Reads the next entry using the supplied BufferedReader object up to 
  @@ -89,10 +90,11 @@
        * this for the particular ftp system being parsed.  In many but not all 
        * cases, this can be defined simply by calling BufferedReader.readLine().
        * 
  -     * @param reader The BufferedReader object from which entries are to be read.
  +     * @param reader The BufferedReader object from which entries are to be 
  +     * read.
        * 
        * @return A string representing the next ftp entry or null if none found.
        * @exception IOException thrown on any IO Error reading from the reader.
        */
  -    public String readNextEntry(BufferedReader reader) throws IOException;
  +    String readNextEntry(BufferedReader reader) throws IOException;
   }
  
  
  
  1.4       +55 -5     jakarta-commons/net/src/java/org/apache/commons/net/ftp/FTPFileIterator.java
  
  Index: FTPFileIterator.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/net/src/java/org/apache/commons/net/ftp/FTPFileIterator.java,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- FTPFileIterator.java	3 Mar 2003 03:42:05 -0000	1.3
  +++ FTPFileIterator.java	6 Mar 2003 12:38:42 -0000	1.4
  @@ -62,19 +62,45 @@
    * Elements may be retrieved one at at time using the hasNext() - next()
    * syntax familiar from Java 2 collections.  Alternatively, entries may
    * be receieved as an array of any requested number of entries or all of them.
  - *
  + * 
    * @author <a href="mailto:scohen@apache.org">Steve Cohen</a>
    * @version $Id$
    * @see org.apache.commons.net.ftp.FTPFileList
  + * @see org.apache.commons.net.ftp.FTPFileEntryParser
    */
   public class FTPFileIterator
   {
  +    /**
  +     * a vector of strings, each representing a possibly valid ftp file
  +     * entry
  +     */
       private Vector rawlines;
  +    
  +    /**
  +     * the parser to which this iterator delegates its parsing duties
  +     */
       private FTPFileEntryParser parser;
   
  +    /**
  +     * constant shorthand for the situation where the raw listing has not 
  +     * yet been scanned
  +     */
       private static final int UNINIT = -1;
  +    
  +    /**
  +     * constant shorthand for the situation where the raw listing has been 
  +     * scanned and found to have no valid entry.
  +     */
       private static final int DIREMPTY = -2;
  +    
  +    /**
  +     * this iterator's current position within <code>rawlines</code>.
  +     */
       private int itemptr = 0;
  +    
  +    /**
  +     * number within <code>rawlines</code> of the first valid file entry.
  +     */
       private int firstGoodEntry = UNINIT;
   
       /**
  @@ -84,7 +110,7 @@
        *
        * @param rawlist the FTPFileList to be iterated
        */
  -    FTPFileIterator ( FTPFileList rawlist )
  +    FTPFileIterator (FTPFileList rawlist)
       {
           this(rawlist, rawlist.getParser());
       }
  @@ -97,17 +123,35 @@
        * @param rawlist the FTPFileList to be iterated
        * @param parser the system specific parser for raw FTP entries.
        */
  -    FTPFileIterator ( FTPFileList rawlist, FTPFileEntryParser parser )
  +    FTPFileIterator (FTPFileList rawlist, FTPFileEntryParser parser)
       {
           this.rawlines = rawlist.getLines();
           this.parser = parser;
       }
   
  +    /**
  +     * Delegates to this object's parser member the job of parsing an
  +     * entry.
  +     * 
  +     * @param entry  A string containing one entry, as determined by the 
  +     * parser's getNextEntry() method.
  +     * 
  +     * @return an FTPFile object representing this entry or null if it can't be 
  +     *         parsed as a file
  +     */
       private FTPFile parseFTPEntry(String entry)
       {
           return this.parser.parseFTPEntry(entry);
       }
   
  +    /**
  +     * Skips over any introductory lines and stuff in the listing that does
  +     * not represent files, returning the line number of the first entry
  +     * that does represent a file.
  +     * 
  +     * @return the line number within <code>rawlines</code> of the first good

  +     * entry in the array or DIREMPTY if there are no good entries.
  +     */
       private int getFirstGoodEntry()
       {
           FTPFile entry = null;
  @@ -123,12 +167,18 @@
           return DIREMPTY;
       }
   
  +    /**
  +     * resets iterator to the beginning of the list.
  +     */
       private void init()
       {
           this.itemptr = 0;
           this.firstGoodEntry = UNINIT;
       }
   
  +    /**
  +     * shorthand for an empty return value.
  +     */
       private static final FTPFile[] EMPTY = new FTPFile[0];
   
       /**
  @@ -279,7 +329,7 @@
               howMany = this.itemptr;
           }
           FTPFile[] output = new FTPFile[howMany];
  -        for (int i = howMany, e = this.firstGoodEntry + this.itemptr; i > 0; )
  +        for (int i = howMany, e = this.firstGoodEntry + this.itemptr; i > 0;)
           {
               output[--i] = parseFTPEntry((String) this.rawlines.elementAt(--e));
               this.itemptr--;
  
  
  
  1.4       +12 -10    jakarta-commons/net/src/java/org/apache/commons/net/ftp/FTPFileList.java
  
  Index: FTPFileList.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/net/src/java/org/apache/commons/net/ftp/FTPFileList.java,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- FTPFileList.java	3 Mar 2003 03:42:05 -0000	1.3
  +++ FTPFileList.java	6 Mar 2003 12:38:42 -0000	1.4
  @@ -62,22 +62,24 @@
   
   /**
    * FTPFileList.java
  - * This class encapsulates a listing of files from an FTP server.  It is 
  + * This class encapsulates a listing of files from an FTP server.  It is
    * initialized with an input stream which is read and the input split into
    * lines, each of which (after some possible initial verbiage) represents
    * a file on the FTP server.  A parser is also supplied, which is used to
    * iterate through the internal list of lines parsing each into an FTPFile
  - * object which is returned to the caller of the iteration methods.  This 
  + * object which is returned to the caller of the iteration methods.  This
    * parser may be replaced with another, allowing the same list to be parsed
  - * with different parsers. 
  - * Parsing takes place on an as-needed basis, basically, the first time a 
  - * position is iterated over.  This happens at the time of iteration, not 
  - * prior to it as the older <code>(FTPClient.listFiles()</code> methods did,

  + * with different parsers.
  + * Parsing takes place on an as-needed basis, basically, the first time a
  + * position is iterated over.  This happens at the time of iteration, not
  + * prior to it as the older <code>(FTPClient.listFiles()</code> methods did,
    * which required a bigger memory hit.
  - *
  + * 
    * @author <a href="mailto:scohen@apache.org">Steve Cohen</a>
    * @version $Id$
    * @see org.apache.commons.net.ftp.FTPClient#createFileList
  + * @see org.apache.commons.net.ftp.FTPFileIterator
  + * @see org.apache.commons.net.ftp.FTPFileEntryParser
    */
   public class FTPFileList
   {
  @@ -124,7 +126,7 @@
        * @exception IOException
        *                   Thrown on any failure to read from the socket.
        */
  -    public static FTPFileList create( InputStream stream,
  +    public static FTPFileList create(InputStream stream,
                                         FTPFileEntryParser parser)
               throws IOException
       {
  @@ -138,7 +140,7 @@
        * 
        * @param stream The socket stream on which the input will be read.
        * 
  -     * @exception IOException
  +     * @exception IOException thrown on any failure to read the stream
        */
       private void readStream(InputStream stream) throws IOException
       {
  
  
  
  1.4       +1 -1      jakarta-commons/net/src/java/org/apache/commons/net/ftp/FTPFileListParser.java
  
  Index: FTPFileListParser.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/net/src/java/org/apache/commons/net/ftp/FTPFileListParser.java,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- FTPFileListParser.java	26 Jan 2003 00:21:43 -0000	1.3
  +++ FTPFileListParser.java	6 Mar 2003 12:38:42 -0000	1.4
  @@ -88,6 +88,6 @@
        *     the directory.
        * @exception IOException  If an I/O error occurs reading the listStream.
        ***/
  -    public FTPFile[] parseFileList(InputStream listStream) throws IOException;
  +    FTPFile[] parseFileList(InputStream listStream) throws IOException;
   
   }
  
  
  
  1.2       +29 -8     jakarta-commons/net/src/java/org/apache/commons/net/ftp/FTPFileListParserImpl.java
  
  Index: FTPFileListParserImpl.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/net/src/java/org/apache/commons/net/ftp/FTPFileListParserImpl.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- FTPFileListParserImpl.java	2 Mar 2003 18:15:24 -0000	1.1
  +++ FTPFileListParserImpl.java	6 Mar 2003 12:38:42 -0000	1.2
  @@ -65,12 +65,28 @@
   import org.apache.oro.text.regex.Perl5Compiler;
   import org.apache.oro.text.regex.MatchResult;
   
  +/**
  + * This abstract class implements both the older FTPFileListParser and
  + * newer FTPFileEntryParser interfaces with default functionality.
  + * All the classes in the parser subpackage inherit from this.
  + * 
  + * @author Steve Cohen <scohen@apache.org>
  + */
   public abstract class FTPFileListParserImpl 
       implements FTPFileListParser, FTPFileEntryParser
   {
  -    private String prefix;
  +    /**
  +     * internal pattern the matcher tries to match, representing a file 
  +     * entry
  +     */
       private Pattern pattern = null;
  +    /**
  +     * internal PatternMatcher object used by the parser
  +     */
       private PatternMatcher matcher = null;
  +    /**
  +     * internal match result used by the parser
  +     */
       private MatchResult result = null;
       
       /**
  @@ -90,7 +106,6 @@
       {
           try 
           {
  -            this.prefix = "[" + getClass().getName() + "] ";
               this.matcher = new Perl5Matcher();
               this.pattern = new Perl5Compiler().compile(regex);
           } 
  @@ -116,7 +131,8 @@
        *     the directory.
        * @exception IOException  If an I/O error occurs reading the listStream.
        ***/
  -    public FTPFile[] parseFileList(InputStream listStream) throws IOException {
  +    public FTPFile[] parseFileList(InputStream listStream) throws IOException 
  +    {
           FTPFileList ffl = FTPFileList.create(listStream, this);
           return ffl.getFiles();
   
  @@ -158,10 +174,13 @@
   
       /**
        * Convenience method delegates to the internal MatchResult's group()
  -     * method.  
  -     *
  +     * method.
  +     * 
  +     * @param matchnum match group number to be retrieved
  +     * 
        * @return the content of the <code>matchnum'th<code> group of the internal
  -     * match or null if this method is called without a match having been made.
  +     *         match or null if this method is called without a match having 
  +     *         been made.
        */
       public String group(int matchnum)
       {
  @@ -195,12 +214,14 @@
        * whatever delemits one entry from the next.  This default implementation
        * simply calls BufferedReader.readLine().
        *
  -     * @param reader The BufferedReader object from which entries are to be read.
  +     * @param reader The BufferedReader object from which entries are to be 
  +     * read.
        *
        * @return A string representing the next ftp entry or null if none found.
        * @exception IOException thrown on any IO Error reading from the reader.
        */
  -    public String readNextEntry(BufferedReader reader) throws IOException {
  +    public String readNextEntry(BufferedReader reader) throws IOException 
  +    {
           return reader.readLine();
       }
   }
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message