001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018 package org.apache.commons.net.ftp;
019 import java.io.BufferedReader;
020 import java.io.IOException;
021 import java.util.List;
022
023 /**
024 * FTPFileEntryParser defines the interface for parsing a single FTP file
025 * listing and converting that information into an
026 * {@link org.apache.commons.net.ftp.FTPFile} instance.
027 * Sometimes you will want to parse unusual listing formats, in which
028 * case you would create your own implementation of FTPFileEntryParser and
029 * if necessary, subclass FTPFile.
030 * <p>
031 * Here are some examples showing how to use one of the classes that
032 * implement this interface.
033 * <p>
034 *
035 * The first example uses the <code>FTPClient.listFiles()</code>
036 * API to pull the whole list from the subfolder <code>subfolder</code> in
037 * one call, attempting to automatically detect the parser type. This
038 * method, without a parserKey parameter, indicates that autodection should
039 * be used.
040 *
041 * <pre>
042 * FTPClient f=FTPClient();
043 * f.connect(server);
044 * f.login(username, password);
045 * FTPFile[] files = f.listFiles("subfolder");
046 * </pre>
047 *
048 * The secondr example uses the <code>FTPClient.listFiles()</code>>
049 * API to pull the whole list from the current working directory in one call,
050 * but specifying by classname the parser to be used. For this particular
051 * parser class, this approach is necessary since there is no way to
052 * autodetect this server type.
053 *
054 * <pre>
055 * FTPClient f=FTPClient();
056 * f.connect(server);
057 * f.login(username, password);
058 * FTPFile[] files = f.listFiles(
059 * "org.apache.commons.net.ftp.parser.EnterpriseUnixFTPFileEntryParser",
060 * ".");
061 * </pre>
062 *
063 * The third example uses the <code>FTPClient.listFiles()</code>
064 * API to pull a single file listing in an arbitrary directory in one call,
065 * specifying by KEY the parser to be used, in this case, VMS.
066 *
067 * <pre>
068 * FTPClient f=FTPClient();
069 * f.connect(server);
070 * f.login(username, password);
071 * FTPFile[] files = f.listFiles("VMS", "subfolder/foo.java");
072 * </pre>
073 *
074 * For an alternative approach, see the {@link FTPListParseEngine} class
075 * which provides iterative access.
076 *
077 * @author <a href="mailto:scohen@apache.org">Steve Cohen</a>
078 * @version $Id: FTPFileEntryParser.java 1299238 2012-03-10 17:12:28Z sebb $
079 * @see org.apache.commons.net.ftp.FTPFile
080 * @see org.apache.commons.net.ftp.FTPClient#listFiles()
081 */
082 public interface FTPFileEntryParser
083 {
084 /**
085 * Parses a line of an FTP server file listing and converts it into a usable
086 * format in the form of an <code> FTPFile </code> instance. If the
087 * file listing line doesn't describe a file, <code> null </code> should be
088 * returned, otherwise a <code> FTPFile </code> instance representing the
089 * files in the directory is returned.
090 * <p>
091 * @param listEntry A line of text from the file listing
092 * @return An FTPFile instance corresponding to the supplied entry
093 */
094 FTPFile parseFTPEntry(String listEntry);
095
096 /**
097 * Reads the next entry using the supplied BufferedReader object up to
098 * whatever delemits one entry from the next. Implementors must define
099 * this for the particular ftp system being parsed. In many but not all
100 * cases, this can be defined simply by calling BufferedReader.readLine().
101 *
102 * @param reader The BufferedReader object from which entries are to be
103 * read.
104 *
105 * @return A string representing the next ftp entry or null if none found.
106 * @exception IOException thrown on any IO Error reading from the reader.
107 */
108 String readNextEntry(BufferedReader reader) throws IOException;
109
110
111 /**
112 * This method is a hook for those implementors (such as
113 * VMSVersioningFTPEntryParser, and possibly others) which need to
114 * perform some action upon the FTPFileList after it has been created
115 * from the server stream, but before any clients see the list.
116 *
117 * The default implementation can be a no-op.
118 *
119 * @param original Original list after it has been created from the server stream
120 *
121 * @return Original list as processed by this method.
122 */
123 List<String> preParse(List<String> original);
124
125
126 }
127
128
129 /* Emacs configuration
130 * Local variables: **
131 * mode: java **
132 * c-basic-offset: 4 **
133 * indent-tabs-mode: nil **
134 * End: **
135 */