From b0513fff8ad54d99ae843c41e66b9d9fe939b562 Mon Sep 17 00:00:00 2001 From: jrandom Date: Thu, 25 Nov 2004 21:49:29 +0000 Subject: [PATCH] javadoc --- .../streaming/ConnectionDataReceiver.java | 33 ++++++++++++++++++- .../client/streaming/ConnectionHandler.java | 8 +++++ .../client/streaming/ConnectionManager.java | 6 ++++ .../i2p/client/streaming/MessageHandler.java | 2 ++ .../client/streaming/MessageOutputStream.java | 14 +++++++- .../net/i2p/client/streaming/PacketQueue.java | 4 +++ 6 files changed, 65 insertions(+), 2 deletions(-) diff --git a/apps/streaming/java/src/net/i2p/client/streaming/ConnectionDataReceiver.java b/apps/streaming/java/src/net/i2p/client/streaming/ConnectionDataReceiver.java index 9219e5f57..ba48fde77 100644 --- a/apps/streaming/java/src/net/i2p/client/streaming/ConnectionDataReceiver.java +++ b/apps/streaming/java/src/net/i2p/client/streaming/ConnectionDataReceiver.java @@ -6,6 +6,11 @@ import net.i2p.I2PAppContext; import net.i2p.util.Log; /** + * Receive data from the MessageOutputStream, build a packet, + * and send it through a connection. The write calls on this + * do NOT block, but they also do not necessary imply immediate + * delivery, or even the generation of a new packet. This class + * is the only one that builds useful outbound Packet objects. * */ class ConnectionDataReceiver implements MessageOutputStream.DataReceiver { @@ -21,6 +26,17 @@ class ConnectionDataReceiver implements MessageOutputStream.DataReceiver { _dummyStatus = new DummyStatus(); } + /** + * Send some data through the connection, or if there is no new data, this + * may generate a packet with a plain ACK/NACK or CLOSE, or nothing whatsoever + * if there's nothing new to send. + * + * @param buf data to be sent - may be null + * @param off offset into the buffer to start writing from + * @param size how many bytes of the buffer to write (may be 0) + * @return an object to allow optional blocking for data acceptance or + * delivery. + */ public MessageOutputStream.WriteStatus writeData(byte[] buf, int off, int size) { boolean doSend = true; if ( (size <= 0) && (_connection.getLastSendId() >= 0) ) { @@ -54,12 +70,25 @@ class ConnectionDataReceiver implements MessageOutputStream.DataReceiver { } + /** + * Send some data through the connection, attaching any appropriate flags + * onto the packet. + * + * @param buf data to be sent - may be null + * @param off offset into the buffer to start writing from + * @param size how many bytes of the buffer to write (may be 0) + * @return the packet sent + */ public PacketLocal send(byte buf[], int off, int size) { return send(buf, off, size, false); } /** + * @param buf data to be sent - may be null + * @param off offset into the buffer to start writing from + * @param size how many bytes of the buffer to write (may be 0) * @param forceIncrement even if the buffer is empty, increment the packetId * so we get an ACK back + * @return the packet sent */ public PacketLocal send(byte buf[], int off, int size, boolean forceIncrement) { PacketLocal packet = buildPacket(buf, off, size, forceIncrement); @@ -123,7 +152,9 @@ class ConnectionDataReceiver implements MessageOutputStream.DataReceiver { return packet; } - + /** + * Used if no new packet was sent. + */ private static final class DummyStatus implements MessageOutputStream.WriteStatus { public final void waitForAccept(int maxWaitMs) { return; } public final void waitForCompletion(int maxWaitMs) { return; } diff --git a/apps/streaming/java/src/net/i2p/client/streaming/ConnectionHandler.java b/apps/streaming/java/src/net/i2p/client/streaming/ConnectionHandler.java index 543406b7f..d09667773 100644 --- a/apps/streaming/java/src/net/i2p/client/streaming/ConnectionHandler.java +++ b/apps/streaming/java/src/net/i2p/client/streaming/ConnectionHandler.java @@ -50,6 +50,14 @@ class ConnectionHandler { } } + /** + * Receive an incoming connection (built from a received SYN) + * + * @param timeoutMs max amount of time to wait for a connection (if less + * than 1ms, wait indefinitely) + * @return connection received, or null if there was a timeout or the + * handler was shut down + */ public Connection accept(long timeoutMs) { if (_log.shouldLog(Log.DEBUG)) _log.debug("Accept("+ timeoutMs+") called"); diff --git a/apps/streaming/java/src/net/i2p/client/streaming/ConnectionManager.java b/apps/streaming/java/src/net/i2p/client/streaming/ConnectionManager.java index 0ef882f1b..d33fd7fe5 100644 --- a/apps/streaming/java/src/net/i2p/client/streaming/ConnectionManager.java +++ b/apps/streaming/java/src/net/i2p/client/streaming/ConnectionManager.java @@ -91,6 +91,7 @@ public class ConnectionManager { public void setAllowIncomingConnections(boolean allow) { _connectionHandler.setActive(allow); } + /** should we acceot connections, or just reject everyone? */ public boolean getAllowIncomingConnections() { return _connectionHandler.getActive(); } @@ -262,6 +263,10 @@ public class ConnectionManager { } } + /** + * Drop the (already closed) connection on the floor. + * + */ public void removeConnection(Connection con) { boolean removed = false; synchronized (_connectionLock) { @@ -287,6 +292,7 @@ public class ConnectionManager { } } + /** return a set of Connection objects */ public Set listConnections() { synchronized (_connectionLock) { return new HashSet(_connectionByInboundId.values()); diff --git a/apps/streaming/java/src/net/i2p/client/streaming/MessageHandler.java b/apps/streaming/java/src/net/i2p/client/streaming/MessageHandler.java index 0da98791f..6c33ddd97 100644 --- a/apps/streaming/java/src/net/i2p/client/streaming/MessageHandler.java +++ b/apps/streaming/java/src/net/i2p/client/streaming/MessageHandler.java @@ -7,6 +7,8 @@ import net.i2p.client.I2PSessionException; import net.i2p.util.Log; /** + * Receive raw information from the I2PSession and turn it into + * Packets, if we can. * */ public class MessageHandler implements I2PSessionListener { diff --git a/apps/streaming/java/src/net/i2p/client/streaming/MessageOutputStream.java b/apps/streaming/java/src/net/i2p/client/streaming/MessageOutputStream.java index dac624168..b1a9ab113 100644 --- a/apps/streaming/java/src/net/i2p/client/streaming/MessageOutputStream.java +++ b/apps/streaming/java/src/net/i2p/client/streaming/MessageOutputStream.java @@ -10,7 +10,9 @@ import net.i2p.util.ByteCache; import net.i2p.util.Log; /** - * + * A stream that we can shove data into that fires off those bytes + * on flush or when the buffer is full. It also blocks according + * to the data receiver's needs. */ public class MessageOutputStream extends OutputStream { private I2PAppContext _context; @@ -104,6 +106,13 @@ public class MessageOutputStream extends OutputStream { throwAnyError(); } + /** + * Flush the data already queued up, blocking until it has been + * delivered. + * + * @throws IOException if the write fails + * @throws InterruptedIOException if the write times out + */ public void flush() throws IOException { WriteStatus ws = null; synchronized (_dataLock) { @@ -148,6 +157,7 @@ public class MessageOutputStream extends OutputStream { _dataCache.release(ba); } } + /** nonblocking close */ public void closeInternal() { _closed = true; _streamError = new IOException("Closed internally"); @@ -217,6 +227,7 @@ public class MessageOutputStream extends OutputStream { _dataReceiver = null; } + /** Define a component to receive data flushed from this stream */ public interface DataReceiver { /** * Nonblocking write @@ -224,6 +235,7 @@ public class MessageOutputStream extends OutputStream { public WriteStatus writeData(byte buf[], int off, int size); } + /** Define a way to detect the status of a write */ public interface WriteStatus { /** wait until the data written either fails or succeeds */ public void waitForCompletion(int maxWaitMs); diff --git a/apps/streaming/java/src/net/i2p/client/streaming/PacketQueue.java b/apps/streaming/java/src/net/i2p/client/streaming/PacketQueue.java index f3d835919..fceb25e42 100644 --- a/apps/streaming/java/src/net/i2p/client/streaming/PacketQueue.java +++ b/apps/streaming/java/src/net/i2p/client/streaming/PacketQueue.java @@ -13,6 +13,10 @@ import net.i2p.util.ByteCache; import net.i2p.util.Log; /** + * Queue out packets to be sent through the session. + * Well, thats the theory at least... in practice we just + * send them immediately with no blocking, since the + * mode=bestEffort doesnt block in the SDK. * */ class PacketQueue {