FTPFileEntryParser


1   /*
2    * Copyright 2001-2005 The Apache Software Foundation
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *     http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.apache.commons.net.ftp;
17  import java.io.BufferedReader  ;
18  import java.io.IOException  ;
19  import java.util.List  ;
20  
21  /**
22   * FTPFileEntryParser defines the interface for parsing a single FTP file
23   * listing and converting that information into an
24   * {@link org.apache.commons.net.ftp.FTPFile} instance.
25   * Sometimes you will want to parse unusual listing formats, in which
26   * case you would create your own implementation of FTPFileEntryParser and
27   * if necessary, subclass FTPFile.
28   * <p>
29   * Here are some examples showing how to use one of the classes that
30   * implement this interface.
31   * <p>
32   * The first example shows how to get an <b>iterable</b> list of files in which the
33   * more expensive <code>FTPFile</code> objects are not created until needed.  This
34   * is suitable for paged displays.   It requires that a parser object be created
35   * beforehand: <code>parser</code> is an object (in the package
36   * <code>org.apache.commons.net.ftp.parser</code>)
37   * implementing this inteface.
38   *
39   * <pre>
40   *    FTPClient f=FTPClient();
41   *    f.connect(server);
42   *    f.login(username, password);
43   *    FTPFileList list = f.createFileList(directory, parser);
44   *    FTPFileIterator iter = list.iterator();
45   *
46   *    while (iter.hasNext()) {
47   *       FTPFile[] files = iter.getNext(25);  // "page size" you want
48   *       //do whatever you want with these files, display them, etc.
49   *       //expensive FTPFile objects not created until needed.
50   *    }
51   * </pre>
52   *
53   * The second example uses the revised <code>FTPClient.listFiles()</code>
54   * API to pull the whole list from the subfolder <code>subfolder</code> in
55   * one call, attempting to automatically detect the parser type.  This
56   * method, without a parserKey parameter, indicates that autodection should
57   * be used.
58   *
59   * <pre>
60   *    FTPClient f=FTPClient();
61   *    f.connect(server);
62   *    f.login(username, password);
63   *    FTPFile[] files = f.listFiles("subfolder");
64   * </pre>
65   *
66   * The third example uses the revised <code>FTPClient.listFiles()</code>>
67   * API to pull the whole list from the current working directory in one call,
68   * but specifying by classname the parser to be used.  For this particular
69   * parser class, this approach is necessary since there is no way to
70   * autodetect this server type.
71   *
72   * <pre>
73   *    FTPClient f=FTPClient();
74   *    f.connect(server);
75   *    f.login(username, password);
76   *    FTPFile[] files = f.listFiles(
77   *      "org.apache.commons.net.ftp.parser.EnterpriseUnixFTPFileEntryParser",
78   *      ".");
79   * </pre>
80   *
81   * The fourth example uses the revised <code>FTPClient.listFiles()</code>
82   * API to pull a single file listing in an arbitrary directory in one call,
83   * specifying by KEY the parser to be used, in this case, VMS.
84   *
85   * <pre>
86   *    FTPClient f=FTPClient();
87   *    f.connect(server);
88   *    f.login(username, password);
89   *    FTPFile[] files = f.listFiles("VMS", "subfolder/foo.java");
90   * </pre>
91   *
92   * @author <a HREF="mailto:scohen@apache.org">Steve Cohen</a>
93   * @version $Id: FTPFileEntryParser.java 165675 2005-05-02 20:09:55Z rwinston $
94   * @see org.apache.commons.net.ftp.FTPFile
95   * @see org.apache.commons.net.ftp.FTPClient#createFileList
96   */
97  public interface FTPFileEntryParser
98  {
99      /**
100      * Parses a line of an FTP server file listing and converts it into a usable
101      * format in the form of an <code> FTPFile </code> instance.  If the
102      * file listing line doesn't describe a file, <code> null </code> should be
103      * returned, otherwise a <code> FTPFile </code> instance representing the
104      * files in the directory is returned.
105      * <p>
106      * @param listEntry A line of text from the file listing
107      * @return An FTPFile instance corresponding to the supplied entry
108      */
109     FTPFile parseFTPEntry(String   listEntry);
110 
111     /**
112      * Reads the next entry using the supplied BufferedReader object up to
113      * whatever delemits one entry from the next.  Implementors must define
114      * this for the particular ftp system being parsed.  In many but not all
115      * cases, this can be defined simply by calling BufferedReader.readLine().
116      *
117      * @param reader The BufferedReader object from which entries are to be
118      * read.
119      *
120      * @return A string representing the next ftp entry or null if none found.
121      * @exception IOException thrown on any IO Error reading from the reader.
122      */
123     String   readNextEntry(BufferedReader   reader) throws IOException  ;
124 
125 
126     /**
127      * This method is a hook for those implementors (such as
128      * VMSVersioningFTPEntryParser, and possibly others) which need to
129      * perform some action upon the FTPFileList after it has been created
130      * from the server stream, but before any clients see the list.
131      *
132      * The default implementation can be a no-op.
133      *
134      * @param original Original list after it has been created from the server stream
135      *
136      * @return Original list as processed by this method.
137      */
138     List   preParse(List   original);
139 
140 
141 }
142 
143 
144 /* Emacs configuration
145  * Local variables:        **
146  * mode:             java  **
147  * c-basic-offset:   4     **
148  * indent-tabs-mode: nil   **
149  * End:                    **
150  */
151
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags