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