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 */