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
The following commit(s) were added to refs/heads/master by this push:
new e22db207 Javadoc
e22db207 is described below
commit e22db20777ce369e0fbf528131a871f768dac4dc
Author: Gary D. Gregory <garydgreg...@gmail.com>
AuthorDate: Wed Feb 12 10:35:35 2025 -0500
Javadoc
---
.../apache/commons/net/ProtocolCommandEvent.java | 29 +++++++++++++++----
.../apache/commons/net/ProtocolCommandSupport.java | 12 ++++++++
.../net/examples/PrintCommandListeners.java | 6 +++-
.../java/org/apache/commons/net/ftp/FTPFile.java | 20 +++++++++++--
.../commons/net/ftp/parser/VMSFTPEntryParser.java | 7 ++++-
.../org/apache/commons/net/io/CopyStreamEvent.java | 19 ++++++++++---
.../apache/commons/net/io/CopyStreamException.java | 3 ++
.../org/apache/commons/net/nntp/NNTPClient.java | 8 +++++-
.../org/apache/commons/net/nntp/NewsgroupInfo.java | 15 ++++++++++
.../java/org/apache/commons/net/ntp/TimeStamp.java | 11 ++++++++
.../apache/commons/net/pop3/POP3MessageInfo.java | 23 ++++++++++++---
.../apache/commons/net/telnet/TelnetClient.java | 33 ++++++++++++++++------
.../apache/commons/net/tftp/TFTPDataPacket.java | 10 +++++++
.../org/apache/commons/net/util/ListenerList.java | 8 ++++++
14 files changed, 176 insertions(+), 28 deletions(-)
diff --git a/src/main/java/org/apache/commons/net/ProtocolCommandEvent.java
b/src/main/java/org/apache/commons/net/ProtocolCommandEvent.java
index 6dd2a196..8945c6f2 100644
--- a/src/main/java/org/apache/commons/net/ProtocolCommandEvent.java
+++ b/src/main/java/org/apache/commons/net/ProtocolCommandEvent.java
@@ -32,9 +32,26 @@ import java.util.EventObject;
public class ProtocolCommandEvent extends EventObject {
private static final long serialVersionUID = 403743538418947240L;
+ /**
+ * The integer code indicating the natureof the reply. This will be the
protocol integer value for protocols that use integer reply codes, or the reply
+ * class constant corresponding to the reply for protocols like POP3 that
use strings like OK rather than integer codes (i.e., POP3Repy.OK).
+ */
private final int replyCode;
+
+ /**
+ * Whether the ProtocolCommandEvent was generated as a result of sending a
command.
+ */
private final boolean isCommand;
- private final String message, command;
+
+ /**
+ * The entire reply as received from the server.
+ */
+ private final String message;
+
+ /**
+ * The string representation of the command type sent, not including the
arguments (e.g., "STAT" or "GET").
+ */
+ private final String command;
/**
* Creates a ProtocolCommandEvent signalling a reply to a command was
received. ProtocolCommandEvents created with this constructor should only be
sent
@@ -71,7 +88,7 @@ public class ProtocolCommandEvent extends EventObject {
}
/**
- * Returns the string representation of the command type sent (e.g.,
"STAT" or "GET"). If the ProtocolCommandEvent is a reply event, then null is
returned.
+ * Gets the string representation of the command type sent (e.g., "STAT"
or "GET"). If the ProtocolCommandEvent is a reply event, then null is returned.
*
* @return The string representation of the command type sent, or null if
this is a reply event.
*/
@@ -80,7 +97,7 @@ public class ProtocolCommandEvent extends EventObject {
}
/**
- * Returns the entire message sent to or received from the server.
Includes the line terminator.
+ * Gets the entire message sent to or received from the server. Includes
the line terminator.
*
* @return The entire message sent to or received from the server.
*/
@@ -89,7 +106,7 @@ public class ProtocolCommandEvent extends EventObject {
}
/**
- * Returns the reply code of the received server reply. Undefined if this
is not a reply event.
+ * Gets the reply code of the received server reply. Undefined if this is
not a reply event.
*
* @return The reply code of the received server reply. Undefined if not a
reply event.
*/
@@ -98,7 +115,7 @@ public class ProtocolCommandEvent extends EventObject {
}
/**
- * Returns true if the ProtocolCommandEvent was generated as a result of
sending a command.
+ * Tests whether the ProtocolCommandEvent was generated as a result of
sending a command.
*
* @return true If the ProtocolCommandEvent was generated as a result of
sending a command. False otherwise.
*/
@@ -107,7 +124,7 @@ public class ProtocolCommandEvent extends EventObject {
}
/**
- * Returns true if the ProtocolCommandEvent was generated as a result of
receiving a reply.
+ * Tests whether the ProtocolCommandEvent was generated as a result of
receiving a reply.
*
* @return true If the ProtocolCommandEvent was generated as a result of
receiving a reply. False otherwise.
*/
diff --git a/src/main/java/org/apache/commons/net/ProtocolCommandSupport.java
b/src/main/java/org/apache/commons/net/ProtocolCommandSupport.java
index 7340befc..b1926e86 100644
--- a/src/main/java/org/apache/commons/net/ProtocolCommandSupport.java
+++ b/src/main/java/org/apache/commons/net/ProtocolCommandSupport.java
@@ -36,7 +36,14 @@ import org.apache.commons.net.util.ListenerList;
public class ProtocolCommandSupport implements Serializable {
private static final long serialVersionUID = -8017692739988399978L;
+ /**
+ * The source to use for all generated ProtocolCommandEvents.
+ */
private final Object source;
+
+ /**
+ * The ProtocolCommandListener.
+ */
private final ListenerList listeners;
/**
@@ -102,6 +109,11 @@ public class ProtocolCommandSupport implements
Serializable {
return listeners.getListenerCount();
}
+ /**
+ * Throws UnsupportedOperationException.
+ *
+ * @param ignored Ignored.
+ */
private void readObject(final ObjectInputStream ignored) {
throw new UnsupportedOperationException("Serialization is not
supported");
}
diff --git
a/src/main/java/org/apache/commons/net/examples/PrintCommandListeners.java
b/src/main/java/org/apache/commons/net/examples/PrintCommandListeners.java
index 417a787d..ff9d6e58 100644
--- a/src/main/java/org/apache/commons/net/examples/PrintCommandListeners.java
+++ b/src/main/java/org/apache/commons/net/examples/PrintCommandListeners.java
@@ -25,7 +25,11 @@ import org.apache.commons.net.io.Util;
*/
public class PrintCommandListeners {
- @SuppressWarnings("resource") // No need to close writer on System.out.
+ /**
+ * Creates a new PrintCommandListener on system out.
+ *
+ * @return a new PrintCommandListener on system out.
+ */
public static PrintCommandListener sysOutPrintCommandListener() {
return new PrintCommandListener(Util.newPrintWriter(System.out), true);
}
diff --git a/src/main/java/org/apache/commons/net/ftp/FTPFile.java
b/src/main/java/org/apache/commons/net/ftp/FTPFile.java
index fe80bdb6..a8c31bcb 100644
--- a/src/main/java/org/apache/commons/net/ftp/FTPFile.java
+++ b/src/main/java/org/apache/commons/net/ftp/FTPFile.java
@@ -66,6 +66,7 @@ public class FTPFile implements Serializable {
/** A constant indicating file execute permission or directory listing
permission. */
public static final int EXECUTE_PERMISSION = 2;
+ /** Type. */
private int type = UNKNOWN_TYPE;
/** 0 is invalid as a link count. */
@@ -73,13 +74,23 @@ public class FTPFile implements Serializable {
/** 0 is valid, so use -1. */
private long size = -1;
+
+ /** Line that could not be parsed. */
private String rawListing;
+
+ /** User. */
private String user = "";
+
+ /** Group. */
private String group = "";
+
+ /** Name. */
private String name;
+
+ /** Link. */
private String link;
- // TODO Consider changing internal representation to java.time.
+ /** TODO Consider changing internal representation to java.time. */
private Calendar calendar;
/** If this is null, then list entry parsing failed. */
@@ -91,7 +102,7 @@ public class FTPFile implements Serializable {
}
/**
- * Constructor for use by {@link FTPListParseEngine} only. Used to create
FTPFile entries for failed parses
+ * Constructor for use by {@link FTPListParseEngine} only. Used to create
FTPFile entries for failed parses.
*
* @param rawListing line that could not be parsed.
* @since 3.4
@@ -291,6 +302,11 @@ public class FTPFile implements Serializable {
return sb.toString();
}
+ /**
+ * Throws UnsupportedOperationException.
+ *
+ * @param ignored Ignored.
+ */
private void readObject(final ObjectInputStream ignored) {
throw new UnsupportedOperationException("Serialization is not
supported");
}
diff --git
a/src/main/java/org/apache/commons/net/ftp/parser/VMSFTPEntryParser.java
b/src/main/java/org/apache/commons/net/ftp/parser/VMSFTPEntryParser.java
index 38e84f4f..0a82f198 100644
--- a/src/main/java/org/apache/commons/net/ftp/parser/VMSFTPEntryParser.java
+++ b/src/main/java/org/apache/commons/net/ftp/parser/VMSFTPEntryParser.java
@@ -87,12 +87,17 @@ public class VMSFTPEntryParser extends
ConfigurableFTPFileEntryParserImpl {
return new FTPClientConfig(FTPClientConfig.SYST_VMS,
DEFAULT_DATE_FORMAT, null);
}
+ /**
+ * Returns {@code false}.
+ *
+ * @return {@code false}.
+ */
protected boolean isVersioning() {
return false;
}
/**
- * DO NOT USE
+ * DO NOT USE.
*
* @param listStream the stream
* @return the array of files
diff --git a/src/main/java/org/apache/commons/net/io/CopyStreamEvent.java
b/src/main/java/org/apache/commons/net/io/CopyStreamEvent.java
index 64001ef4..afed011d 100644
--- a/src/main/java/org/apache/commons/net/io/CopyStreamEvent.java
+++ b/src/main/java/org/apache/commons/net/io/CopyStreamEvent.java
@@ -36,12 +36,23 @@ public class CopyStreamEvent extends EventObject {
*/
public static final long UNKNOWN_STREAM_SIZE = -1;
+ /**
+ * The number of bytes transferred during the write that triggered the
CopyStreamEvent.
+ */
private final int bytesTransferred;
+
+ /**
+ * The total number of bytes transferred so far during a copy operation.
+ */
private final long totalBytesTransferred;
+
+ /**
+ * The number of bytes in the stream being copied. This may be set to
{@code UNKNOWN_STREAM_SIZE} if the size is unknown.
+ */
private final long streamSize;
/**
- * Creates a new CopyStreamEvent instance.
+ * Constructs a new instance.
*
* @param source The source of the event.
* @param totalBytesTransferred The total number of bytes transferred so
far during a copy operation.
@@ -56,7 +67,7 @@ public class CopyStreamEvent extends EventObject {
}
/**
- * Returns the number of bytes transferred by the write that triggered the
event.
+ * Gets the number of bytes transferred by the write that triggered the
event.
*
* @return The number of bytes transferred by the write that triggered the
vent.
*/
@@ -65,7 +76,7 @@ public class CopyStreamEvent extends EventObject {
}
/**
- * Returns the size of the stream being copied. This may be set to {@code
UNKNOWN_STREAM_SIZE} if the size is unknown.
+ * Gets the size of the stream being copied. This may be set to {@code
UNKNOWN_STREAM_SIZE} if the size is unknown.
*
* @return The size of the stream being copied.
*/
@@ -74,7 +85,7 @@ public class CopyStreamEvent extends EventObject {
}
/**
- * Returns the total number of bytes transferred so far by the copy
operation.
+ * Gets the total number of bytes transferred so far by the copy operation.
*
* @return The total number of bytes transferred so far by the copy
operation.
*/
diff --git a/src/main/java/org/apache/commons/net/io/CopyStreamException.java
b/src/main/java/org/apache/commons/net/io/CopyStreamException.java
index 4ac84a3c..72fc7c9e 100644
--- a/src/main/java/org/apache/commons/net/io/CopyStreamException.java
+++ b/src/main/java/org/apache/commons/net/io/CopyStreamException.java
@@ -28,6 +28,9 @@ import java.io.IOException;
public class CopyStreamException extends IOException {
private static final long serialVersionUID = -2602899129433221532L;
+ /**
+ * The total number of bytes confirmed to have been transferred by a
failed copy operation.
+ */
private final long totalBytesTransferred;
/**
diff --git a/src/main/java/org/apache/commons/net/nntp/NNTPClient.java
b/src/main/java/org/apache/commons/net/nntp/NNTPClient.java
index 8b41ea80..7273f331 100644
--- a/src/main/java/org/apache/commons/net/nntp/NNTPClient.java
+++ b/src/main/java/org/apache/commons/net/nntp/NNTPClient.java
@@ -239,11 +239,17 @@ public class NNTPClient extends NNTP {
return NNTPReply.isPositiveCompletion(getReply());
}
+ /**
+ * Creates a new writer or returns null if we don't have a a positive
intermediate response.
+ *
+ * @param articleId Article ID.
+ * @return a new writer or null.
+ * @throws IOException If an I/O error occurs while either sending the
command or receiving the server reply.
+ */
public Writer forwardArticle(final String articleId) throws IOException {
if (!NNTPReply.isPositiveIntermediate(ihave(articleId))) {
return null;
}
-
return new DotTerminatedMessageWriter(_writer_);
}
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 f7cff290..2d6271c3 100644
--- a/src/main/java/org/apache/commons/net/nntp/NewsgroupInfo.java
+++ b/src/main/java/org/apache/commons/net/nntp/NewsgroupInfo.java
@@ -49,6 +49,11 @@ public final class NewsgroupInfo {
private long lastArticle;
private int postingPermission;
+ /**
+ * Gets the estimated number of articles in the newsgroup. The accuracy of
this value will depend on the server implementation.
+ *
+ * @return The estimated number of articles in the newsgroup.
+ */
@Deprecated
public int getArticleCount() {
return (int) estimatedArticleCount;
@@ -63,6 +68,11 @@ public final class NewsgroupInfo {
return estimatedArticleCount;
}
+ /**
+ * Gets the number of the first article in the newsgroup.
+ *
+ * @return The number of the first article in the newsgroup.
+ */
@Deprecated
public int getFirstArticle() {
return (int) firstArticle;
@@ -77,6 +87,11 @@ public final class NewsgroupInfo {
return firstArticle;
}
+ /**
+ * Gets the number of the last article in the newsgroup.
+ *
+ * @return The number of the last article in the newsgroup.
+ */
@Deprecated
public int getLastArticle() {
return (int) lastArticle;
diff --git a/src/main/java/org/apache/commons/net/ntp/TimeStamp.java
b/src/main/java/org/apache/commons/net/ntp/TimeStamp.java
index 1dc4a98c..78d70637 100644
--- a/src/main/java/org/apache/commons/net/ntp/TimeStamp.java
+++ b/src/main/java/org/apache/commons/net/ntp/TimeStamp.java
@@ -215,8 +215,14 @@ public class TimeStamp implements Serializable,
Comparable<TimeStamp> {
*/
private final long ntpTime;
+ /**
+ * Formats dates.
+ */
private DateFormat simpleFormatter;
+ /**
+ * Formats UTC strings.
+ */
private DateFormat utcFormatter;
/**
@@ -341,6 +347,11 @@ public class TimeStamp implements Serializable,
Comparable<TimeStamp> {
return ntpTime;
}
+ /**
+ * Throws UnsupportedOperationException.
+ *
+ * @param ignored Ignored.
+ */
private void readObject(final ObjectInputStream ignored) {
throw new UnsupportedOperationException("Serialization is not
supported");
}
diff --git a/src/main/java/org/apache/commons/net/pop3/POP3MessageInfo.java
b/src/main/java/org/apache/commons/net/pop3/POP3MessageInfo.java
index ca2f4ccb..93bf0cce 100644
--- a/src/main/java/org/apache/commons/net/pop3/POP3MessageInfo.java
+++ b/src/main/java/org/apache/commons/net/pop3/POP3MessageInfo.java
@@ -23,28 +23,36 @@ package org.apache.commons.net.pop3;
* <p>
* In response to a status command, {@code number} contains the number of
messages in the mailbox, {@code size} contains the size of the mailbox
* in bytes, and {@code identifier} is null.
+ * </p>
* <p>
* In response to a message listings, {@code number} contains the message
number, {@code size} contains the size of the message in bytes, and
* {@code identifier} is null.
+ * </p>
* <p>
* In response to unique identifier listings, {@code number} contains the
message number, {@code size} is undefined, and {@code identifier}
* contains the message's unique identifier.
+ * </p>
*/
-
public final class POP3MessageInfo {
+
+ /** Number. */
public int number;
+
+ /** Size. */
public int size;
+
+ /** Identifier. */
public String identifier;
/**
- * Creates a POP3MessageInfo instance with {@code number} and {@code size}
set to 0, and {@code identifier} set to null.
+ * Constructs a new instance with {@code number} and {@code size} set to
0, and {@code identifier} set to null.
*/
public POP3MessageInfo() {
this(0, null, 0);
}
/**
- * Creates a POP3MessageInfo instance with {@code number} set to {@code
num}, {@code size} set to {@code octets}, and
+ * Constructs a new instance with {@code number} set to {@code num},
{@code size} set to {@code octets}, and
* {@code identifier} set to null.
*
* @param num the number
@@ -55,7 +63,7 @@ public final class POP3MessageInfo {
}
/**
- * Creates a POP3MessageInfo instance with {@code number} set to {@code
num}, {@code size} undefined, and {@code identifier} set to
+ * Constructs a new instance with {@code number} set to {@code num},
{@code size} undefined, and {@code identifier} set to
* {@code uid}.
*
* @param num the number
@@ -65,6 +73,13 @@ public final class POP3MessageInfo {
this(num, uid, -1);
}
+ /**
+ * Constructs a new instance.
+ *
+ * @param num the number.
+ * @param uid the UID.
+ * @param octets the size.
+ */
private POP3MessageInfo(final int num, final String uid, final int size) {
this.number = num;
this.size = size;
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 f70a3648..b956235a 100644
--- a/src/main/java/org/apache/commons/net/telnet/TelnetClient.java
+++ b/src/main/java/org/apache/commons/net/telnet/TelnetClient.java
@@ -36,10 +36,25 @@ import java.time.Duration;
public class TelnetClient extends Telnet {
private static final int DEFAULT_MAX_SUBNEGOTIATION_LENGTH = 512;
+ /**
+ * the size of the subnegotiation buffer.
+ */
final int maxSubnegotiationLength;
+
+ /** Input stream. */
private InputStream input;
+
+ /** Output stream. */
private OutputStream output;
+
+ /**
+ * Whether to enable the reader thread.
+ */
protected boolean readerThread = true;
+
+ /**
+ * Telnet input listener.
+ */
private TelnetInputListener inputListener;
/**
@@ -50,9 +65,9 @@ public class TelnetClient extends Telnet {
}
/**
- * Constructs an instance with the specified max subnegotiation length and
the default terminal-type {@code VT100}
+ * Constructs an instance with the specified max subnegotiation length and
the default terminal-type {@code VT100}.
*
- * @param maxSubnegotiationLength the size of the subnegotiation buffer
+ * @param maxSubnegotiationLength the size of the subnegotiation buffer.
*/
public TelnetClient(final int maxSubnegotiationLength) {
this("VT100", maxSubnegotiationLength);
@@ -70,12 +85,12 @@ public class TelnetClient extends Telnet {
/**
* Constructs an instance with the specified terminal type and max
subnegotiation length
*
- * @param termtype the terminal type to use, e.g. {@code
VT100}
+ * @param termType the terminal type to use, e.g. {@code
VT100}
* @param maxSubnegotiationLength the size of the subnegotiation buffer
*/
- public TelnetClient(final String termtype, final int
maxSubnegotiationLength) {
+ public TelnetClient(final String termType, final int
maxSubnegotiationLength) {
/* TERMINAL-TYPE option (start) */
- super(termtype);
+ super(termType);
/* TERMINAL-TYPE option (end) */
this.input = null;
this.output = null;
@@ -250,7 +265,7 @@ public class TelnetClient extends Telnet {
* Notifications are only supported when a {@link #setReaderThread reader
thread} is enabled for the connection.
* </p>
*
- * @param listener listener to be registered; replaces any previous
+ * @param listener listener to be registered, replaces any previous
listener.
* @since 3.0
*/
public synchronized void registerInputListener(final TelnetInputListener
listener) {
@@ -352,11 +367,11 @@ public class TelnetClient extends Telnet {
* When this method is invoked, the reader thread status will apply to all
subsequent connections; the current connection (if any) is not affected.
* </p>
*
- * @param flag true to enable the reader thread, false to disable
+ * @param readerThread true to enable the reader thread, false to disable.
* @see #registerInputListener
*/
- public void setReaderThread(final boolean flag) {
- readerThread = flag;
+ public void setReaderThread(final boolean readerThread) {
+ this.readerThread = readerThread;
}
/**
diff --git a/src/main/java/org/apache/commons/net/tftp/TFTPDataPacket.java
b/src/main/java/org/apache/commons/net/tftp/TFTPDataPacket.java
index f34c6424..7a2725fa 100644
--- a/src/main/java/org/apache/commons/net/tftp/TFTPDataPacket.java
+++ b/src/main/java/org/apache/commons/net/tftp/TFTPDataPacket.java
@@ -78,6 +78,16 @@ public final class TFTPDataPacket extends TFTPPacket {
}
}
+ /**
+ * Creates a data packet to be sent to a host at a given port with a given
block number. The actual data to be sent is passed as an array, an offset, and a
+ * length. The offset is the offset into the byte array where the data
starts. The length is the length of the data. If the length is greater than
+ * MAX_DATA_LENGTH, it is truncated.
+ *
+ * @param destination The host to which the packet is going to be sent.
+ * @param port The port to which the packet is going to be sent.
+ * @param blockNumber The block number of the data.
+ * @param data The byte array containing the data.
+ */
public TFTPDataPacket(final InetAddress destination, final int port, final
int blockNumber, final byte[] data) {
this(destination, port, blockNumber, data, 0, data.length);
}
diff --git a/src/main/java/org/apache/commons/net/util/ListenerList.java
b/src/main/java/org/apache/commons/net/util/ListenerList.java
index 83a8162b..78c0727d 100644
--- a/src/main/java/org/apache/commons/net/util/ListenerList.java
+++ b/src/main/java/org/apache/commons/net/util/ListenerList.java
@@ -30,6 +30,9 @@ public class ListenerList implements Serializable,
Iterable<EventListener> {
private static final long serialVersionUID = -1934227607974228213L;
+ /**
+ * The thread-safe list of listeners.
+ */
private final CopyOnWriteArrayList<EventListener> listeners;
/**
@@ -68,6 +71,11 @@ public class ListenerList implements Serializable,
Iterable<EventListener> {
return listeners.iterator();
}
+ /**
+ * Throws UnsupportedOperationException.
+ *
+ * @param ignored Ignore.
+ */
private void readObject(final ObjectInputStream ignored) {
throw new UnsupportedOperationException("Serialization is not
supported");
}
