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
20 import java.io.BufferedReader;
21 import java.io.IOException;
22 import java.util.List;
23
24 /**
25 * FTPFileEntryParser defines the interface for parsing a single FTP file listing and converting that information into an
26 * {@link org.apache.commons.net.ftp.FTPFile} instance. Sometimes you will want to parse unusual listing formats, in which case you would create your own
27 * implementation of FTPFileEntryParser and if necessary, subclass FTPFile.
28 * <p>
29 * Here are some examples showing how to use one of the classes that implement this interface.
30 * <p>
31 *
32 * The first example uses the <code>FTPClient.listFiles()</code> API to pull the whole list from the subfolder <code>subfolder</code> in one call, attempting to
33 * automatically detect the parser type. This method, without a parserKey parameter, indicates that autodection should be used.
34 *
35 * <pre>
36 * FTPClient f = FTPClient();
37 * f.connect(server);
38 * f.login(user, password);
39 * FTPFile[] files = f.listFiles("subfolder");
40 * </pre>
41 *
42 * The second example uses the <code>FTPClient.listFiles()</code> API to pull the whole list from the current working directory in one call, but specifying by
43 * class name the parser to be used. For this particular parser class, this approach is necessary since there is no way to autodetect this server type.
44 *
45 * <pre>
46 * FTPClient f = FTPClient();
47 * f.connect(server);
48 * f.login(user, password);
49 * FTPFile[] files = f.listFiles("org.apache.commons.net.ftp.parser.EnterpriseUnixFTPFileEntryParser", ".");
50 * </pre>
51 *
52 * The third example uses the <code>FTPClient.listFiles()</code> API to pull a single file listing in an arbitrary directory in one call, specifying by KEY the
53 * parser to be used, in this case, VMS.
54 *
55 * <pre>
56 * FTPClient f = FTPClient();
57 * f.connect(server);
58 * f.login(user, password);
59 * FTPFile[] files = f.listFiles("VMS", "subfolder/foo.java");
60 * </pre>
61 *
62 * For an alternative approach, see the {@link FTPListParseEngine} class which provides iterative access.
63 *
64 * @see org.apache.commons.net.ftp.FTPFile
65 * @see org.apache.commons.net.ftp.FTPClient#listFiles()
66 */
67 public interface FTPFileEntryParser {
68 /**
69 * Parses a line of an FTP server file listing and converts it into a usable format in the form of an <code>FTPFile</code> instance. If the file listing
70 * line doesn't describe a file, <code>null</code> should be returned, otherwise a <code>FTPFile</code> instance representing the files in the directory
71 * is returned.
72 *
73 * @param listEntry A line of text from the file listing
74 * @return An FTPFile instance corresponding to the supplied entry
75 */
76 FTPFile parseFTPEntry(String listEntry);
77
78 /**
79 * This method is a hook for those implementors (such as VMSVersioningFTPEntryParser, and possibly others) which need to perform some action upon the
80 * FTPFileList after it has been created from the server stream, but before any clients see the list.
81 *
82 * The default implementation can be a no-op.
83 *
84 * @param original Original list after it has been created from the server stream
85 *
86 * @return Original list as processed by this method.
87 */
88 List<String> preParse(List<String> original);
89
90 /**
91 * Reads the next entry using the supplied BufferedReader object up to whatever delimits one entry from the next. Implementors must define this for the
92 * particular ftp system being parsed. In many but not all cases, this can be defined simply by calling BufferedReader.readLine().
93 *
94 * @param reader The BufferedReader object from which entries are to be read.
95 *
96 * @return A string representing the next ftp entry or null if none found.
97 * @throws IOException thrown on any IO Error reading from the reader.
98 */
99 String readNextEntry(BufferedReader reader) throws IOException;
100
101 }