This is an automated email from the ASF dual-hosted git repository. ggregory pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/commons-net.git
commit 3bb2db3ce9287ad1b85700b1e09583d739c10f36 Author: Gary Gregory <[email protected]> AuthorDate: Mon Sep 18 11:46:50 2023 -0400 Javadoc: Fix "warning: empty <p> tag" Add missing Javadoc --- .../org/apache/commons/net/bsd/RCommandClient.java | 21 ++--- .../org/apache/commons/net/ftp/FTPSClient.java | 22 +++++ .../net/nntp/NNTPConnectionClosedException.java | 1 - .../org/apache/commons/net/nntp/NNTPReply.java | 96 +++++++++++++++++++--- .../org/apache/commons/net/nntp/NewsgroupInfo.java | 5 -- .../apache/commons/net/nntp/SimpleNNTPHeader.java | 8 +- .../org/apache/commons/net/ntp/NTPUDPClient.java | 3 - .../org/apache/commons/net/ntp/NtpV3Packet.java | 17 +++- .../org/apache/commons/net/smtp/RelayPath.java | 4 - .../java/org/apache/commons/net/smtp/SMTP.java | 2 + .../org/apache/commons/net/smtp/SMTPClient.java | 1 - .../org/apache/commons/net/smtp/SMTPCommand.java | 57 +++++++++++-- .../net/smtp/SMTPConnectionClosedException.java | 1 - .../org/apache/commons/net/smtp/SMTPReply.java | 62 +++++++++++--- .../apache/commons/net/smtp/SimpleSMTPHeader.java | 5 +- .../net/telnet/InvalidTelnetOptionException.java | 2 - .../commons/net/telnet/SimpleOptionHandler.java | 2 - .../net/telnet/SuppressGAOptionHandler.java | 1 - .../apache/commons/net/telnet/TelnetClient.java | 2 +- .../apache/commons/net/telnet/TelnetCommand.java | 2 - .../commons/net/telnet/TelnetInputStream.java | 2 - .../net/telnet/TelnetNotificationHandler.java | 2 +- .../apache/commons/net/telnet/TelnetOption.java | 3 +- .../commons/net/telnet/TelnetOutputStream.java | 7 +- .../net/telnet/TerminalTypeOptionHandler.java | 4 - .../net/telnet/WindowSizeOptionHandler.java | 2 - 26 files changed, 243 insertions(+), 91 deletions(-) diff --git a/src/main/java/org/apache/commons/net/bsd/RCommandClient.java b/src/main/java/org/apache/commons/net/bsd/RCommandClient.java index a790f0b2..433fecb5 100644 --- a/src/main/java/org/apache/commons/net/bsd/RCommandClient.java +++ b/src/main/java/org/apache/commons/net/bsd/RCommandClient.java @@ -45,6 +45,7 @@ import org.apache.commons.net.io.SocketInputStream; * {@link #rcommand rcommand() } method, and then fetch the connection's input, output, and optionally error streams. Interaction with the remote command is * controlled entirely through the I/O streams. Once you have finished processing the streams, you should invoke * {@link org.apache.commons.net.bsd.RExecClient#disconnect disconnect() } to clean up properly. + * </p> * <p> * By default, the standard output and standard error streams of the remote process are transmitted over the same connection, readable from the input stream * returned by {@link org.apache.commons.net.bsd.RExecClient#getInputStream getInputStream() } . However, it is possible to tell the rshd daemon to return the @@ -52,12 +53,12 @@ import org.apache.commons.net.io.SocketInputStream; * getErrorStream() } . You can specify that a separate connection should be created for standard error by setting the boolean * <code> separateErrorStream </code> parameter of {@link #rcommand rcommand() } to <code> true </code>. The standard input of the remote process can be written * to through the output stream returned by {@link org.apache.commons.net.bsd.RExecClient#getOutputStream getOutputStream() } . + * </p> * * @see org.apache.commons.net.SocketClient * @see RExecClient * @see RLoginClient */ - public class RCommandClient extends RExecClient { /** * The default rshell port. Set to 514 in BSD Unix. @@ -247,13 +248,13 @@ public class RCommandClient extends RExecClient { /** * Same as <code> rcommand(localUsername, remoteUsername, command, false); </code> * - * @param localUsername the local user - * @param remoteUsername the remote user + * @param localUser the local user + * @param remoteUser the remote user * @param command the command * @throws IOException on error */ - public void rcommand(final String localUsername, final String remoteUsername, final String command) throws IOException { - rcommand(localUsername, remoteUsername, command, false); + public void rcommand(final String localUser, final String remoteUser, final String command) throws IOException { + rcommand(localUser, remoteUser, command, false); } /** @@ -268,16 +269,16 @@ public class RCommandClient extends RExecClient { * the remote server, an IOException will be thrown. This serves as a simple protection against possible hijacking of the error stream by an attacker * monitoring the rexec() negotiation. You may disable this behavior with {@link org.apache.commons.net.bsd.RExecClient#setRemoteVerificationEnabled * setRemoteVerificationEnabled()} . - * <p> + * </p> * - * @param localUsername The user account on the local machine that is requesting the command execution. - * @param remoteUsername The account name on the server through which to execute the command. + * @param localUser The user account on the local machine that is requesting the command execution. + * @param remoteUser The account name on the server through which to execute the command. * @param command The command, including any arguments, to execute. * @param separateErrorStream True if you would like the standard error to be transmitted through a different stream than standard output. False if not. * @throws IOException If the rcommand() attempt fails. The exception will contain a message indicating the nature of the failure. */ - public void rcommand(final String localUsername, final String remoteUsername, final String command, final boolean separateErrorStream) throws IOException { - rexec(localUsername, remoteUsername, command, separateErrorStream); + public void rcommand(final String localUser, final String remoteUser, final String command, final boolean separateErrorStream) throws IOException { + rexec(localUser, remoteUser, command, separateErrorStream); } } diff --git a/src/main/java/org/apache/commons/net/ftp/FTPSClient.java b/src/main/java/org/apache/commons/net/ftp/FTPSClient.java index 149c02e2..d699bca6 100644 --- a/src/main/java/org/apache/commons/net/ftp/FTPSClient.java +++ b/src/main/java/org/apache/commons/net/ftp/FTPSClient.java @@ -59,57 +59,79 @@ public class FTPSClient extends FTPClient { // ftps 990/tcp ftp protocol, control, over TLS/SSL // ftps 990/udp ftp protocol, control, over TLS/SSL + /** Default FTPS data port. */ public static final int DEFAULT_FTPS_DATA_PORT = 989; + + /** Default FTPS port. */ public static final int DEFAULT_FTPS_PORT = 990; /** The value that I can set in PROT command (C = Clear, P = Protected) */ private static final String[] PROT_COMMAND_VALUE = { "C", "E", "S", "P" }; + /** Default PROT Command */ private static final String DEFAULT_PROT = "C"; + /** Default secure socket protocol name, i.e. TLS */ private static final String DEFAULT_PROTOCOL = "TLS"; /** The AUTH (Authentication/Security Mechanism) command. */ private static final String CMD_AUTH = "AUTH"; + /** The ADAT (Authentication/Security Data) command. */ private static final String CMD_ADAT = "ADAT"; + /** The PROT (Data Channel Protection Level) command. */ private static final String CMD_PROT = "PROT"; + /** The PBSZ (Protection Buffer Size) command. */ private static final String CMD_PBSZ = "PBSZ"; + /** The MIC (Integrity Protected Command) command. */ private static final String CMD_MIC = "MIC"; + /** The CONF (Confidentiality Protected Command) command. */ private static final String CMD_CONF = "CONF"; + /** The ENC (Privacy Protected Command) command. */ private static final String CMD_ENC = "ENC"; + /** The CCC (Clear Command Channel) command. */ private static final String CMD_CCC = "CCC"; /** @deprecated - not used - may be removed in a future release */ @Deprecated public static String KEYSTORE_ALGORITHM; + /** @deprecated - not used - may be removed in a future release */ @Deprecated public static String TRUSTSTORE_ALGORITHM; + /** @deprecated - not used - may be removed in a future release */ @Deprecated public static String PROVIDER; + /** @deprecated - not used - may be removed in a future release */ @Deprecated public static String STORE_TYPE; + /** The security mode. (True - Implicit Mode / False - Explicit Mode) */ private final boolean isImplicit; + /** The secure socket protocol to be used, e.g. SSL/TLS. */ private final String protocol; + /** The AUTH Command value */ private String auth = DEFAULT_PROTOCOL; + /** The context object. */ private SSLContext context; + /** The socket object. */ private Socket plainSocket; + /** Controls whether a new SSL session may be established by this socket. Default true. */ private boolean isCreation = true; + /** The use client mode flag. */ private boolean isClientMode = true; diff --git a/src/main/java/org/apache/commons/net/nntp/NNTPConnectionClosedException.java b/src/main/java/org/apache/commons/net/nntp/NNTPConnectionClosedException.java index b5e04e27..cd63833a 100644 --- a/src/main/java/org/apache/commons/net/nntp/NNTPConnectionClosedException.java +++ b/src/main/java/org/apache/commons/net/nntp/NNTPConnectionClosedException.java @@ -38,7 +38,6 @@ public final class NNTPConnectionClosedException extends IOException { /** * Constructs a NNTPConnectionClosedException with a specified message. - * <p> * * @param message The message explaining the reason for the exception. */ diff --git a/src/main/java/org/apache/commons/net/nntp/NNTPReply.java b/src/main/java/org/apache/commons/net/nntp/NNTPReply.java index 1e44c727..6221ec9e 100644 --- a/src/main/java/org/apache/commons/net/nntp/NNTPReply.java +++ b/src/main/java/org/apache/commons/net/nntp/NNTPReply.java @@ -21,53 +21,129 @@ package org.apache.commons.net.nntp; * NNTPReply stores a set of constants for NNTP reply codes. To interpret the meaning of the codes, familiarity with RFC 977 is assumed. The mnemonic constant * names are transcriptions from the code descriptions of RFC 977. */ - public final class NNTPReply { + /** NNTP reply code {@value}. */ public static final int HELP_TEXT_FOLLOWS = 100; + + /** NNTP reply code {@value}. */ public static final int DEBUG_OUTPUT = 199; + + /** NNTP reply code {@value}. */ public static final int SERVER_READY_POSTING_ALLOWED = 200; + + /** NNTP reply code {@value}. */ public static final int SERVER_READY_POSTING_NOT_ALLOWED = 201; + + /** NNTP reply code {@value}. */ public static final int SLAVE_STATUS_NOTED = 202; + + /** NNTP reply code {@value}. */ public static final int CLOSING_CONNECTION = 205; + + /** NNTP reply code {@value}. */ public static final int GROUP_SELECTED = 211; + + /** NNTP reply code {@value}. */ public static final int ARTICLE_RETRIEVED_HEAD_AND_BODY_FOLLOW = 220; + + /** NNTP reply code {@value}. */ public static final int ARTICLE_RETRIEVED_HEAD_FOLLOWS = 221; + + /** NNTP reply code {@value}. */ public static final int ARTICLE_RETRIEVED_BODY_FOLLOWS = 222; + + /** NNTP reply code {@value}. */ public static final int ARTICLE_RETRIEVED_REQUEST_TEXT_SEPARATELY = 223; + + /** NNTP reply code {@value}. */ public static final int ARTICLE_LIST_BY_MESSAGE_ID_FOLLOWS = 230; + + /** NNTP reply code {@value}. */ public static final int NEW_NEWSGROUP_LIST_FOLLOWS = 231; + + /** NNTP reply code {@value}. */ public static final int ARTICLE_TRANSFERRED_OK = 235; + + /** NNTP reply code {@value}. */ public static final int ARTICLE_POSTED_OK = 240; + + /** NNTP reply code {@value}. */ public static final int AUTHENTICATION_ACCEPTED = 281; + + /** NNTP reply code {@value}. */ public static final int SEND_ARTICLE_TO_TRANSFER = 335; + + /** NNTP reply code {@value}. */ public static final int SEND_ARTICLE_TO_POST = 340; + + /** NNTP reply code {@value}. */ public static final int MORE_AUTH_INFO_REQUIRED = 381; + + /** NNTP reply code {@value}. */ public static final int SERVICE_DISCONTINUED = 400; + + /** NNTP reply code {@value}. */ public static final int NO_SUCH_NEWSGROUP = 411; + + /** NNTP reply code {@value}. */ public static final int NO_NEWSGROUP_SELECTED = 412; + + /** NNTP reply code {@value}. */ public static final int NO_CURRENT_ARTICLE_SELECTED = 420; + + /** NNTP reply code {@value}. */ public static final int NO_NEXT_ARTICLE = 421; + + /** NNTP reply code {@value}. */ public static final int NO_PREVIOUS_ARTICLE = 422; + + /** NNTP reply code {@value}. */ public static final int NO_SUCH_ARTICLE_NUMBER = 423; + + /** NNTP reply code {@value}. */ public static final int NO_SUCH_ARTICLE_FOUND = 430; + + /** NNTP reply code {@value}. */ public static final int ARTICLE_NOT_WANTED = 435; + + /** NNTP reply code {@value}. */ public static final int TRANSFER_FAILED = 436; + + /** NNTP reply code {@value}. */ public static final int ARTICLE_REJECTED = 437; + + /** NNTP reply code {@value}. */ public static final int POSTING_NOT_ALLOWED = 440; + + /** NNTP reply code {@value}. */ public static final int POSTING_FAILED = 441; - /** @since 2.2 - corrected value to 480 */ + + /** + * NNTP reply code {@value}. + * + * @since 2.2 - corrected value to 480 + */ public static final int AUTHENTICATION_REQUIRED = 480; + + /** NNTP reply code {@value}. */ public static final int AUTHENTICATION_REJECTED = 482; + + /** NNTP reply code {@value}. */ public static final int COMMAND_NOT_RECOGNIZED = 500; + + /** NNTP reply code {@value}. */ public static final int COMMAND_SYNTAX_ERROR = 501; + + /** NNTP reply code {@value}. */ public static final int PERMISSION_DENIED = 502; + + /** NNTP reply code {@value}. */ public static final int PROGRAM_FAULT = 503; /** - * Determine if a reply code is an informational response. All codes beginning with a 1 are positive informational responses. Informational responses are + * Tests if a reply code is an informational response. All codes beginning with a 1 are positive informational responses. Informational responses are * used to provide human-readable information such as help text. - * <p> * * @param reply The reply code to test. * @return True if a reply code is an informational response, false if not. @@ -77,9 +153,8 @@ public final class NNTPReply { } /** - * Determine if a reply code is a negative permanent response. All codes beginning with a 5 are negative permanent responses. The NNTP server will send a + * Tests if a reply code is a negative permanent response. All codes beginning with a 5 are negative permanent responses. The NNTP server will send a * negative permanent response when it does not implement a command, a command is incorrectly formatted, or a serious program error occurs. - * <p> * * @param reply The reply code to test. * @return True if a reply code is a negative permanent response, false if not. @@ -89,10 +164,9 @@ public final class NNTPReply { } /** - * Determine if a reply code is a negative transient response. All codes beginning with a 4 are negative transient responses. The NNTP server will send a + * Tests if a reply code is a negative transient response. All codes beginning with a 4 are negative transient responses. The NNTP server will send a * negative transient response on the failure of a correctly formatted command that could not be performed for some reason. For example, retrieving an * article that does not exist will result in a negative transient response. - * <p> * * @param reply The reply code to test. * @return True if a reply code is a negative transient response, false if not. @@ -102,9 +176,8 @@ public final class NNTPReply { } /** - * Determine if a reply code is a positive completion response. All codes beginning with a 2 are positive completion responses. The NNTP server will send a + * Tests if a reply code is a positive completion response. All codes beginning with a 2 are positive completion responses. The NNTP server will send a * positive completion response on the final successful completion of a command. - * <p> * * @param reply The reply code to test. * @return True if a reply code is a positive completion response, false if not. @@ -114,10 +187,9 @@ public final class NNTPReply { } /** - * Determine if a reply code is a positive intermediate response. All codes beginning with a 3 are positive intermediate responses. The NNTP server will + * Tests if a reply code is a positive intermediate response. All codes beginning with a 3 are positive intermediate responses. The NNTP server will * send a positive intermediate response on the successful completion of one part of a multipart command or sequence of commands. For example, after a * successful POST command, a positive intermediate response will be sent to indicate that the server is ready to receive the article to be posted. - * <p> * * @param reply The reply code to test. * @return True if a reply code is a positive intermediate response, false if not. diff --git a/src/main/java/org/apache/commons/net/nntp/NewsgroupInfo.java b/src/main/java/org/apache/commons/net/nntp/NewsgroupInfo.java index 3952cb47..db1d68f6 100644 --- a/src/main/java/org/apache/commons/net/nntp/NewsgroupInfo.java +++ b/src/main/java/org/apache/commons/net/nntp/NewsgroupInfo.java @@ -56,7 +56,6 @@ public final class NewsgroupInfo { /** * Get the estimated number of articles in the newsgroup. The accuracy of this value will depend on the server implementation. - * <p> * * @return The estimated number of articles in the newsgroup. */ @@ -71,7 +70,6 @@ public final class NewsgroupInfo { /** * Get the number of the first article in the newsgroup. - * <p> * * @return The number of the first article in the newsgroup. */ @@ -86,7 +84,6 @@ public final class NewsgroupInfo { /** * Get the number of the last article in the newsgroup. - * <p> * * @return The number of the last article in the newsgroup. */ @@ -96,7 +93,6 @@ public final class NewsgroupInfo { /** * Get the newsgroup name. - * <p> * * @return The name of the newsgroup. */ @@ -106,7 +102,6 @@ public final class NewsgroupInfo { /** * Get the posting permission of the newsgroup. This will be one of the <code> POSTING_PERMISSION </code> constants. - * <p> * * @return The posting permission status of the newsgroup. */ diff --git a/src/main/java/org/apache/commons/net/nntp/SimpleNNTPHeader.java b/src/main/java/org/apache/commons/net/nntp/SimpleNNTPHeader.java index 715ebcbc..2ff5d822 100644 --- a/src/main/java/org/apache/commons/net/nntp/SimpleNNTPHeader.java +++ b/src/main/java/org/apache/commons/net/nntp/SimpleNNTPHeader.java @@ -23,6 +23,7 @@ package org.apache.commons.net.nntp; * <p> * The main purpose of the class is to faciliatate the article posting process, by relieving the programmer from having to explicitly format an article header. * For example: + * </p> * * <pre> * writer = client.postArticle(); @@ -49,7 +50,6 @@ public class SimpleNNTPHeader { /** * Creates a new SimpleNNTPHeader instance initialized with the given from and subject header field values. - * <p> * * @param from The value of the <code>From:</code> header field. This should be the article poster's email address. * @param subject The value of the <code>Subject:</code> header field. This should be the subject of the article. @@ -70,7 +70,6 @@ public class SimpleNNTPHeader { * <pre> * header.addHeaderField("Organization", "Foobar, Inc."); * </pre> - * <p> * * @param headerField The header field to add, not including the colon. * @param value The value of the added header field. @@ -84,7 +83,6 @@ public class SimpleNNTPHeader { /** * Adds a newsgroup to the article <code>Newsgroups:</code> field. - * <p> * * @param newsgroup The newsgroup to add to the article's newsgroup distribution list. */ @@ -97,7 +95,6 @@ public class SimpleNNTPHeader { /** * Returns the address used in the <code> From: </code> header field. - * <p> * * @return The from address. */ @@ -107,7 +104,6 @@ public class SimpleNNTPHeader { /** * Returns the contents of the <code> Newsgroups: </code> header field. - * <p> * * @return The comma-separated list of newsgroups to which the article is being posted. */ @@ -117,7 +113,6 @@ public class SimpleNNTPHeader { /** * Returns the subject used in the <code> Subject: </code> header field. - * <p> * * @return The subject. */ @@ -128,7 +123,6 @@ public class SimpleNNTPHeader { /** * Converts the SimpleNNTPHeader to a properly formatted header in the form of a String, including the blank line used to separate the header from the * article body. - * <p> * * @return The article header in the form of a String. */ diff --git a/src/main/java/org/apache/commons/net/ntp/NTPUDPClient.java b/src/main/java/org/apache/commons/net/ntp/NTPUDPClient.java index c606252f..8afc323a 100644 --- a/src/main/java/org/apache/commons/net/ntp/NTPUDPClient.java +++ b/src/main/java/org/apache/commons/net/ntp/NTPUDPClient.java @@ -30,7 +30,6 @@ import org.apache.commons.net.DatagramSocketClient; * calls to <a href="#getTime"> getTime </a> are permitted without re-establishing a connection. That is because UDP is a connectionless protocol and the * Network Time Protocol is stateless. */ - public final class NTPUDPClient extends DatagramSocketClient { /** The default NTP port. It is set to 123 according to RFC 1305. */ public static final int DEFAULT_PORT = 123; @@ -41,7 +40,6 @@ public final class NTPUDPClient extends DatagramSocketClient { * Retrieves the time information from the specified server on the default NTP port and returns it. The time is the number of milliseconds since 00:00 * (midnight) 1 January 1900 UTC, as specified by RFC 1305. This method reads the raw NTP packet and constructs a <i>TimeInfo</i> object that allows access * to all the fields of the NTP message header. - * <p> * * @param host The address of the server. * @return The time value retrieved from the server. @@ -55,7 +53,6 @@ public final class NTPUDPClient extends DatagramSocketClient { * Retrieves the time information from the specified server and port and returns it. The time is the number of milliseconds since 00:00 (midnight) 1 January * 1900 UTC, as specified by RFC 1305. This method reads the raw NTP packet and constructs a <i>TimeInfo</i> object that allows access to all the fields of * the NTP message header. - * <p> * * @param host The address of the server. * @param port The port of the service. diff --git a/src/main/java/org/apache/commons/net/ntp/NtpV3Packet.java b/src/main/java/org/apache/commons/net/ntp/NtpV3Packet.java index 46654211..a43aa9b9 100644 --- a/src/main/java/org/apache/commons/net/ntp/NtpV3Packet.java +++ b/src/main/java/org/apache/commons/net/ntp/NtpV3Packet.java @@ -34,14 +34,29 @@ public interface NtpV3Packet { int LI_LAST_MINUTE_HAS_59_SECONDS = 2; int LI_ALARM_CONDITION = 3; - /* mode options */ + // mode options + /** Mode option {@value}. */ int MODE_RESERVED = 0; + + /** Mode option {@value}. */ int MODE_SYMMETRIC_ACTIVE = 1; + + /** Mode option {@value}. */ int MODE_SYMMETRIC_PASSIVE = 2; + + /** Mode option {@value}. */ int MODE_CLIENT = 3; + + /** Mode option {@value}. */ int MODE_SERVER = 4; + + /** Mode option {@value}. */ int MODE_BROADCAST = 5; + + /** Mode option {@value}. */ int MODE_CONTROL_MESSAGE = 6; + + /** Mode option {@value}. */ int MODE_PRIVATE = 7; int NTP_MINPOLL = 4; // 16 seconds diff --git a/src/main/java/org/apache/commons/net/smtp/RelayPath.java b/src/main/java/org/apache/commons/net/smtp/RelayPath.java index b8d3ed71..defb809c 100644 --- a/src/main/java/org/apache/commons/net/smtp/RelayPath.java +++ b/src/main/java/org/apache/commons/net/smtp/RelayPath.java @@ -26,14 +26,12 @@ import java.util.Vector; * * @see SMTPClient */ - public final class RelayPath { private final Vector<String> path; private final String emailAddress; /** * Create a relay path with the specified email address as the ultimate destination. - * <p> * * @param emailAddress The destination email address. */ @@ -51,7 +49,6 @@ public final class RelayPath { * path.addRelay("bar.com"); * path.addRelay("foo.com"); * </pre> - * <p> * * @param hostname The host to add to the relay path. */ @@ -61,7 +58,6 @@ public final class RelayPath { /** * Return the properly formatted string representation of the relay path. - * <p> * * @return The properly formatted string representation of the relay path. */ diff --git a/src/main/java/org/apache/commons/net/smtp/SMTP.java b/src/main/java/org/apache/commons/net/smtp/SMTP.java index a242c736..589d402d 100644 --- a/src/main/java/org/apache/commons/net/smtp/SMTP.java +++ b/src/main/java/org/apache/commons/net/smtp/SMTP.java @@ -46,11 +46,13 @@ import org.apache.commons.net.util.NetConstants; * {@link org.apache.commons.net.SocketClient#disconnect disconnect() } to properly clean up the system resources used by SMTP. Before disconnecting, you may * check the last reply code and text with {@link #getReplyCode getReplyCode }, {@link #getReplyString getReplyString }, and {@link #getReplyStrings * getReplyStrings}. + * </p> * <p> * Rather than list it separately for each method, we mention here that every method communicating with the server and throwing an IOException can also throw a * {@link org.apache.commons.net.MalformedServerReplyException} , which is a subclass of IOException. A MalformedServerReplyException will be thrown when the * reply received from the server deviates enough from the protocol specification that it cannot be interpreted in a useful manner despite attempts to be as * lenient as possible. + * </p> * * @see SMTPClient * @see SMTPConnectionClosedException diff --git a/src/main/java/org/apache/commons/net/smtp/SMTPClient.java b/src/main/java/org/apache/commons/net/smtp/SMTPClient.java index 687c2f3c..0cbd6ed2 100644 --- a/src/main/java/org/apache/commons/net/smtp/SMTPClient.java +++ b/src/main/java/org/apache/commons/net/smtp/SMTPClient.java @@ -92,7 +92,6 @@ import org.apache.commons.net.io.DotTerminatedMessageWriter; * @see SMTPConnectionClosedException * @see org.apache.commons.net.MalformedServerReplyException */ - public class SMTPClient extends SMTP { /** diff --git a/src/main/java/org/apache/commons/net/smtp/SMTPCommand.java b/src/main/java/org/apache/commons/net/smtp/SMTPCommand.java index 45289046..14f514d7 100644 --- a/src/main/java/org/apache/commons/net/smtp/SMTPCommand.java +++ b/src/main/java/org/apache/commons/net/smtp/SMTPCommand.java @@ -24,19 +24,46 @@ package org.apache.commons.net.smtp; */ public final class SMTPCommand { + /** SMTP command {@value}. */ public static final int HELO = 0; + + /** SMTP command {@value}. */ public static final int MAIL = 1; + + /** SMTP command {@value}. */ public static final int RCPT = 2; + + /** SMTP command {@value}. */ public static final int DATA = 3; + + /** SMTP command {@value}. */ public static final int SEND = 4; + + /** SMTP command {@value}. */ public static final int SOML = 5; + + /** SMTP command {@value}. */ public static final int SAML = 6; + + /** SMTP command {@value}. */ public static final int RSET = 7; + + /** SMTP command {@value}. */ public static final int VRFY = 8; + + /** SMTP command {@value}. */ public static final int EXPN = 9; + + /** SMTP command {@value}. */ public static final int HELP = 10; + + /** SMTP command {@value}. */ public static final int NOOP = 11; + + /** SMTP command {@value}. */ public static final int TURN = 12; + + /** SMTP command {@value}. */ public static final int QUIT = 13; /** @@ -55,21 +82,40 @@ public final class SMTPCommand { private static final int NEXT = EHLO + 1; // update as necessary when adding new entries + /** Alias for {@value}. */ public static final int HELLO = HELO; + + /** Alias for {@value}. */ public static final int LOGIN = HELO; + + /** Alias for {@value}. */ public static final int MAIL_FROM = MAIL; + + /** Alias for {@value}. */ public static final int RECIPIENT = RCPT; + + /** Alias for {@value}. */ public static final int SEND_MESSAGE_DATA = DATA; + + /** Alias for {@value}. */ public static final int SEND_FROM = SEND; + + /** Alias for {@value}. */ public static final int SEND_OR_MAIL_FROM = SOML; + + /** Alias for {@value}. */ public static final int SEND_AND_MAIL_FROM = SAML; + + /** Alias for {@value}. */ public static final int RESET = RSET; + + /** Alias for {@value}. */ public static final int VERIFY = VRFY; + + /** Alias for {@value}. */ public static final int EXPAND = EXPN; - // public static final int HELP = HELP; - // public static final int NOOP = NOOP; - // public static final int TURN = TURN; - // public static final int QUIT = QUIT; + + /** Alias for {@value}. */ public static final int LOGOUT = QUIT; private static final String[] commands = { "HELO", "MAIL FROM:", "RCPT TO:", "DATA", "SEND FROM:", "SOML FROM:", "SAML FROM:", "RSET", "VRFY", "EXPN", @@ -82,8 +128,7 @@ public final class SMTPCommand { } /** - * Retrieve the SMTP protocol command string corresponding to a specified command code. - * <p> + * Gets the SMTP protocol command string corresponding to a specified command code. * * @param command The command code. * @return The SMTP protocol command string corresponding to a specified command code. diff --git a/src/main/java/org/apache/commons/net/smtp/SMTPConnectionClosedException.java b/src/main/java/org/apache/commons/net/smtp/SMTPConnectionClosedException.java index 04745ca1..3b6a1fad 100644 --- a/src/main/java/org/apache/commons/net/smtp/SMTPConnectionClosedException.java +++ b/src/main/java/org/apache/commons/net/smtp/SMTPConnectionClosedException.java @@ -28,7 +28,6 @@ import java.io.IOException; * @see SMTP * @see SMTPClient */ - public final class SMTPConnectionClosedException extends IOException { private static final long serialVersionUID = 626520434326660627L; diff --git a/src/main/java/org/apache/commons/net/smtp/SMTPReply.java b/src/main/java/org/apache/commons/net/smtp/SMTPReply.java index 41e374d8..13c95894 100644 --- a/src/main/java/org/apache/commons/net/smtp/SMTPReply.java +++ b/src/main/java/org/apache/commons/net/smtp/SMTPReply.java @@ -21,35 +21,76 @@ package org.apache.commons.net.smtp; * SMTPReply stores a set of constants for SMTP reply codes. To interpret the meaning of the codes, familiarity with RFC 821 is assumed. The mnemonic constant * names are transcriptions from the code descriptions of RFC 821. */ - public final class SMTPReply { + /** SMTP reply code {@value}. */ public static final int SYSTEM_STATUS = 211; + + /** SMTP reply code {@value}. */ public static final int HELP_MESSAGE = 214; + + /** SMTP reply code {@value}. */ public static final int SERVICE_READY = 220; + + /** SMTP reply code {@value}. */ public static final int SERVICE_CLOSING_TRANSMISSION_CHANNEL = 221; + + /** SMTP reply code {@value}. */ public static final int ACTION_OK = 250; + + /** SMTP reply code {@value}. */ public static final int USER_NOT_LOCAL_WILL_FORWARD = 251; + + /** SMTP reply code {@value}. */ public static final int START_MAIL_INPUT = 354; + + /** SMTP reply code {@value}. */ public static final int SERVICE_NOT_AVAILABLE = 421; + + /** SMTP reply code {@value}. */ public static final int ACTION_NOT_TAKEN = 450; + + /** SMTP reply code {@value}. */ public static final int ACTION_ABORTED = 451; + + /** SMTP reply code {@value}. */ public static final int INSUFFICIENT_STORAGE = 452; + + /** SMTP reply code {@value}. */ public static final int UNRECOGNIZED_COMMAND = 500; + + /** SMTP reply code {@value}. */ public static final int SYNTAX_ERROR_IN_ARGUMENTS = 501; + + /** SMTP reply code {@value}. */ public static final int COMMAND_NOT_IMPLEMENTED = 502; + + /** SMTP reply code {@value}. */ public static final int BAD_COMMAND_SEQUENCE = 503; + + /** SMTP reply code {@value}. */ public static final int COMMAND_NOT_IMPLEMENTED_FOR_PARAMETER = 504; + + /** SMTP reply code {@value}. */ public static final int MAILBOX_UNAVAILABLE = 550; + + /** SMTP reply code {@value}. */ public static final int USER_NOT_LOCAL = 551; + + /** SMTP reply code {@value}. */ + + /** SMTP reply code {@value}. */ public static final int STORAGE_ALLOCATION_EXCEEDED = 552; + + /** SMTP reply code {@value}. */ public static final int MAILBOX_NAME_NOT_ALLOWED = 553; + + /** SMTP reply code {@value}. */ public static final int TRANSACTION_FAILED = 554; /** - * Determine if a reply code is a negative permanent response. All codes beginning with a 5 are negative permanent responses. The SMTP server will send a + * Tests if a reply code is a negative permanent response. All codes beginning with a 5 are negative permanent responses. The SMTP server will send a * negative permanent response on the failure of a command that cannot be reattempted with success. - * <p> * * @param reply The reply code to test. * @return True if a reply code is a negative permanent response, false if not. @@ -59,9 +100,8 @@ public final class SMTPReply { } /** - * Determine if a reply code is a negative transient response. All codes beginning with a 4 are negative transient responses. The SMTP server will send a + * Tests if a reply code is a negative transient response. All codes beginning with a 4 are negative transient responses. The SMTP server will send a * negative transient response on the failure of a command that can be reattempted with success. - * <p> * * @param reply The reply code to test. * @return True if a reply code is a negative transient response, false if not. @@ -71,9 +111,8 @@ public final class SMTPReply { } /** - * Determine if a reply code is a positive completion response. All codes beginning with a 2 are positive completion responses. The SMTP server will send a + * Tests if a reply code is a positive completion response. All codes beginning with a 2 are positive completion responses. The SMTP server will send a * positive completion response on the final successful completion of a command. - * <p> * * @param reply The reply code to test. * @return True if a reply code is a positive completion response, false if not. @@ -83,10 +122,9 @@ public final class SMTPReply { } /** - * Determine if a reply code is a positive intermediate response. All codes beginning with a 3 are positive intermediate responses. The SMTP server will + * Tests if a reply code is a positive intermediate response. All codes beginning with a 3 are positive intermediate responses. The SMTP server will * send a positive intermediate response on the successful completion of one part of a multipart sequence of commands. For example, after a successful DATA * command, a positive intermediate response will be sent to indicate that the server is ready to receive the message data. - * <p> * * @param reply The reply code to test. * @return True if a reply code is a positive intermediate response, false if not. @@ -96,12 +134,12 @@ public final class SMTPReply { } /** - * Determine if a reply code is a positive preliminary response. All codes beginning with a 1 are positive preliminary responses. Positive preliminary + * Tests if a reply code is a positive preliminary response. All codes beginning with a 1 are positive preliminary responses. Positive preliminary * responses are used to indicate tentative success. No further commands can be issued to the SMTP server after a positive preliminary response until a * follow-up response is received from the server. * <p> - * <b> Note: </b> <em> No SMTP commands defined in RFC 822 provide this type of reply. </em> - * <p> + * <b>Note:</b> <em> No SMTP commands defined in RFC 822 provide this type of reply. </em> + * </p> * * @param reply The reply code to test. * @return True if a reply code is a positive preliminary response, false if not. diff --git a/src/main/java/org/apache/commons/net/smtp/SimpleSMTPHeader.java b/src/main/java/org/apache/commons/net/smtp/SimpleSMTPHeader.java index f86b926d..62bc8b8a 100644 --- a/src/main/java/org/apache/commons/net/smtp/SimpleSMTPHeader.java +++ b/src/main/java/org/apache/commons/net/smtp/SimpleSMTPHeader.java @@ -27,6 +27,7 @@ import java.util.Locale; * <p> * The main purpose of the class is to facilitate the mail sending process, by relieving the programmer from having to explicitly format a simple message * header. For example: + * </p> * * <pre> * writer = client.sendMessageData(); @@ -56,7 +57,6 @@ public class SimpleSMTPHeader { /** * Creates a new SimpleSMTPHeader instance initialized with the given from, to, and subject header field values. - * <p> * * @param from The value of the <code>From:</code> header field. This should be the sender's email address. Must not be null. * @param to The value of the <code>To:</code> header field. This should be the recipient's email address. May be null @@ -75,7 +75,6 @@ public class SimpleSMTPHeader { /** * Add an email address to the CC (carbon copy or courtesy copy) list. - * <p> * * @param address The email address to add to the CC list. */ @@ -97,7 +96,6 @@ public class SimpleSMTPHeader { * <pre> * header.addHeaderField("Organization", "Foobar, Inc."); * </pre> - * <p> * * @param headerField The header field to add, not including the colon. * @param value The value of the added header field. @@ -115,7 +113,6 @@ public class SimpleSMTPHeader { /** * Converts the SimpleSMTPHeader to a properly formatted header in the form of a String, including the blank line used to separate the header from the * article body. The header fields CC and Subject are only included when they are non-null. - * <p> * * @return The message header in the form of a String. */ diff --git a/src/main/java/org/apache/commons/net/telnet/InvalidTelnetOptionException.java b/src/main/java/org/apache/commons/net/telnet/InvalidTelnetOptionException.java index c3b3a639..1f821d0a 100644 --- a/src/main/java/org/apache/commons/net/telnet/InvalidTelnetOptionException.java +++ b/src/main/java/org/apache/commons/net/telnet/InvalidTelnetOptionException.java @@ -37,7 +37,6 @@ public class InvalidTelnetOptionException extends Exception { /** * Constructor for the exception. - * <p> * * @param message - Error message. * @param optcode - Option code. @@ -49,7 +48,6 @@ public class InvalidTelnetOptionException extends Exception { /** * Gets the error message of ths exception. - * <p> * * @return the error message. */ diff --git a/src/main/java/org/apache/commons/net/telnet/SimpleOptionHandler.java b/src/main/java/org/apache/commons/net/telnet/SimpleOptionHandler.java index 6929b5b2..d746cccc 100644 --- a/src/main/java/org/apache/commons/net/telnet/SimpleOptionHandler.java +++ b/src/main/java/org/apache/commons/net/telnet/SimpleOptionHandler.java @@ -23,7 +23,6 @@ package org.apache.commons.net.telnet; public class SimpleOptionHandler extends TelnetOptionHandler { /** * Constructor for the SimpleOptionHandler. Initial and accept behavior flags are set to false - * <p> * * @param optcode - option code. */ @@ -34,7 +33,6 @@ public class SimpleOptionHandler extends TelnetOptionHandler { /** * Constructor for the SimpleOptionHandler. Allows defining desired initial setting for local/remote activation of this option and behavior in case a * local/remote activation request for this option is received. - * <p> * * @param optcode - option code. * @param initlocal - if set to true, a WILL is sent upon connection. diff --git a/src/main/java/org/apache/commons/net/telnet/SuppressGAOptionHandler.java b/src/main/java/org/apache/commons/net/telnet/SuppressGAOptionHandler.java index 17fb5413..35322fee 100644 --- a/src/main/java/org/apache/commons/net/telnet/SuppressGAOptionHandler.java +++ b/src/main/java/org/apache/commons/net/telnet/SuppressGAOptionHandler.java @@ -31,7 +31,6 @@ public class SuppressGAOptionHandler extends TelnetOptionHandler { /** * Constructor for the SuppressGAOptionHandler. Allows defining desired initial setting for local/remote activation of this option and behavior in case a * local/remote activation request for this option is received. - * <p> * * @param initlocal - if set to true, a WILL is sent upon connection. * @param initremote - if set to true, a DO is sent upon connection. diff --git a/src/main/java/org/apache/commons/net/telnet/TelnetClient.java b/src/main/java/org/apache/commons/net/telnet/TelnetClient.java index b402fbab..2b5da2d5 100644 --- a/src/main/java/org/apache/commons/net/telnet/TelnetClient.java +++ b/src/main/java/org/apache/commons/net/telnet/TelnetClient.java @@ -31,8 +31,8 @@ import java.time.Duration; * InputStream and OutputStream for sending and receiving data over the Telnet connection can be obtained by using the {@link #getInputStream getInputStream() } * and {@link #getOutputStream getOutputStream() } methods. When you finish using the streams, you must call {@link #disconnect disconnect } rather than simply * closing the streams. + * </p> */ - public class TelnetClient extends Telnet { private static final int DEFAULT_MAX_SUBNEGOTIATION_LENGTH = 512; diff --git a/src/main/java/org/apache/commons/net/telnet/TelnetCommand.java b/src/main/java/org/apache/commons/net/telnet/TelnetCommand.java index e6e832c5..d86d540c 100644 --- a/src/main/java/org/apache/commons/net/telnet/TelnetCommand.java +++ b/src/main/java/org/apache/commons/net/telnet/TelnetCommand.java @@ -100,7 +100,6 @@ public final class TelnetCommand { /** * Returns the string representation of the telnet protocol command corresponding to the given command code. - * <p> * * @param code The command code of the telnet protocol command. * @return The string representation of the telnet protocol command. @@ -111,7 +110,6 @@ public final class TelnetCommand { /** * Determines if a given command code is valid. Returns true if valid, false if not. - * <p> * * @param code The command code to test. * @return True if the command code is valid, false if not. diff --git a/src/main/java/org/apache/commons/net/telnet/TelnetInputStream.java b/src/main/java/org/apache/commons/net/telnet/TelnetInputStream.java index 0567afde..fafe42f9 100644 --- a/src/main/java/org/apache/commons/net/telnet/TelnetInputStream.java +++ b/src/main/java/org/apache/commons/net/telnet/TelnetInputStream.java @@ -431,7 +431,6 @@ final class TelnetInputStream extends BufferedInputStream implements Runnable { /** * Reads the next number of bytes from the stream into an array and returns the number of bytes read. Returns -1 if the end of the stream has been reached. - * <p> * * @param buffer The byte array in which to store the data. * @return The number of bytes read. Returns -1 if the end of the message has been reached. @@ -445,7 +444,6 @@ final class TelnetInputStream extends BufferedInputStream implements Runnable { /** * Reads the next number of bytes from the stream into an array and returns the number of bytes read. Returns -1 if the end of the message has been reached. * The characters are stored in the array starting from the given offset and up to the length specified. - * <p> * * @param buffer The byte array in which to store the data. * @param offset The offset into the array at which to start storing data. diff --git a/src/main/java/org/apache/commons/net/telnet/TelnetNotificationHandler.java b/src/main/java/org/apache/commons/net/telnet/TelnetNotificationHandler.java index 0fe53b11..2506a452 100644 --- a/src/main/java/org/apache/commons/net/telnet/TelnetNotificationHandler.java +++ b/src/main/java/org/apache/commons/net/telnet/TelnetNotificationHandler.java @@ -22,8 +22,8 @@ package org.apache.commons.net.telnet; * <p> * The user can implement this interface and register a TelnetNotificationHandler by using the registerNotificationHandler() of TelnetClient to be notified of * option negotiation commands. + * </p> */ - public interface TelnetNotificationHandler { /** * The remote party sent a DO command. diff --git a/src/main/java/org/apache/commons/net/telnet/TelnetOption.java b/src/main/java/org/apache/commons/net/telnet/TelnetOption.java index 3ff1a128..7bfd6514 100644 --- a/src/main/java/org/apache/commons/net/telnet/TelnetOption.java +++ b/src/main/java/org/apache/commons/net/telnet/TelnetOption.java @@ -21,12 +21,11 @@ package org.apache.commons.net.telnet; * The TelnetOption class cannot be instantiated and only serves as a storehouse for telnet option constants. * <p> * Details regarding Telnet option specification can be found in RFC 855. - * + * </p> * * @see org.apache.commons.net.telnet.Telnet * @see org.apache.commons.net.telnet.TelnetClient */ - public class TelnetOption { /** The maximum value an option code can have. This value is 255. */ public static final int MAX_OPTION_VALUE = 255; diff --git a/src/main/java/org/apache/commons/net/telnet/TelnetOutputStream.java b/src/main/java/org/apache/commons/net/telnet/TelnetOutputStream.java index 3680c5e3..12389d7c 100644 --- a/src/main/java/org/apache/commons/net/telnet/TelnetOutputStream.java +++ b/src/main/java/org/apache/commons/net/telnet/TelnetOutputStream.java @@ -24,12 +24,12 @@ import java.io.OutputStream; * Wraps an output stream. * <p> * In binary mode, the only conversion is to double IAC. + * </p> * <p> * In ASCII mode, if convertCRtoCRLF is true (currently always true), any CR is converted to CRLF. IACs are doubled. Also, a bare LF is converted to CRLF and a * bare CR is converted to CR\0 - * <p> + * </p> */ - final class TelnetOutputStream extends OutputStream { private final TelnetClient client; // TODO there does not appear to be any way to change this value - should it be a ctor parameter? @@ -54,7 +54,6 @@ final class TelnetOutputStream extends OutputStream { /** * Writes a byte array to the stream. - * <p> * * @param buffer The byte array to write. * @throws IOException If an error occurs while writing to the underlying stream. @@ -66,7 +65,6 @@ final class TelnetOutputStream extends OutputStream { /** * Writes a number of bytes from a byte array to the stream starting from a given offset. - * <p> * * @param buffer The byte array to write. * @param offset The offset into the array at which to start copying data. @@ -84,7 +82,6 @@ final class TelnetOutputStream extends OutputStream { /** * Writes a byte to the stream. - * <p> * * @param ch The byte to write. * @throws IOException If an error occurs while writing to the underlying stream. diff --git a/src/main/java/org/apache/commons/net/telnet/TerminalTypeOptionHandler.java b/src/main/java/org/apache/commons/net/telnet/TerminalTypeOptionHandler.java index d02daf86..fc7141a2 100644 --- a/src/main/java/org/apache/commons/net/telnet/TerminalTypeOptionHandler.java +++ b/src/main/java/org/apache/commons/net/telnet/TerminalTypeOptionHandler.java @@ -43,7 +43,6 @@ public class TerminalTypeOptionHandler extends TelnetOptionHandler { /** * Constructor for the TerminalTypeOptionHandler. Initial and accept behavior flags are set to false - * <p> * * @param termtype - terminal type that will be negotiated. */ @@ -55,7 +54,6 @@ public class TerminalTypeOptionHandler extends TelnetOptionHandler { /** * Constructor for the TerminalTypeOptionHandler. Allows defining desired initial setting for local/remote activation of this option and behavior in case a * local/remote activation request for this option is received. - * <p> * * @param termtype - terminal type that will be negotiated. * @param initlocal - if set to true, a {@code WILL} is sent upon connection. @@ -71,11 +69,9 @@ public class TerminalTypeOptionHandler extends TelnetOptionHandler { /** * Implements the abstract method of TelnetOptionHandler. - * <p> * * @param suboptionData - the sequence received, without IAC SB & IAC SE * @param suboptionLength - the length of data in suboption_data - * <p> * @return terminal type information */ @Override diff --git a/src/main/java/org/apache/commons/net/telnet/WindowSizeOptionHandler.java b/src/main/java/org/apache/commons/net/telnet/WindowSizeOptionHandler.java index f5474613..3cae81a1 100644 --- a/src/main/java/org/apache/commons/net/telnet/WindowSizeOptionHandler.java +++ b/src/main/java/org/apache/commons/net/telnet/WindowSizeOptionHandler.java @@ -40,7 +40,6 @@ public class WindowSizeOptionHandler extends TelnetOptionHandler { /** * Constructor for the WindowSizeOptionHandler. Initial and accept behavior flags are set to false - * <p> * * @param nWidth - Window width. * @param nHeight - Window Height @@ -74,7 +73,6 @@ public class WindowSizeOptionHandler extends TelnetOptionHandler { /** * Implements the abstract method of TelnetOptionHandler. This will send the client Height and Width to the server. - * <p> * * @return array to send to remote system */
