You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by sc...@apache.org on 2003/03/06 13:38:43 UTC
cvs commit: jakarta-commons/net/src/java/org/apache/commons/net/ftp FTPClient.java FTPFileEntryParser.java FTPFileIterator.java FTPFileList.java FTPFileListParser.java FTPFileListParserImpl.java
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 <sc...@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