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 }