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