Skip to content

Commit

Permalink
Javadoc
Browse files Browse the repository at this point in the history
  • Loading branch information
@garydgregory
garydgregory committed Feb 26, 2025
1 parent eba2fb0 commit 1d55795
Showing 1 changed file with 37 additions and 30 deletions.
67 changes: 37 additions & 30 deletions src/main/java/org/apache/commons/net/ftp/FTPClient.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -117,15 +117,15 @@
* FTP reply code causing a success or failure, you must call {@link org.apache.commons.net.ftp.FTP#getReplyCode getReplyCode } after a success or failure.
* </p>
* <p>
* The default settings for FTPClient are for it to use {@code FTP.ASCII_FILE_TYPE}, {@code FTP.NON_PRINT_TEXT_FORMAT}, {@code FTP.STREAM_TRANSFER_MODE}, and
* {@code FTP.FILE_STRUCTURE}. The only file types directly supported are {@code FTP.ASCII_FILE_TYPE} and {@code FTP.BINARY_FILE_TYPE}. Because there are at
* The default settings for FTPClient are for it to use {@link FTP#ASCII_FILE_TYPE}, {@link FTP#NON_PRINT_TEXT_FORMAT}, {@link FTP#STREAM_TRANSFER_MODE}, and
* {@link FTP#FILE_STRUCTURE}. The only file types directly supported are {@link FTP#ASCII_FILE_TYPE} and {@link FTP#BINARY_FILE_TYPE}. Because there are at
* least 4 different EBCDIC encodings, we have opted not to provide direct support for EBCDIC. To transfer EBCDIC and other unsupported file types you must
* create your own filter InputStreams and OutputStreams and wrap them around the streams returned or required by the FTPClient methods. FTPClient uses the
* {@link ToNetASCIIOutputStream NetASCII} filter streams to provide transparent handling of ASCII files. We will consider incorporating EBCDIC support if there
* is enough demand.
* </p>
* <p>
* {@code FTP.NON_PRINT_TEXT_FORMAT}, {@code FTP.STREAM_TRANSFER_MODE}, and {@code FTP.FILE_STRUCTURE} are the only supported formats, transfer modes, and file
* {@link FTP#NON_PRINT_TEXT_FORMAT}, {@link FTP#STREAM_TRANSFER_MODE}, and {@link FTP#FILE_STRUCTURE} are the only supported formats, transfer modes, and file
* structures.
* </p>
* <p>
Expand All @@ -142,7 +142,7 @@
* You should keep in mind that the FTP server may choose to prematurely close a connection if the client has been idle for longer than a given time period
* (usually 900 seconds). The FTPClient class will detect a premature FTP server connection closing when it receives a
* {@link org.apache.commons.net.ftp.FTPReply#SERVICE_NOT_AVAILABLE FTPReply.SERVICE_NOT_AVAILABLE } response to a command. When that occurs, the FTP class
* method encountering that reply will throw an {@link org.apache.commons.net.ftp.FTPConnectionClosedException} . {@code FTPConnectionClosedException} is a
* method encountering that reply will throw an {@link org.apache.commons.net.ftp.FTPConnectionClosedException}. {@link FTPConnectionClosedException} is a
* subclass of {@code IOException} and therefore need not be caught separately, but if you are going to catch it separately, its catch block must appear before
* the more general {@code IOException} catch block. When you encounter an {@link org.apache.commons.net.ftp.FTPConnectionClosedException} , you must disconnect
* the connection with {@link #disconnect disconnect() } to properly clean up the system resources used by FTPClient. Before disconnecting, you may check the
Expand Down Expand Up @@ -613,9 +613,9 @@ static String parsePathname(final String reply) {
private boolean ipAddressFromPasvResponse = Boolean.getBoolean(FTP_IP_ADDRESS_FROM_PASV_RESPONSE);

/**
* Default FTPClient constructor. Creates a new FTPClient instance with the data connection mode set to {@code ACTIVE_LOCAL_DATA_CONNECTION_MODE}, the file
* type set to {@code FTP.ASCII_FILE_TYPE}, the file format set to {@code FTP.NON_PRINT_TEXT_FORMAT}, the file structure set to {@code FTP.FILE_STRUCTURE},
* and the transfer mode set to {@code FTP.STREAM_TRANSFER_MODE}.
* Default FTPClient constructor. Creates a new FTPClient instance with the data connection mode set to {@link #ACTIVE_LOCAL_DATA_CONNECTION_MODE}, the file
* type set to {@link FTP#ASCII_FILE_TYPE}, the file format set to {@link FTP#NON_PRINT_TEXT_FORMAT}, the file structure set to {@link FTP#FILE_STRUCTURE},
* and the transfer mode set to {@link FTP#STREAM_TRANSFER_MODE}.
* <p>
* The list parsing auto-detect feature can be configured to use lenient future dates (short dates may be up to one day in the future) as follows:
* </p>
Expand Down Expand Up @@ -1350,8 +1350,8 @@ public void enterLocalActiveMode() {
/**
* Sets the current data connection mode to {@code PASSIVE_LOCAL_DATA_CONNECTION_MODE}. Use this method only for data transfers between the client and
* server. This method causes a PASV (or EPSV) command to be issued to the server before the opening of every data connection, telling the server to open a
* data port to which the client will connect to conduct data transfers. The FTPClient will stay in {@code PASSIVE_LOCAL_DATA_CONNECTION_MODE} until the
* mode is changed by calling some other method such as {@link #enterLocalActiveMode enterLocalActiveMode() }
* data port to which the client will connect to conduct data transfers. The FTPClient will stay in {@link #PASSIVE_LOCAL_DATA_CONNECTION_MODE} until the
* mode is changed by calling some other method such as {@link #enterLocalActiveMode enterLocalActiveMode()}
* <p>
* <strong>N.B.</strong> currently calling any connect method will reset the mode to ACTIVE_LOCAL_DATA_CONNECTION_MODE.
* </p>
Expand Down Expand Up @@ -2031,7 +2031,7 @@ private FTPListParseEngine initiateListParsing(final FTPFileEntryParser parser,
/**
* Using the default autodetect mechanism, initialize an FTPListParseEngine object containing a raw file information for the supplied directory. This
* information is obtained through the LIST command. This object is then capable of being iterated to return a sequence of FTPFile objects with information
* filled in by the {@code FTPFileEntryParser} used.
* filled in by the {@link FTPFileEntryParser} used.
* <p>
* The server may or may not expand glob expressions. You should avoid using glob expressions because the return format for glob listings differs from
* server to server and will likely cause this method to fail.
Expand Down Expand Up @@ -2075,7 +2075,7 @@ public FTPListParseEngine initiateListParsing(final String path) throws IOExcept
/**
* Using the supplied parser key, initialize an FTPListParseEngine object containing a raw file information for the supplied directory. This information is
* obtained through the LIST command. This object is then capable of being iterated to return a sequence of FTPFile objects with information filled in by
* the {@code FTPFileEntryParser} used.
* the {@link FTPFileEntryParser} used.
* <p>
* The server may or may not expand glob expressions. You should avoid using glob expressions because the return format for glob listings differs from
* server to server and will likely cause this method to fail.
Expand All @@ -2085,7 +2085,7 @@ public FTPListParseEngine initiateListParsing(final String path) throws IOExcept
* lists.
* </p>
*
* @param parserKey A string representing a designated code or fully-qualified class name of an {@code FTPFileEntryParser} that should be used to parse each
* @param parserKey A string representing a designated code or fully-qualified class name of an {@link FTPFileEntryParser} that should be used to parse each
* server file listing. May be {@code null}, in which case the code checks first the system property {@link #FTP_SYSTEM_TYPE}, and if that
* is not defined the SYST command is used to provide the value. To allow for arbitrary system types, the return from the SYST command is
* used to look up an alias for the type in the {@link #SYSTEM_TYPE_PROPERTIES} properties file if it is available.
Expand Down Expand Up @@ -2181,7 +2181,7 @@ public boolean isUseEPSVwithIPv4() {
/**
* Using the default system autodetect mechanism, obtain a list of directories contained in the current working directory.
* <p>
* This information is obtained through the LIST command. The contents of the returned array is determined by the{@code FTPFileEntryParser} used.
* This information is obtained through the LIST command. The contents of the returned array is determined by the{@link FTPFileEntryParser} used.
* </p>
* <p>
* N.B. the LIST command does not generally return very precise timestamps. For recent files, the response usually contains hours and minutes (not seconds).
Expand Down Expand Up @@ -2213,7 +2213,7 @@ public FTPFile[] listDirectories() throws IOException {
/**
* Using the default system autodetect mechanism, obtain a list of directories contained in the specified directory.
* <p>
* This information is obtained through the LIST command. The contents of the returned array is determined by the{@code FTPFileEntryParser} used.
* This information is obtained through the LIST command. The contents of the returned array is determined by the{@link FTPFileEntryParser} used.
* </p>
* <p>
* N.B. the LIST command does not generally return very precise timestamps. For recent files, the response usually contains hours and minutes (not seconds).
Expand Down Expand Up @@ -2246,7 +2246,7 @@ public FTPFile[] listDirectories(final String parent) throws IOException {
/**
* Using the default system autodetect mechanism, obtain a list of file information for the current working directory.
* <p>
* This information is obtained through the LIST command. The contents of the returned array is determined by the{@code FTPFileEntryParser} used.
* This information is obtained through the LIST command. The contents of the returned array is determined by the {@link FTPFileEntryParser} used.
* </p>
* <p>
* N.B. the LIST command does not generally return very precise timestamps. For recent files, the response usually contains hours and minutes (not seconds).
Expand Down Expand Up @@ -2279,7 +2279,7 @@ public FTPFile[] listFiles() throws IOException {
/**
* Using the default system autodetect mechanism, obtain a list of file information for the current working directory or for just a single file.
* <p>
* This information is obtained through the LIST command. The contents of the returned array is determined by the{@code FTPFileEntryParser} used.
* This information is obtained through the LIST command. The contents of the returned array is determined by the {@link FTPFileEntryParser} used.
* </p>
* <p>
* N.B. the LIST command does not generally return very precise timestamps. For recent files, the response usually contains hours and minutes (not seconds).
Expand Down Expand Up @@ -3010,7 +3010,7 @@ public void setDataTimeout(final int timeoutMillis) {
}

/**
* Sets the file structure. The default structure is {@code FTP.FILE_STRUCTURE} if this method is never called or if a connect method is called.
* Sets the file structure. The default structure is {@link FTP#FILE_STRUCTURE} if this method is never called or if a connect method is called.
*
* @param fileStructure The structure of the file (one of the FTP class {@code _STRUCTURE} constants).
* @return True if successfully completed, false if not.
Expand All @@ -3028,7 +3028,7 @@ public boolean setFileStructure(final int fileStructure) throws IOException {
}

/**
* Sets the transfer mode. The default transfer mode {@code FTP.STREAM_TRANSFER_MODE} if this method is never called or if a connect method is called.
* Sets the transfer mode. The default transfer mode {@link FTP#STREAM_TRANSFER_MODE} if this method is never called or if a connect method is called.
*
* @param fileTransferMode The new transfer mode to use (one of the FTP class {@code _TRANSFER_MODE} constants).
* @return True if successfully completed, false if not.
Expand All @@ -3046,13 +3046,16 @@ public boolean setFileTransferMode(final int fileTransferMode) throws IOExceptio
}

/**
* Sets the file type to be transferred. This should be one of {@code FTP.ASCII_FILE_TYPE}, {@code FTP.BINARY_FILE_TYPE}, etc. The file type only needs to
* Sets the file type to be transferred. This should be one of {@link FTP#ASCII_FILE_TYPE}, {@link FTP#BINARY_FILE_TYPE}, etc. The file type only needs to
* be set when you want to change the type. After changing it, the new type stays in effect until you change it again. The default file type is
* {@code FTP.ASCII_FILE_TYPE} if this method is never called. <br>
* {@link FTP#ASCII_FILE_TYPE} if this method is never called.
* <p>
* The server default is supposed to be ASCII (see RFC 959), however many ftp servers default to BINARY. <b>To ensure correct operation with all servers,
* always specify the appropriate file type after connecting to the server.</b> <br>
* always specify the appropriate file type after connecting to the server.</b>
* </p>
* <p>
* <strong>N.B.</strong> currently calling any connect method will reset the type to FTP.ASCII_FILE_TYPE.
* <strong>N.B.</strong> currently calling any connect method will reset the type to {@link FTP#ASCII_FILE_TYPE}.
* </p>
*
* @param fileType The {@code _FILE_TYPE} constant indicating the type of file.
* @return True if successfully completed, false if not.
Expand All @@ -3071,16 +3074,20 @@ public boolean setFileType(final int fileType) throws IOException {
}

/**
* Sets the file type to be transferred and the format. The type should be one of {@code FTP.ASCII_FILE_TYPE}, {@code FTP.BINARY_FILE_TYPE}, etc. The file
* Sets the file type to be transferred and the format. The type should be one of {@link FTP#ASCII_FILE_TYPE}, {@link FTP#BINARY_FILE_TYPE}, etc. The file
* type only needs to be set when you want to change the type. After changing it, the new type stays in effect until you change it again. The default file
* type is {@code FTP.ASCII_FILE_TYPE} if this method is never called. <br>
* type is {@link FTP#ASCII_FILE_TYPE} if this method is never called.
* <p>
* The server default is supposed to be ASCII (see RFC 959), however many ftp servers default to BINARY. <b>To ensure correct operation with all servers,
* always specify the appropriate file type after connecting to the server.</b> <br>
* The format should be one of the FTP class {@code TEXT_FORMAT} constants, or if the type is {@code FTP.LOCAL_FILE_TYPE}, the format should be the byte
* size for that type. The default format is {@code FTP.NON_PRINT_TEXT_FORMAT} if this method is never called.
* always specify the appropriate file type after connecting to the server.</b>
* </p>
* <p>
* The format should be one of the FTP class {@code TEXT_FORMAT} constants, or if the type is {@link FTP#LOCAL_FILE_TYPE}, the format should be the byte
* size for that type. The default format is {@link FTP#NON_PRINT_TEXT_FORMAT} if this method is never called.
* </p>
* <p>
* <strong>N.B.</strong> currently calling any connect method will reset the type to FTP.ASCII_FILE_TYPE and the formatOrByteSize to
* FTP.NON_PRINT_TEXT_FORMAT.
* <strong>N.B.</strong> currently calling any connect method will reset the type to {@link FTP#ASCII_FILE_TYPE} and the formatOrByteSize to
* {@link FTP#NON_PRINT_TEXT_FORMAT}.
* </p>
*
* @param fileType The {@code _FILE_TYPE} constant indicating the type of file.
Expand Down Expand Up @@ -3193,7 +3200,7 @@ public void setPassiveNatWorkaround(final boolean enabled) {
/**
* Sets the workaround strategy to replace the PASV mode reply addresses. This gets around the problem that some NAT boxes may change the reply.
*
* The default implementation is {@code NatServerResolverImpl}, i.e. site-local replies are replaced.
* The default implementation is {@link NatServerResolverImpl}, i.e. site-local replies are replaced.
*
* @param passiveNatWorkaroundStrategy strategy to replace internal IP's in passive mode or null to disable the workaround (i.e. use PASV mode reply
* address.)
Expand Down

0 comments on commit 1d55795

Please sign in to comment.