From 252f1047e56fc80df8325135aa6afe03a2a85803 Mon Sep 17 00:00:00 2001 From: zzz Date: Thu, 14 Jul 2011 18:53:58 +0000 Subject: [PATCH] javadocs and final --- core/java/src/net/i2p/client/I2PClient.java | 9 ++++-- .../src/net/i2p/client/I2PClientImpl.java | 13 +++++++++ core/java/src/net/i2p/client/I2PSession.java | 29 +++++++++++++++++-- .../i2p/client/I2PSessionDemultiplexer.java | 7 +++-- .../src/net/i2p/client/I2PSessionImpl.java | 2 ++ .../src/net/i2p/client/I2PSessionImpl2.java | 2 ++ .../net/i2p/client/I2PSessionMuxedImpl.java | 13 +++++---- 7 files changed, 62 insertions(+), 13 deletions(-) diff --git a/core/java/src/net/i2p/client/I2PClient.java b/core/java/src/net/i2p/client/I2PClient.java index adc03bb27..6521cf258 100644 --- a/core/java/src/net/i2p/client/I2PClient.java +++ b/core/java/src/net/i2p/client/I2PClient.java @@ -44,7 +44,9 @@ public interface I2PClient { * using the specified options to both connect to the router, to instruct * the router how to handle the new session, and to configure the end to end * encryption. - * @param destKeyStream location from which to read the Destination, PrivateKey, and SigningPrivateKey from + * + * @param destKeyStream location from which to read the Destination, PrivateKey, and SigningPrivateKey from, + * format is specified in {@link net.i2p.data.PrivateKeyFile PrivateKeyFile} * @param options set of options to configure the router with, if null will use System properties * @return new session allowing a Destination to recieve all of its messages and send messages to any other Destination. */ @@ -52,8 +54,10 @@ public interface I2PClient { /** Create a new destination with the default certificate creation properties and store * it, along with the private encryption and signing keys at the specified location + * * @param destKeyStream create a new destination and write out the object to the given stream, * formatted as Destination, PrivateKey, and SigningPrivateKey + * format is specified in {@link net.i2p.data.PrivateKeyFile PrivateKeyFile} * @return new destination */ public Destination createDestination(OutputStream destKeyStream) throws I2PException, IOException; @@ -61,7 +65,8 @@ public interface I2PClient { /** Create a new destination with the given certificate and store it, along with the private * encryption and signing keys at the specified location * - * @param destKeyStream location to write out the destination, PrivateKey, and SigningPrivateKey + * @param destKeyStream location to write out the destination, PrivateKey, and SigningPrivateKey, + * format is specified in {@link net.i2p.data.PrivateKeyFile PrivateKeyFile} * @param cert certificate to tie to the destination * @return newly created destination */ diff --git a/core/java/src/net/i2p/client/I2PClientImpl.java b/core/java/src/net/i2p/client/I2PClientImpl.java index d0147f0d7..23033dbf0 100644 --- a/core/java/src/net/i2p/client/I2PClientImpl.java +++ b/core/java/src/net/i2p/client/I2PClientImpl.java @@ -30,8 +30,12 @@ import net.i2p.data.SigningPublicKey; * @author jrandom */ class I2PClientImpl implements I2PClient { + /** * Create the destination with a null payload + * + * @param destKeyStream location to write out the destination, PrivateKey, and SigningPrivateKey, + * format is specified in {@link net.i2p.data.PrivateKeyFile PrivateKeyFile} */ public Destination createDestination(OutputStream destKeyStream) throws I2PException, IOException { Certificate cert = new Certificate(); @@ -44,6 +48,8 @@ class I2PClientImpl implements I2PClient { * Create the destination with the given payload and write it out along with * the PrivateKey and SigningPrivateKey to the destKeyStream * + * @param destKeyStream location to write out the destination, PrivateKey, and SigningPrivateKey, + * format is specified in {@link net.i2p.data.PrivateKeyFile PrivateKeyFile} */ public Destination createDestination(OutputStream destKeyStream, Certificate cert) throws I2PException, IOException { Destination d = new Destination(); @@ -67,13 +73,20 @@ class I2PClientImpl implements I2PClient { /** * Create a new session (though do not connect it yet) + * + * @param destKeyStream location from which to read the Destination, PrivateKey, and SigningPrivateKey from, + * format is specified in {@link net.i2p.data.PrivateKeyFile PrivateKeyFile} * @param options set of options to configure the router with, if null will use System properties */ public I2PSession createSession(InputStream destKeyStream, Properties options) throws I2PSessionException { return createSession(I2PAppContext.getGlobalContext(), destKeyStream, options); } + /** * Create a new session (though do not connect it yet) + * + * @param destKeyStream location from which to read the Destination, PrivateKey, and SigningPrivateKey from, + * format is specified in {@link net.i2p.data.PrivateKeyFile PrivateKeyFile} * @param options set of options to configure the router with, if null will use System properties */ public I2PSession createSession(I2PAppContext context, InputStream destKeyStream, Properties options) throws I2PSessionException { diff --git a/core/java/src/net/i2p/client/I2PSession.java b/core/java/src/net/i2p/client/I2PSession.java index d21c858d7..06b094488 100644 --- a/core/java/src/net/i2p/client/I2PSession.java +++ b/core/java/src/net/i2p/client/I2PSession.java @@ -217,11 +217,34 @@ public interface I2PSession { */ public int[] bandwidthLimits() throws I2PSessionException; - /** See I2PSessionMuxedImpl for details */ + /** + * Listen on specified protocol and port. + * + * An existing listener with the same proto and port is replaced. + * Only the listener with the best match is called back for each message. + * + * @param proto 1-254 or PROTO_ANY (0) for all; recommended: + * I2PSession.PROTO_STREAMING + * I2PSession.PROTO_DATAGRAM + * 255 disallowed + * @param port 1-65535 or PORT_ANY (0) for all + * @since 0.7.1 + */ public void addSessionListener(I2PSessionListener lsnr, int proto, int port); - /** See I2PSessionMuxedImpl for details */ + + /** + * Listen on specified protocol and port, and receive notification + * of proto, fromPort, and toPort for every message. + * @param proto 1-254 or PROTO_ANY (0) for all; 255 disallowed + * @param port 1-65535 or PORT_ANY (0) for all + * @since 0.7.1 + */ public void addMuxedSessionListener(I2PSessionMuxedListener l, int proto, int port); - /** See I2PSessionMuxedImpl for details */ + + /** + * removes the specified listener (only) + * @since 0.7.1 + */ public void removeListener(int proto, int port); public static final int PORT_ANY = 0; diff --git a/core/java/src/net/i2p/client/I2PSessionDemultiplexer.java b/core/java/src/net/i2p/client/I2PSessionDemultiplexer.java index 28d211fa5..5d28d1a21 100644 --- a/core/java/src/net/i2p/client/I2PSessionDemultiplexer.java +++ b/core/java/src/net/i2p/client/I2PSessionDemultiplexer.java @@ -16,13 +16,14 @@ import net.i2p.util.Log; * depending on whether they want to hear about the * protocol, from port, and to port for every received message. * - * This only calls one listener, not all that apply. + * messageAvailable() only calls one listener, not all that apply. + * The others call all listeners. * * @author zzz */ public class I2PSessionDemultiplexer implements I2PSessionMuxedListener { - private Log _log; - private Map _listeners; + private final Log _log; + private final Map _listeners; public I2PSessionDemultiplexer(I2PAppContext ctx) { _log = ctx.logManager().getLog(I2PSessionDemultiplexer.class); diff --git a/core/java/src/net/i2p/client/I2PSessionImpl.java b/core/java/src/net/i2p/client/I2PSessionImpl.java index 0a29ff9d8..04dde2050 100644 --- a/core/java/src/net/i2p/client/I2PSessionImpl.java +++ b/core/java/src/net/i2p/client/I2PSessionImpl.java @@ -159,6 +159,8 @@ abstract class I2PSessionImpl implements I2PSession, I2CPMessageReader.I2CPMessa * Create a new session, reading the Destination, PrivateKey, and SigningPrivateKey * from the destKeyStream, and using the specified options to connect to the router * + * @param destKeyStream stream containing the private key data, + * format is specified in {@link net.i2p.data.PrivateKeyFile PrivateKeyFile} * @param options set of options to configure the router with, if null will use System properties * @throws I2PSessionException if there is a problem loading the private keys or */ diff --git a/core/java/src/net/i2p/client/I2PSessionImpl2.java b/core/java/src/net/i2p/client/I2PSessionImpl2.java index 3af551eaa..0f397f68e 100644 --- a/core/java/src/net/i2p/client/I2PSessionImpl2.java +++ b/core/java/src/net/i2p/client/I2PSessionImpl2.java @@ -49,6 +49,8 @@ class I2PSessionImpl2 extends I2PSessionImpl { * Create a new session, reading the Destination, PrivateKey, and SigningPrivateKey * from the destKeyStream, and using the specified options to connect to the router * + * @param destKeyStream stream containing the private key data, + * format is specified in {@link net.i2p.data.PrivateKeyFile PrivateKeyFile} * @param options set of options to configure the router with, if null will use System properties * @throws I2PSessionException if there is a problem loading the private keys or */ diff --git a/core/java/src/net/i2p/client/I2PSessionMuxedImpl.java b/core/java/src/net/i2p/client/I2PSessionMuxedImpl.java index fcf11d0da..e125fc49b 100644 --- a/core/java/src/net/i2p/client/I2PSessionMuxedImpl.java +++ b/core/java/src/net/i2p/client/I2PSessionMuxedImpl.java @@ -65,9 +65,12 @@ import net.i2p.util.SimpleScheduler; * @author zzz */ class I2PSessionMuxedImpl extends I2PSessionImpl2 implements I2PSession { - private I2PSessionDemultiplexer _demultiplexer; + + private final I2PSessionDemultiplexer _demultiplexer; /* + * @param destKeyStream stream containing the private key data, + * format is specified in {@link net.i2p.data.PrivateKeyFile PrivateKeyFile} * @param options set of options to configure the router with, if null will use System properties */ public I2PSessionMuxedImpl(I2PAppContext ctx, InputStream destKeyStream, Properties options) throws I2PSessionException { @@ -92,11 +95,11 @@ class I2PSessionMuxedImpl extends I2PSessionImpl2 implements I2PSession { * An existing listener with the same proto and port is replaced. * Only the listener with the best match is called back for each message. * - * @param proto 1-254 or PROTO_ANY for all; recommended: + * @param proto 1-254 or PROTO_ANY (0) for all; recommended: * I2PSession.PROTO_STREAMING * I2PSession.PROTO_DATAGRAM * 255 disallowed - * @param port 1-65535 or PORT_ANY for all + * @param port 1-65535 or PORT_ANY (0) for all */ @Override public void addSessionListener(I2PSessionListener lsnr, int proto, int port) { @@ -106,8 +109,8 @@ class I2PSessionMuxedImpl extends I2PSessionImpl2 implements I2PSession { /** * Listen on specified protocol and port, and receive notification * of proto, fromPort, and toPort for every message. - * @param proto 1-254 or 0 for all; 255 disallowed - * @param port 1-65535 or 0 for all + * @param proto 1-254 or PROTO_ANY (0) for all; 255 disallowed + * @param port 1-65535 or PORT_ANY (0) for all */ @Override public void addMuxedSessionListener(I2PSessionMuxedListener l, int proto, int port) {