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    *      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  package org.apache.commons.vfs2.provider.ftp;
18  
19  import java.io.IOException;
20  import java.io.InputStream;
21  import java.io.OutputStream;
22  import java.time.Instant;
23  
24  import org.apache.commons.net.ftp.FTPFile;
25  import org.apache.commons.net.ftp.FTPReply;
26  import org.apache.commons.vfs2.FileSystemException;
27  
28  /**
29   * What VFS expects from an FTP client to provide.
30   */
31  public interface FtpClient {
32  
33      /**
34       * Aborts the current operation.
35       *
36       * @return true if aborted.
37       * @throws IOException If an I/O error occurs
38       */
39      boolean abort() throws IOException;
40  
41      /**
42       * Returns an OutputStream through which data can be written to append to a file on the server with the given name.
43       *
44       * @param relPath The name of the remote file.
45       * @return An OutputStream through which the remote file can be appended.
46       * @throws IOException If an I/O error occurs.
47       */
48      OutputStream appendFileStream(String relPath) throws IOException;
49  
50      /**
51       * There are a few FTPClient methods that do not complete the entire sequence of FTP commands to complete a transaction.
52       * These commands require some action by the programmer after the reception of a positive intermediate command. After
53       * the programmer's code completes its actions, it must call this method to receive the completion reply from the server
54       * and verify the success of the entire transaction.
55       *
56       * @return true if successfully completed, false if not.
57       * @throws IOException If an I/O error occurs.
58       */
59      boolean completePendingCommand() throws IOException;
60  
61      /**
62       * Deletes a file on the FTP server.
63       *
64       * @param relPath The relPath of the file to be deleted.
65       * @return true if successfully completed, false if not.
66       * @throws IOException If an I/O error occurs.
67       */
68      boolean deleteFile(String relPath) throws IOException;
69  
70      /**
71       * Sends the FTP QUIT command to the server, receive the reply, and return the reply code.
72       *
73       * @throws IOException If an I/O error occurs.
74       */
75      void disconnect() throws IOException;
76  
77      /**
78       * Gets the integer value of the reply code of the last FTP reply.
79       *
80       * @return The integer value of the reply code of the last FTP reply.
81       * @throws IOException If an I/O error occurs.
82       */
83      @SuppressWarnings("unused")
84      default int getReplyCode() throws IOException {
85          return FTPReply.COMMAND_OK;
86      }
87  
88      /**
89       * Gets the entire text of the last FTP server response exactly as it was received, including all end of line markers in
90       * NETASCII format.
91       *
92       * @return The entire text from the last FTP response as a String.
93       * @throws IOException If an I/O error occurs.
94       */
95      String getReplyString() throws IOException;
96  
97      /**
98       * Queries the server for a supported feature.
99       *
100      * @param feature the name of the feature, converted to upper case.
101      * @return {@code true} if the feature is present, {@code false} if the feature is not present or the FTP command
102      *         failed.
103      *
104      * @throws IOException If an I/O error occurs.
105      * @since 2.8.0
106      */
107     boolean hasFeature(String feature) throws IOException;
108 
109     /**
110      * Tests if the client is currently connected to a server.
111      *
112      * @return true if the client is currently connected to a server, false otherwise.
113      * @throws FileSystemException If an I/O error occurs.
114      */
115     boolean isConnected() throws FileSystemException;
116 
117     /**
118      * Using the default system autodetect mechanism, obtain a list of file information for the current working directory or
119      * for just a single file.
120      * <p>
121      * TODO This interface should not leak Apache Commons NET types like FTPFile
122      * </p>
123      *
124      * @param relPath The file or directory to list.
125      * @return an array of FTPFile.
126      * @throws IOException If an I/O error occurs.
127      */
128     FTPFile[] listFiles(String relPath) throws IOException;
129 
130     /**
131      * Creates a new subdirectory on the FTP server in the current directory (if a relative pathname is given) or where
132      * specified (if an absolute pathname is given).
133      *
134      * @param relPath The pathname of the directory to create.
135      * @return true if successfully completed, false if not.
136      * @throws IOException If an I/O error occurs.
137      */
138     boolean makeDirectory(String relPath) throws IOException;
139 
140     /**
141      * Sends the MDTM command to get a file's date and time information after file transfer. It is typically more accurate
142      * than the {@code "LIST"} command response. Time values are always represented in UTC (GMT), and in the Gregorian
143      * calendar regardless of what calendar may have been in use at the date and time the file was last modified.
144      * <p>
145      * NOTE: not all remote FTP servers support {@code MDTM}.
146      * </p>
147      *
148      * @param relPath The relative path of the file object to execute {@code MDTM} command against
149      * @return new {@code Instant} object containing the {@code MDTM} timestamp.
150      * @throws IOException If an I/O error occurs.
151      * @since 2.8.0
152      */
153     @SuppressWarnings("unused")
154     default Instant mdtmInstant(final String relPath) throws IOException {
155         return null;
156     }
157 
158     /**
159      * Removes a directory on the FTP server (if empty).
160      *
161      * @param relPath The pathname of the directory to remove.
162      * @return true if successfully completed, false if not.
163      * @throws IOException If an I/O error occurs.
164      */
165     boolean removeDirectory(String relPath) throws IOException;
166 
167     /**
168      * Renames a remote file.
169      *
170      * @param from The name of the remote file to rename.
171      * @param to The new name of the remote file.
172      * @return true if successfully completed, false if not.
173      * @throws IOException If an I/O error occurs.
174      */
175     boolean rename(String from, String to) throws IOException;
176 
177     /**
178      * Returns an InputStream from which a named file from the server can be read.
179      *
180      * @param relPath The name of the remote file.
181      * @return An InputStream from which the remote file can be read.
182      * @throws IOException If an I/O error occurs.
183      */
184     InputStream retrieveFileStream(String relPath) throws IOException;
185 
186     /**
187      * Returns an InputStream from which a named file from the server can be read.
188      *
189      * @param relPath The name of the remote file.
190      * @param bufferSize buffer size.
191      * @return An InputStream from which the remote file can be read.
192      * @throws IOException If an I/O error occurs.
193      */
194     default InputStream retrieveFileStream(final String relPath, final int bufferSize) throws IOException {
195         // Backward compatibility: no buffer size.
196         return retrieveFileStream(relPath);
197     }
198 
199     /**
200      * Returns an InputStream from which a named file from the server can be read.
201      *
202      * @param relPath The name of the remote file.
203      * @param restartOffset restart offset.
204      * @return An InputStream from which the remote file can be read.
205      * @throws IOException If an I/O error occurs.
206      */
207     InputStream retrieveFileStream(String relPath, long restartOffset) throws IOException;
208 
209     /**
210      * Sets the buffer size for buffered data streams.
211      *
212      * @param bufferSize The size of the buffer.
213      * @throws FileSystemException If an I/O error occurs.
214      */
215     @SuppressWarnings("unused")
216     default void setBufferSize(final int bufferSize) throws FileSystemException {
217         // Backward compatibility: do nothing.
218     }
219 
220     /**
221      * Returns an OutputStream through which data can be written to store a file on the server using the given name.
222      *
223      * @param relPath The name to give the remote file.
224      * @return An OutputStream through which the remote file can be written.
225      * @throws IOException If an I/O error occurs.
226      */
227     OutputStream storeFileStream(String relPath) throws IOException;
228 
229 }