View Javadoc

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