View Javadoc

    1   /*
    2    * Copyright 2001-2005 The Apache Software Foundation
    3    *
    4    * Licensed under the Apache License, Version 2.0 (the "License");
    5    * you may not use this file except in compliance with the License.
    6    * You may obtain a copy of the License at
    7    *
    8    *     http://www.apache.org/licenses/LICENSE-2.0
    9    *
    10   * Unless required by applicable law or agreed to in writing, software
    11   * distributed under the License is distributed on an "AS IS" BASIS,
    12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13   * See the License for the specific language governing permissions and
    14   * limitations under the License.
    15   */
    16  package org.apache.commons.net.ftp;
    17  import java.io.BufferedReader;
    18  import java.io.IOException;
    19  import java.util.List;
    20
    21  /***
    22   * FTPFileEntryParser defines the interface for parsing a single FTP file
    23   * listing and converting that information into an
    24   * {@link org.apache.commons.net.ftp.FTPFile} instance.
    25   * Sometimes you will want to parse unusual listing formats, in which
    26   * case you would create your own implementation of FTPFileEntryParser and
    27   * if necessary, subclass FTPFile.
    28   * <p>
    29   * Here are some examples showing how to use one of the classes that
    30   * implement this interface.
    31   * <p>
    32   * The first example shows how to get an <b>iterable</b> list of files in which the
    33   * more expensive <code>FTPFile</code> objects are not created until needed.  This
    34   * is suitable for paged displays.   It requires that a parser object be created
    35   * beforehand: <code>parser</code> is an object (in the package
    36   * <code>org.apache.commons.net.ftp.parser</code>)
    37   * implementing this inteface.
    38   *
    39   * <pre>
    40   *    FTPClient f=FTPClient();
    41   *    f.connect(server);
    42   *    f.login(username, password);
    43   *    FTPFileList list = f.createFileList(directory, parser);
    44   *    FTPFileIterator iter = list.iterator();
    45   *
    46   *    while (iter.hasNext()) {
    47   *       FTPFile[] files = iter.getNext(25);  // "page size" you want
    48   *       //do whatever you want with these files, display them, etc.
    49   *       //expensive FTPFile objects not created until needed.
    50   *    }
    51   * </pre>
    52   *
    53   * The second example uses the revised <code>FTPClient.listFiles()</code>
    54   * API to pull the whole list from the subfolder <code>subfolder</code> in
    55   * one call, attempting to automatically detect the parser type.  This
    56   * method, without a parserKey parameter, indicates that autodection should
    57   * be used.
    58   *
    59   * <pre>
    60   *    FTPClient f=FTPClient();
    61   *    f.connect(server);
    62   *    f.login(username, password);
    63   *    FTPFile[] files = f.listFiles("subfolder");
    64   * </pre>
    65   *
    66   * The third example uses the revised <code>FTPClient.listFiles()</code>>
    67   * API to pull the whole list from the current working directory in one call,
    68   * but specifying by classname the parser to be used.  For this particular
    69   * parser class, this approach is necessary since there is no way to
    70   * autodetect this server type.
    71   *
    72   * <pre>
    73   *    FTPClient f=FTPClient();
    74   *    f.connect(server);
    75   *    f.login(username, password);
    76   *    FTPFile[] files = f.listFiles(
    77   *      "org.apache.commons.net.ftp.parser.EnterpriseUnixFTPFileEntryParser",
    78   *      ".");
    79   * </pre>
    80   *
    81   * The fourth example uses the revised <code>FTPClient.listFiles()</code>
    82   * API to pull a single file listing in an arbitrary directory in one call,
    83   * specifying by KEY the parser to be used, in this case, VMS.
    84   *
    85   * <pre>
    86   *    FTPClient f=FTPClient();
    87   *    f.connect(server);
    88   *    f.login(username, password);
    89   *    FTPFile[] files = f.listFiles("VMS", "subfolder/foo.java");
    90   * </pre>
    91   *
    92   * @author <a href="mailto:scohen@apache.org">Steve Cohen</a>
    93   * @version $Id: FTPFileEntryParser.java 165675 2005-05-02 20:09:55Z rwinston $
    94   * @see org.apache.commons.net.ftp.FTPFile
    95   * @see org.apache.commons.net.ftp.FTPClient#createFileList
    96   */
    97  public interface FTPFileEntryParser
    98  {
    99      /***
    100      * Parses a line of an FTP server file listing and converts it into a usable
    101      * format in the form of an <code> FTPFile </code> instance.  If the
    102      * file listing line doesn't describe a file, <code> null </code> should be
    103      * returned, otherwise a <code> FTPFile </code> instance representing the
    104      * files in the directory is returned.
    105      * <p>
    106      * @param listEntry A line of text from the file listing
    107      * @return An FTPFile instance corresponding to the supplied entry
    108      */
    109     FTPFile parseFTPEntry(String listEntry);
    110
    111     /***
    112      * Reads the next entry using the supplied BufferedReader object up to
    113      * whatever delemits one entry from the next.  Implementors must define
    114      * this for the particular ftp system being parsed.  In many but not all
    115      * cases, this can be defined simply by calling BufferedReader.readLine().
    116      *
    117      * @param reader The BufferedReader object from which entries are to be
    118      * read.
    119      *
    120      * @return A string representing the next ftp entry or null if none found.
    121      * @exception IOException thrown on any IO Error reading from the reader.
    122      */
    123     String readNextEntry(BufferedReader reader) throws IOException;
    124
    125
    126     /***
    127      * This method is a hook for those implementors (such as
    128      * VMSVersioningFTPEntryParser, and possibly others) which need to
    129      * perform some action upon the FTPFileList after it has been created
    130      * from the server stream, but before any clients see the list.
    131      *
    132      * The default implementation can be a no-op.
    133      *
    134      * @param original Original list after it has been created from the server stream
    135      *
    136      * @return Original list as processed by this method.
    137      */
    138     List preParse(List original);
    139
    140
    141 }
    142
    143
    144 /* Emacs configuration
    145  * Local variables:        **
    146  * mode:             java  **
    147  * c-basic-offset:   4     **
    148  * indent-tabs-mode: nil   **
    149  * End:                    **
    150  */