From ca5c15d4def12f74c941558118e6a5db4ae0bc9b Mon Sep 17 00:00:00 2001 From: sponge Date: Sat, 11 Oct 2008 10:28:31 +0000 Subject: [PATCH] Added more complete javadocs to ministreaming and cleaned up overrides so the code is JDK5 compliant. There remains some unchecked warnings, but these aren't important at this juncture. --- .../net/i2p/client/streaming/ByteCollector.java | 3 +++ .../net/i2p/client/streaming/I2PServerSocket.java | 6 ++++-- .../i2p/client/streaming/I2PServerSocketImpl.java | 4 ++-- .../src/net/i2p/client/streaming/I2PSocket.java | 15 ++++++++++----- .../net/i2p/client/streaming/I2PSocketImpl.java | 15 +++++++++++++++ .../i2p/client/streaming/I2PSocketManager.java | 6 ++++++ .../client/streaming/I2PSocketManagerFactory.java | 13 +++++++++++++ .../client/streaming/I2PSocketManagerImpl.java | 3 ++- .../i2p/client/streaming/I2PSocketOptions.java | 10 ++++++++++ .../i2p/client/streaming/StreamSinkClient.java | 5 +++-- .../net/i2p/client/streaming/StreamSinkSend.java | 1 + .../i2p/client/streaming/StreamSinkServer.java | 1 + .../src/net/i2p/client/streaming/TestSwarm.java | 4 ++-- 13 files changed, 72 insertions(+), 14 deletions(-) diff --git a/apps/ministreaming/java/src/net/i2p/client/streaming/ByteCollector.java b/apps/ministreaming/java/src/net/i2p/client/streaming/ByteCollector.java index 629684eb0..39249b449 100644 --- a/apps/ministreaming/java/src/net/i2p/client/streaming/ByteCollector.java +++ b/apps/ministreaming/java/src/net/i2p/client/streaming/ByteCollector.java @@ -245,10 +245,12 @@ class ByteCollector { * * @return the, uh, string */ + @Override public String toString() { return new String(toByteArray()); } + @Override public int hashCode() { int h = 0; for (int i = 0; i < size; i++) { @@ -263,6 +265,7 @@ class ByteCollector { * @return true if and only if both are the same size and the * byte arrays they contain are equal. */ + @Override public boolean equals(Object o) { if (o instanceof ByteCollector) { ByteCollector by = (ByteCollector) o; diff --git a/apps/ministreaming/java/src/net/i2p/client/streaming/I2PServerSocket.java b/apps/ministreaming/java/src/net/i2p/client/streaming/I2PServerSocket.java index ffb125209..d0028fdb8 100644 --- a/apps/ministreaming/java/src/net/i2p/client/streaming/I2PServerSocket.java +++ b/apps/ministreaming/java/src/net/i2p/client/streaming/I2PServerSocket.java @@ -12,6 +12,7 @@ import net.i2p.I2PException; public interface I2PServerSocket { /** * Closes the socket. + * @throws I2PException */ public void close() throws I2PException; @@ -31,18 +32,19 @@ public interface I2PServerSocket { /** * Set Sock Option accept timeout - * @param x + * @param x timeout in ms */ public void setSoTimeout(long x); /** * Get Sock Option accept timeout - * @return timeout + * @return timeout in ms */ public long getSoTimeout(); /** * Access the manager which is coordinating the server socket + * @return I2PSocketManager */ public I2PSocketManager getManager(); } diff --git a/apps/ministreaming/java/src/net/i2p/client/streaming/I2PServerSocketImpl.java b/apps/ministreaming/java/src/net/i2p/client/streaming/I2PServerSocketImpl.java index d4734b022..93db8595b 100644 --- a/apps/ministreaming/java/src/net/i2p/client/streaming/I2PServerSocketImpl.java +++ b/apps/ministreaming/java/src/net/i2p/client/streaming/I2PServerSocketImpl.java @@ -31,14 +31,14 @@ class I2PServerSocketImpl implements I2PServerSocket { private Object socketAddedLock = new Object(); /** - * Set Sock Option accept timeout stub, does nothing + * Set Sock Option accept timeout stub, does nothing in ministreaming * @param x */ public void setSoTimeout(long x) { } /** - * Get Sock Option accept timeout stub, does nothing + * Get Sock Option accept timeout stub, does nothing in ministreaming * @return timeout */ public long getSoTimeout() { diff --git a/apps/ministreaming/java/src/net/i2p/client/streaming/I2PSocket.java b/apps/ministreaming/java/src/net/i2p/client/streaming/I2PSocket.java index a7cc07e9d..fee9fe667 100644 --- a/apps/ministreaming/java/src/net/i2p/client/streaming/I2PSocket.java +++ b/apps/ministreaming/java/src/net/i2p/client/streaming/I2PSocket.java @@ -13,31 +13,34 @@ import net.i2p.data.Destination; */ public interface I2PSocket { /** - * Return the Destination of this side of the socket. + * @return the Destination of this side of the socket. */ public Destination getThisDestination(); /** - * Return the destination of the peer. + * @return the destination of the peer. */ public Destination getPeerDestination(); /** - * Return an InputStream to read from the socket. + * @return an InputStream to read from the socket. + * @throws IOException on failure */ public InputStream getInputStream() throws IOException; /** - * Return an OutputStream to write into the socket. + * @return an OutputStream to write into the socket. + * @throws IOException on failure */ public OutputStream getOutputStream() throws IOException; /** - * Retrieve this socket's configuration + * @return socket's configuration */ public I2PSocketOptions getOptions(); /** * Configure the socket + * @param options I2PSocketOptions to set */ public void setOptions(I2PSocketOptions options); @@ -54,11 +57,13 @@ public interface I2PSocket { * the socket wait forever). This is simply a helper to adjust the * I2PSocketOptions * + * @param ms timeout in ms */ public void setReadTimeout(long ms); /** * Closes the socket if not closed yet + * @throws IOException on failure */ public void close() throws IOException; diff --git a/apps/ministreaming/java/src/net/i2p/client/streaming/I2PSocketImpl.java b/apps/ministreaming/java/src/net/i2p/client/streaming/I2PSocketImpl.java index 5662f4ce8..58349217b 100644 --- a/apps/ministreaming/java/src/net/i2p/client/streaming/I2PSocketImpl.java +++ b/apps/ministreaming/java/src/net/i2p/client/streaming/I2PSocketImpl.java @@ -335,6 +335,10 @@ class I2PSocketImpl implements I2PSocket { throw new RuntimeException("Incorrect read() result"); } + // I have to ask if this method is really needed, since the JDK has this already, + // including the timeouts. Perhaps the need is for debugging more than anything + // else? + @Override public int read(byte[] b, int off, int len) throws IOException { if (_log.shouldLog(Log.DEBUG)) _log.debug(getStreamPrefix() + "Read called for " + len + " bytes (avail=" @@ -397,6 +401,10 @@ class I2PSocketImpl implements I2PSocket { return read.length; } + /** + * @return 0 if empty, > 0 if there is data. + */ + @Override public int available() { synchronized (bc) { return bc.getCurrentSize(); @@ -471,6 +479,7 @@ class I2PSocketImpl implements I2PSocket { } } + @Override public void close() throws IOException { super.close(); notifyClosed(); @@ -496,11 +505,15 @@ class I2PSocketImpl implements I2PSocket { write(new byte[] { (byte) b}); } + // This override is faster than the built in JDK, + // but there are other variations not handled + @Override public void write(byte[] b, int off, int len) throws IOException { _bytesWritten += len; sendTo.queueData(b, off, len, true); } + @Override public void close() { sendTo.notifyClosed(); } @@ -580,6 +593,7 @@ class I2PSocketImpl implements I2PSocket { return true; } + @Override public void run() { byte[] buffer = new byte[MAX_PACKET_SIZE]; ByteCollector bc = new ByteCollector(); @@ -657,5 +671,6 @@ class I2PSocketImpl implements I2PSocket { } } + @Override public String toString() { return "" + hashCode(); } } diff --git a/apps/ministreaming/java/src/net/i2p/client/streaming/I2PSocketManager.java b/apps/ministreaming/java/src/net/i2p/client/streaming/I2PSocketManager.java index ba113ca62..02bef1a0a 100644 --- a/apps/ministreaming/java/src/net/i2p/client/streaming/I2PSocketManager.java +++ b/apps/ministreaming/java/src/net/i2p/client/streaming/I2PSocketManager.java @@ -48,6 +48,7 @@ public interface I2PSocketManager { * @param peer Destination to connect to * @param options I2P socket options to be used for connecting * + * @return new connected socket * @throws ConnectException if the peer refuses the connection * @throws NoRouteToHostException if the peer is not found or not reachable * @throws InterruptedIOException if the connection timeouts @@ -62,6 +63,7 @@ public interface I2PSocketManager { * * @param peer Destination to connect to * + * @return new connected socket * @throws ConnectException if the peer refuses the connection * @throws NoRouteToHostException if the peer is not found or not reachable * @throws InterruptedIOException if the connection timeouts @@ -80,6 +82,7 @@ public interface I2PSocketManager { /** * Retrieve a set of currently connected I2PSockets, either initiated locally or remotely. * + * @return a set of currently connected I2PSockets */ public Set listSockets(); @@ -87,6 +90,9 @@ public interface I2PSocketManager { * Ping the specified peer, returning true if they replied to the ping within * the timeout specified, false otherwise. This call blocks. * + * @param peer Destination to ping + * @param timeoutMs timeout in ms + * @return success or failure */ public boolean ping(Destination peer, long timeoutMs); diff --git a/apps/ministreaming/java/src/net/i2p/client/streaming/I2PSocketManagerFactory.java b/apps/ministreaming/java/src/net/i2p/client/streaming/I2PSocketManagerFactory.java index 0ee5b692b..ce18d68df 100644 --- a/apps/ministreaming/java/src/net/i2p/client/streaming/I2PSocketManagerFactory.java +++ b/apps/ministreaming/java/src/net/i2p/client/streaming/I2PSocketManagerFactory.java @@ -43,6 +43,7 @@ public class I2PSocketManagerFactory { * Create a socket manager using a brand new destination connected to the * I2CP router on the local machine on the default port (7654). * + * @param opts I2CP options * @return the newly created socket manager, or null if there were errors */ public static I2PSocketManager createManager(Properties opts) { @@ -53,6 +54,8 @@ public class I2PSocketManagerFactory { * Create a socket manager using a brand new destination connected to the * I2CP router on the specified host and port * + * @param host I2CP host + * @param port I2CP port * @return the newly created socket manager, or null if there were errors */ public static I2PSocketManager createManager(String host, int port) { @@ -63,6 +66,9 @@ public class I2PSocketManagerFactory { * Create a socket manager using a brand new destination connected to the * I2CP router on the given machine reachable through the given port. * + * @param i2cpHost I2CP host + * @param i2cpPort I2CP port + * @param opts I2CP options * @return the newly created socket manager, or null if there were errors */ public static I2PSocketManager createManager(String i2cpHost, int i2cpPort, Properties opts) { @@ -85,6 +91,7 @@ public class I2PSocketManagerFactory { * Create a socket manager using the destination loaded from the given private key * stream and connected to the default I2CP host and port. * + * @param myPrivateKeyStream private key stream * @return the newly created socket manager, or null if there were errors */ public static I2PSocketManager createManager(InputStream myPrivateKeyStream) { @@ -95,6 +102,8 @@ public class I2PSocketManagerFactory { * Create a socket manager using the destination loaded from the given private key * stream and connected to the default I2CP host and port. * + * @param myPrivateKeyStream private key stream + * @param opts I2CP options * @return the newly created socket manager, or null if there were errors */ public static I2PSocketManager createManager(InputStream myPrivateKeyStream, Properties opts) { @@ -106,6 +115,10 @@ public class I2PSocketManagerFactory { * stream and connected to the I2CP router on the specified machine on the given * port * + * @param myPrivateKeyStream private key stream + * @param i2cpHost I2CP host + * @param i2cpPort I2CP port + * @param opts I2CP options * @return the newly created socket manager, or null if there were errors */ public static I2PSocketManager createManager(InputStream myPrivateKeyStream, String i2cpHost, int i2cpPort, diff --git a/apps/ministreaming/java/src/net/i2p/client/streaming/I2PSocketManagerImpl.java b/apps/ministreaming/java/src/net/i2p/client/streaming/I2PSocketManagerImpl.java index 4a95475e5..406f71847 100644 --- a/apps/ministreaming/java/src/net/i2p/client/streaming/I2PSocketManagerImpl.java +++ b/apps/ministreaming/java/src/net/i2p/client/streaming/I2PSocketManagerImpl.java @@ -166,6 +166,7 @@ class I2PSocketManagerImpl implements I2PSocketManager, I2PSessionListener { return; case DATA_IN: sendIncoming(id, payload); + return; case CHAFF: // ignore return; @@ -423,7 +424,7 @@ class I2PSocketManagerImpl implements I2PSocketManager, I2PSessionListener { */ private void handleUnknown(int type, String id, byte payload[]) { _log.error(getName() + ": \n\n=============== Unknown packet! " + "============" - + "\nType: " + (int) type + + "\nType: " + type + "\nID: " + getReadableForm(id) + "\nBase64'ed Data: " + Base64.encode(payload) + "\n\n\n"); diff --git a/apps/ministreaming/java/src/net/i2p/client/streaming/I2PSocketOptions.java b/apps/ministreaming/java/src/net/i2p/client/streaming/I2PSocketOptions.java index fe191803e..94532e51b 100644 --- a/apps/ministreaming/java/src/net/i2p/client/streaming/I2PSocketOptions.java +++ b/apps/ministreaming/java/src/net/i2p/client/streaming/I2PSocketOptions.java @@ -5,9 +5,13 @@ package net.i2p.client.streaming; * */ public interface I2PSocketOptions { + /** How much data will we accept that hasn't been written out yet. */ public static final String PROP_BUFFER_SIZE = "i2p.streaming.bufferSize"; + /** How long wait for the ACK from a SYN, in milliseconds. */ public static final String PROP_CONNECT_TIMEOUT = "i2p.streaming.connectTimeout"; + /** How long to block on read. */ public static final String PROP_READ_TIMEOUT = "i2p.streaming.readTimeout"; + /** How long to block on write/flush */ public static final String PROP_WRITE_TIMEOUT = "i2p.streaming.writeTimeout"; /** @@ -20,6 +24,7 @@ public interface I2PSocketOptions { /** * Define how long we will wait for the ACK from a SYN, in milliseconds. * + * @param ms timeout in ms */ public void setConnectTimeout(long ms); @@ -27,6 +32,7 @@ public interface I2PSocketOptions { * What is the longest we'll block on the input stream while waiting * for more data. If this value is exceeded, the read() throws * InterruptedIOException + * @return timeout in ms */ public long getReadTimeout(); @@ -34,6 +40,7 @@ public interface I2PSocketOptions { * What is the longest we'll block on the input stream while waiting * for more data. If this value is exceeded, the read() throws * InterruptedIOException + * @param ms timeout in ms */ public void setReadTimeout(long ms); @@ -53,6 +60,7 @@ public interface I2PSocketOptions { * either some data is removed or the connection is closed. If this is * less than or equal to zero, there is no limit (warning: can eat ram) * + * @param numBytes How much data will we accept that hasn't been written out yet. */ public void setMaxBufferSize(int numBytes); @@ -61,6 +69,7 @@ public interface I2PSocketOptions { * for the data to flush. If this value is exceeded, the write() throws * InterruptedIOException. If this is less than or equal to zero, there * is no timeout. + * @return wait time to block on the output stream while waiting for the data to flush. */ public long getWriteTimeout(); @@ -69,6 +78,7 @@ public interface I2PSocketOptions { * for the data to flush. If this value is exceeded, the write() throws * InterruptedIOException. If this is less than or equal to zero, there * is no timeout. + * @param ms wait time to block on the output stream while waiting for the data to flush. */ public void setWriteTimeout(long ms); } diff --git a/apps/ministreaming/java/src/net/i2p/client/streaming/StreamSinkClient.java b/apps/ministreaming/java/src/net/i2p/client/streaming/StreamSinkClient.java index fb0e006fa..a5a6d4b63 100644 --- a/apps/ministreaming/java/src/net/i2p/client/streaming/StreamSinkClient.java +++ b/apps/ministreaming/java/src/net/i2p/client/streaming/StreamSinkClient.java @@ -18,8 +18,8 @@ import net.i2p.util.Log; /** * Simple streaming lib test app that connects to a given destination and sends - * it a particular amount of random data, then disconnects. See the {@link #main} - * + * it a particular amount of random data, then disconnects. + * @see #main(java.lang.String[]) */ public class StreamSinkClient { private Log _log; @@ -124,6 +124,7 @@ public class StreamSinkClient { *
  • serverDestFile: file containing the StreamSinkServer's binary Destination
    • *
  • concurrentSends: how many concurrent threads should send to the server at once
    • * + * @param args [i2cpHost i2cpPort] sendSizeKB writeDelayMs serverDestFile [concurrentSends] */ public static void main(String args[]) { StreamSinkClient client = null; diff --git a/apps/ministreaming/java/src/net/i2p/client/streaming/StreamSinkSend.java b/apps/ministreaming/java/src/net/i2p/client/streaming/StreamSinkSend.java index 1470e76e0..44bcb1b47 100644 --- a/apps/ministreaming/java/src/net/i2p/client/streaming/StreamSinkSend.java +++ b/apps/ministreaming/java/src/net/i2p/client/streaming/StreamSinkSend.java @@ -110,6 +110,7 @@ public class StreamSinkSend { *
  • writeDelayMs: how long to wait between each .write (0 for no delay)
    • *
  • serverDestFile: file containing the StreamSinkServer's binary Destination
    • * + * @param args sendFile writeDelayMs serverDestFile */ public static void main(String args[]) { if (args.length != 3) { diff --git a/apps/ministreaming/java/src/net/i2p/client/streaming/StreamSinkServer.java b/apps/ministreaming/java/src/net/i2p/client/streaming/StreamSinkServer.java index 7a5c28f1c..4266fd911 100644 --- a/apps/ministreaming/java/src/net/i2p/client/streaming/StreamSinkServer.java +++ b/apps/ministreaming/java/src/net/i2p/client/streaming/StreamSinkServer.java @@ -161,6 +161,7 @@ public class StreamSinkServer { *
  • ourDestFile: filename to write our binary destination to
    • *
  • numHandlers: how many concurrent connections to handle
    • * + * @param args [i2cpHost i2cpPort] sinkDir ourDestFile [numHandlers] */ public static void main(String args[]) { StreamSinkServer server = null; diff --git a/apps/ministreaming/java/src/net/i2p/client/streaming/TestSwarm.java b/apps/ministreaming/java/src/net/i2p/client/streaming/TestSwarm.java index f9ccadf83..1c3ef54e9 100644 --- a/apps/ministreaming/java/src/net/i2p/client/streaming/TestSwarm.java +++ b/apps/ministreaming/java/src/net/i2p/client/streaming/TestSwarm.java @@ -24,9 +24,9 @@ public class TestSwarm { private Log _log; private String _destFile; private String _peerDestFiles[]; - private String _conOptions; private I2PSocketManager _manager; - private boolean _dead; + private String _conOptions; // unused? used elsewhere? + private boolean _dead; // unused? used elsewhere? public static void main(String args[]) { if (args.length < 1) {