I2P Address: [http://git.idk.i2p]

Skip to content
Snippets Groups Projects
Commit 1c6b78a8 authored by sponge's avatar sponge
Browse files

SAM davadoc cleanups

JDK5 compliance
parent 8117d046
No related branches found
No related tags found
No related merge requests found
Showing
with 128 additions and 20 deletions
......@@ -90,6 +90,7 @@ public class SAMBridge implements Runnable {
/**
* Retrieve the destination associated with the given name
*
* @param name name of the destination
* @return null if the name does not exist, or if it is improperly formatted
*/
public Destination getDestination(String name) {
......@@ -113,6 +114,7 @@ public class SAMBridge implements Runnable {
* as a base64 string (Destination+PrivateKey+SessionPrivateKey, as I2CP
* stores it).
*
* @param name Name of the destination
* @return null if the name does not exist, else the stream
*/
public String getKeystream(String name) {
......@@ -126,6 +128,8 @@ public class SAMBridge implements Runnable {
/**
* Specify that the given keystream should be used for the given name
*
* @param name Name of the destination
* @param stream Name of the stream
*/
public void addKeystream(String name, String stream) {
synchronized (nameToPrivKeys) {
......@@ -194,7 +198,8 @@ public class SAMBridge implements Runnable {
* name=val options are passed to the I2CP code to build a session,
* allowing the bridge to specify an alternate I2CP host and port, tunnel
* depth, etc.
*/
* @param args [[listenHost ]listenPort[ name=val]*]
*/
public static void main(String args[]) {
String keyfile = DEFAULT_SAM_KEYFILE;
int port = SAM_LISTENPORT;
......
......@@ -20,7 +20,9 @@ public interface SAMDatagramReceiver {
/**
* Send a byte array to a SAM client.
*
* @param sender Destination
* @param data Byte array to be received
* @throws IOException
*/
public void receiveDatagramBytes(Destination sender, byte data[]) throws IOException;
......
......@@ -40,6 +40,9 @@ public class SAMDatagramSession extends SAMMessageSession {
* @param dest Base64-encoded destination (private key)
* @param props Properties to setup the I2P session
* @param recv Object that will receive incoming data
* @throws IOException
* @throws DataFormatException
* @throws I2PSessionException
*/
public SAMDatagramSession(String dest, Properties props,
SAMDatagramReceiver recv) throws IOException,
......@@ -56,6 +59,9 @@ public class SAMDatagramSession extends SAMMessageSession {
* @param destStream Input stream containing the destination keys
* @param props Properties to setup the I2P session
* @param recv Object that will receive incoming data
* @throws IOException
* @throws DataFormatException
* @throws I2PSessionException
*/
public SAMDatagramSession(InputStream destStream, Properties props,
SAMDatagramReceiver recv) throws IOException,
......@@ -69,9 +75,11 @@ public class SAMDatagramSession extends SAMMessageSession {
/**
* Send bytes through a SAM DATAGRAM session.
*
* @param dest Destination
* @param data Bytes to be sent
*
* @return True if the data was sent, false otherwise
* @throws DataFormatException
*/
public boolean sendBytes(String dest, byte[] data) throws DataFormatException {
if (data.length > DGRAM_SIZE_MAX)
......
......@@ -51,6 +51,7 @@ public abstract class SAMHandler implements Runnable {
* @param verMajor SAM major version to manage
* @param verMinor SAM minor version to manage
* @param i2cpProps properties to configure the I2CP connection (host, port, etc)
* @throws IOException
*/
protected SAMHandler(Socket s,
int verMajor, int verMinor, Properties i2cpProps) throws IOException {
......@@ -82,6 +83,8 @@ public abstract class SAMHandler implements Runnable {
/**
* Get the input stream of the socket connected to the SAM client
*
* @return input stream
* @throws IOException
*/
protected final InputStream getClientSocketInputStream() throws IOException {
return socket.getInputStream();
......@@ -93,6 +96,7 @@ public abstract class SAMHandler implements Runnable {
* you're doing.
*
* @param data A byte array to be written
* @throws IOException
*/
protected final void writeBytes(byte[] data) throws IOException {
synchronized (socketWLock) {
......@@ -105,6 +109,7 @@ public abstract class SAMHandler implements Runnable {
* If you're crazy enough to write to the raw socket, grab the write lock
* with getWriteLock(), synchronize against it, and write to the getOut()
*
* @return socket Write lock object
*/
protected Object getWriteLock() { return socketWLock; }
protected OutputStream getOut() { return socketOS; }
......@@ -134,6 +139,7 @@ public abstract class SAMHandler implements Runnable {
/**
* Close the socket connected to the SAM client.
*
* @throws IOException
*/
protected final void closeClientSocket() throws IOException {
if (socket != null)
......@@ -167,6 +173,7 @@ public abstract class SAMHandler implements Runnable {
*
* @return A String describing the handler;
*/
@Override
public final String toString() {
return ("SAM handler (class: " + this.getClass().getName()
+ "; SAM version: " + verMajor + "." + verMinor
......
......@@ -43,6 +43,9 @@ public abstract class SAMMessageSession {
*
* @param dest Base64-encoded destination (private key)
* @param props Properties to setup the I2P session
* @throws IOException
* @throws DataFormatException
* @throws I2PSessionException
*/
protected SAMMessageSession(String dest, Properties props) throws IOException, DataFormatException, I2PSessionException {
ByteArrayInputStream bais;
......@@ -57,6 +60,9 @@ public abstract class SAMMessageSession {
*
* @param destStream Input stream containing the destination keys
* @param props Properties to setup the I2P session
* @throws IOException
* @throws DataFormatException
* @throws I2PSessionException
*/
protected SAMMessageSession(InputStream destStream, Properties props) throws IOException, DataFormatException, I2PSessionException {
initSAMMessageSession(destStream, props);
......@@ -84,9 +90,11 @@ public abstract class SAMMessageSession {
/**
* Send bytes through a SAM message-based session.
*
* @param dest Destination
* @param data Bytes to be sent
*
* @return True if the data was sent, false otherwise
* @throws DataFormatException
*/
public abstract boolean sendBytes(String dest, byte[] data) throws DataFormatException;
......@@ -94,9 +102,11 @@ public abstract class SAMMessageSession {
* Actually send bytes through the SAM message-based session I2PSession
* (er...).
*
* @param dest Destination
* @param data Bytes to be sent
*
* @return True if the data was sent, false otherwise
* @throws DataFormatException
*/
protected boolean sendBytesThroughMessageSession(String dest, byte[] data) throws DataFormatException {
Destination d = new Destination();
......@@ -124,6 +134,7 @@ public abstract class SAMMessageSession {
/**
* Handle a new received message
* @param msg Message payload
*/
protected abstract void messageReceived(byte[] msg);
......@@ -156,7 +167,8 @@ public abstract class SAMMessageSession {
* Create a new SAM message-based session handler
*
* @param destStream Input stream containing the destination keys
* @param props Properties to setup the I2P session
* @param props Properties to setup the I2P session
* @throws I2PSessionException
*/
public SAMMessageSessionHandler(InputStream destStream, Properties props) throws I2PSessionException {
_log.debug("Instantiating new SAM message-based session handler");
......
......@@ -20,6 +20,7 @@ public interface SAMRawReceiver {
* regarding the sender.
*
* @param data Byte array to be received
* @throws IOException
*/
public void receiveRawBytes(byte data[]) throws IOException;
......
......@@ -33,6 +33,9 @@ public class SAMRawSession extends SAMMessageSession {
* @param dest Base64-encoded destination (private key)
* @param props Properties to setup the I2P session
* @param recv Object that will receive incoming data
* @throws IOException
* @throws DataFormatException
* @throws I2PSessionException
*/
public SAMRawSession(String dest, Properties props,
SAMRawReceiver recv) throws IOException, DataFormatException, I2PSessionException {
......@@ -47,6 +50,9 @@ public class SAMRawSession extends SAMMessageSession {
* @param destStream Input stream containing the destination keys
* @param props Properties to setup the I2P session
* @param recv Object that will receive incoming data
* @throws IOException
* @throws DataFormatException
* @throws I2PSessionException
*/
public SAMRawSession(InputStream destStream, Properties props,
SAMRawReceiver recv) throws IOException, DataFormatException, I2PSessionException {
......@@ -61,6 +67,7 @@ public class SAMRawSession extends SAMMessageSession {
* @param data Bytes to be sent
*
* @return True if the data was sent, false otherwise
* @throws DataFormatException
*/
public boolean sendBytes(String dest, byte[] data) throws DataFormatException {
if (data.length > RAW_SIZE_MAX)
......
......@@ -19,11 +19,17 @@ import net.i2p.data.Destination;
public interface SAMStreamReceiver {
/**
* Sends the result of a stream send operation
* @param id Stream ID
* @param result information
* @param bufferState state of the buffer
* @throws IOException
*/
public void streamSendAnswer( int id, String result, String bufferState ) throws IOException;
/**
* Notifies that the outwards buffer is free for writing
* @param id stream ID
* @throws IOException
*/
public void notifyStreamSendBufferFree( int id ) throws IOException;
......@@ -31,6 +37,8 @@ public interface SAMStreamReceiver {
* Notify about a new incoming connection
*
* @param id New connection id
* @param dest Destination
* @throws IOException
*/
public void notifyStreamIncomingConnection ( int id, Destination dest ) throws IOException;
......@@ -38,6 +46,9 @@ public interface SAMStreamReceiver {
* Notify about a new outgoing connection
*
* @param id New connection id
* @param result message result
* @param msg Message
* @throws IOException
*/
public void notifyStreamOutgoingConnection(int id, String result, String msg) throws IOException;
......@@ -47,6 +58,7 @@ public interface SAMStreamReceiver {
* @param id Connection id
* @param data Byte array to be received
* @param len Number of bytes in data
* @throws IOException
*/
public void receiveStreamBytes(int id, byte data[], int len) throws IOException;
......@@ -57,6 +69,7 @@ public interface SAMStreamReceiver {
* @param id Connection id
* @param result Disconnection reason ("OK" or something else)
* @param msg Error message, if any
* @throws IOException
*/
public void notifyStreamDisconnection(int id, String result, String msg) throws IOException;
......
......@@ -83,6 +83,9 @@ public class SAMStreamSession {
* @param dir Session direction ("RECEIVE", "CREATE" or "BOTH")
* @param props Properties to setup the I2P session
* @param recv Object that will receive incoming data
* @throws IOException
* @throws DataFormatException
* @throws SAMException
*/
public SAMStreamSession(String dest, String dir, Properties props,
SAMStreamReceiver recv) throws IOException, DataFormatException, SAMException {
......@@ -100,6 +103,9 @@ public class SAMStreamSession {
* @param dir Session direction ("RECEIVE", "CREATE" or "BOTH")
* @param props Properties to setup the I2P session
* @param recv Object that will receive incoming data
* @throws IOException
* @throws DataFormatException
* @throws SAMException
*/
public SAMStreamSession(InputStream destStream, String dir,
Properties props, SAMStreamReceiver recv) throws IOException, DataFormatException, SAMException {
......@@ -182,6 +188,7 @@ public class SAMStreamSession {
* @param dest Base64-encoded Destination to connect to
* @param props Options to be used for connection
*
* @return true if successful
* @throws DataFormatException if the destination is not valid
* @throws SAMInvalidDirectionException if trying to connect through a
* receive-only session
......@@ -189,6 +196,7 @@ public class SAMStreamSession {
* @throws NoRouteToHostException if the destination can't be reached
* @throws InterruptedIOException if the connection timeouts
* @throws I2PException if there's another I2P-related error
* @throws IOException
*/
public boolean connect ( int id, String dest, Properties props ) throws I2PException, ConnectException, NoRouteToHostException, DataFormatException, InterruptedIOException, SAMInvalidDirectionException, IOException {
if (!canCreate) {
......@@ -224,9 +232,11 @@ public class SAMStreamSession {
/**
* Send bytes through a SAM STREAM session.
*
* @param data Bytes to be sent
*
* @param id Stream Id
* @param in Datastream input
* @param size Count of bytes to send
* @return True if the data was queued for sending, false otherwise
* @throws IOException
*/
public boolean sendBytes(int id, InputStream in, int size) throws IOException {
StreamSender sender = getSender(id);
......@@ -264,6 +274,7 @@ public class SAMStreamSession {
* Close a connection managed by the SAM STREAM session.
*
* @param id Connection id
* @return true on success
*/
public boolean closeConnection(int id) {
if (!checkSocketHandlerId(id)) {
......@@ -323,6 +334,7 @@ public class SAMStreamSession {
* Get a SAM STREAM session socket handler.
*
* @param id Handler id
* @return SAM StreamSender handler
*/
protected SAMStreamSessionSocketReader getSocketReader ( int id ) {
synchronized (handlersMapLock) {
......@@ -339,6 +351,7 @@ public class SAMStreamSession {
* Check whether a SAM STREAM session socket handler id is still in use.
*
* @param id Handler id
* @return True if in use
*/
protected boolean checkSocketHandlerId ( int id ) {
synchronized (handlersMapLock) {
......@@ -503,7 +516,8 @@ public class SAMStreamSession {
* Create a new SAM STREAM session socket reader
*
* @param s Socket to be handled
* @param id Unique id assigned to the handler
* @param id Unique id assigned to the handler
* @throws IOException
*/
public SAMStreamSessionSocketReader ( I2PSocket s, int id ) throws IOException {}
......@@ -526,7 +540,8 @@ public class SAMStreamSession {
* Create a new SAM STREAM session socket reader
*
* @param s Socket to be handled
* @param id Unique id assigned to the handler
* @param id Unique id assigned to the handler
* @throws IOException
*/
public SAMv1StreamSessionSocketReader ( I2PSocket s, int id ) throws IOException {
......@@ -541,6 +556,7 @@ public class SAMStreamSession {
* Stop a SAM STREAM session socket reader thead immediately.
*
*/
@Override
public void stopRunning() {
_log.debug("stopRunning() invoked on socket reader " + id);
synchronized (runningLock) {
......@@ -551,6 +567,7 @@ public class SAMStreamSession {
}
}
@Override
public void run() {
_log.debug("run() called for socket reader " + id);
......@@ -605,8 +622,8 @@ public class SAMStreamSession {
/**
* Send bytes through the SAM STREAM session socket sender
*
* @param data Data to be sent
*
* @param in Data input stream
* @param size Count of bytes to send
* @throws IOException if the client didnt provide enough data
*/
public void sendBytes ( InputStream in, int size ) throws IOException {}
......@@ -655,10 +672,9 @@ public class SAMStreamSession {
/**
* Send bytes through the SAM STREAM session socket sender
*
* @param data Data to be sent
*
* @throws IOException if the client didnt provide enough data
*/
@Override
public void sendBytes(InputStream in, int size) throws IOException {
if (_log.shouldLog(Log.DEBUG))
_log.debug("Handler " + _id + ": sending " + size + " bytes");
......@@ -679,6 +695,7 @@ public class SAMStreamSession {
* Stop a SAM STREAM session socket sender thread immediately
*
*/
@Override
public void stopRunning() {
_log.debug("stopRunning() invoked on socket sender " + _id);
synchronized (runningLock) {
......@@ -701,11 +718,13 @@ public class SAMStreamSession {
* Stop a SAM STREAM session socket sender gracefully: stop the
* sender thread once all pending data has been sent.
*/
@Override
public void shutDownGracefully() {
_log.debug("shutDownGracefully() invoked on socket sender " + _id);
_shuttingDownGracefully = true;
}
@Override
public void run() {
_log.debug("run() called for socket sender " + _id);
ByteArray data = null;
......
......@@ -57,6 +57,8 @@ public class SAMv1Handler extends SAMHandler implements SAMRawReceiver, SAMDatag
* @param s Socket attached to a SAM client
* @param verMajor SAM major version to manage (should be 1)
* @param verMinor SAM minor version to manage
* @throws SAMException
* @throws IOException
*/
public SAMv1Handler(Socket s, int verMajor, int verMinor) throws SAMException, IOException {
this(s, verMajor, verMinor, new Properties());
......@@ -70,6 +72,8 @@ public class SAMv1Handler extends SAMHandler implements SAMRawReceiver, SAMDatag
* @param verMajor SAM major version to manage (should be 1)
* @param verMinor SAM minor version to manage
* @param i2cpProps properties to configure the I2CP connection (host, port, etc)
* @throws SAMException
* @throws IOException
*/
public SAMv1Handler(Socket s, int verMajor, int verMinor, Properties i2cpProps) throws SAMException, IOException {
super(s, verMajor, verMinor, i2cpProps);
......
......@@ -47,6 +47,9 @@ public class SAMv2StreamSession extends SAMStreamSession
* @param dir Session direction ("RECEIVE", "CREATE" or "BOTH")
* @param props Properties to setup the I2P session
* @param recv Object that will receive incoming data
* @throws IOException
* @throws DataFormatException
* @throws SAMException
*/
public SAMv2StreamSession ( String dest, String dir, Properties props,
SAMStreamReceiver recv ) throws IOException, DataFormatException, SAMException
......@@ -61,6 +64,9 @@ public class SAMv2StreamSession extends SAMStreamSession
* @param dir Session direction ("RECEIVE", "CREATE" or "BOTH")
* @param props Properties to setup the I2P session
* @param recv Object that will receive incoming data
* @throws IOException
* @throws DataFormatException
* @throws SAMException
*/
public SAMv2StreamSession ( InputStream destStream, String dir,
Properties props, SAMStreamReceiver recv ) throws IOException, DataFormatException, SAMException
......@@ -81,6 +87,7 @@ public class SAMv2StreamSession extends SAMStreamSession
* @return true if the communication with the SAM client is ok
*/
@Override
public boolean connect ( int id, String dest, Properties props )
throws DataFormatException, SAMInvalidDirectionException
{
......@@ -215,13 +222,20 @@ public class SAMv2StreamSession extends SAMStreamSession
/**
* Lets us push data through the stream without blocking, (even after exceeding
* the I2PSocket's buffer)
*/
*
* @param s I2PSocket
* @param id Socket ID
* @return v2StreamSender
* @throws IOException
*/
@Override
protected StreamSender newStreamSender ( I2PSocket s, int id ) throws IOException
{
return new v2StreamSender ( s, id ) ;
}
@Override
protected SAMStreamSessionSocketReader
newSAMStreamSessionSocketReader(I2PSocket s, int id ) throws IOException
{
......@@ -256,10 +270,11 @@ public class SAMv2StreamSession extends SAMStreamSession
/**
* Send bytes through the SAM STREAM session socket sender
*
* @param data Data to be sent
*
* @throws IOException if the client didnt provide enough data
* @param in Data stream of data to send
* @param size Count of bytes to send
* @throws IOException if the client didnt provide enough data
*/
@Override
public void sendBytes ( InputStream in, int size ) throws IOException
{
if ( _log.shouldLog ( Log.DEBUG ) )
......@@ -303,6 +318,7 @@ public class SAMv2StreamSession extends SAMStreamSession
* Stop a SAM STREAM session socket sender thread immediately
*
*/
@Override
public void stopRunning()
{
_log.debug ( "stopRunning() invoked on socket sender " + _id );
......@@ -335,12 +351,14 @@ public class SAMv2StreamSession extends SAMStreamSession
* Stop a SAM STREAM session socket sender gracefully: stop the
* sender thread once all pending data has been sent.
*/
@Override
public void shutDownGracefully()
{
_log.debug ( "shutDownGracefully() invoked on socket sender " + _id );
_shuttingDownGracefully = true;
}
@Override
public void run()
{
_log.debug ( "run() called for socket sender " + _id );
......@@ -420,12 +438,14 @@ public class SAMv2StreamSession extends SAMStreamSession
/**
* Send bytes through a SAM STREAM session.
*
* @param data Bytes to be sent
*
* @return True if the data was queued for sending, false otherwise
* Send bytes through a SAM STREAM session.
*
* @param id Stream ID
* @param limit limitation
* @param nolimit true to limit
* @return True if the data was queued for sending, false otherwise
*/
@Override
public boolean setReceiveLimit ( int id, long limit, boolean nolimit )
{
SAMStreamSessionSocketReader reader = getSocketReader ( id );
......
......@@ -26,6 +26,7 @@ public class SAMEventHandler extends SAMClientEventListenerImpl {
_log = ctx.logManager().getLog(getClass());
}
@Override
public void helloReplyReceived(boolean ok) {
synchronized (_helloLock) {
if (ok)
......@@ -36,6 +37,7 @@ public class SAMEventHandler extends SAMClientEventListenerImpl {
}
}
@Override
public void sessionStatusReceived(String result, String destination, String msg) {
synchronized (_sessionCreateLock) {
if (SAMReader.SAMClientEventListener.SESSION_STATUS_OK.equals(result))
......@@ -46,6 +48,7 @@ public class SAMEventHandler extends SAMClientEventListenerImpl {
}
}
@Override
public void namingReplyReceived(String name, String result, String value, String msg) {
synchronized (_namingReplyLock) {
if (SAMReader.SAMClientEventListener.NAMING_REPLY_OK.equals(result))
......@@ -56,6 +59,7 @@ public class SAMEventHandler extends SAMClientEventListenerImpl {
}
}
@Override
public void unknownMessageReceived(String major, String minor, Properties params) {
_log.error("wrt, [" + major + "] [" + minor + "] [" + params + "]");
}
......@@ -68,6 +72,7 @@ public class SAMEventHandler extends SAMClientEventListenerImpl {
/**
* Wait for the connection to be established, returning true if everything
* went ok
* @return true if everything ok
*/
public boolean waitForHelloReply() {
while (true) {
......@@ -85,6 +90,7 @@ public class SAMEventHandler extends SAMClientEventListenerImpl {
/**
* Wait for the session to be created, returning true if everything went ok
*
* @return true if everything ok
*/
public boolean waitForSessionCreateReply() {
while (true) {
......@@ -104,6 +110,7 @@ public class SAMEventHandler extends SAMClientEventListenerImpl {
* not able to be retrieved.
*
* @param name name to be looked for, or "ME"
* @return destination found matching the name, or null
*/
public String waitForNamingReply(String name) {
while (true) {
......
......@@ -54,7 +54,7 @@ public class SAMStreamSend {
_samHost = samHost;
_samPort = samPort;
_destFile = destFile;
_dataFile = dataFile;;
_dataFile = dataFile;
_conOptions = "";
_eventHandler = new SendEventHandler(_context);
_remotePeers = new HashMap();
......
......@@ -78,6 +78,7 @@ public class SAMStreamSink {
private class SinkEventHandler extends SAMEventHandler {
public SinkEventHandler(I2PAppContext ctx) { super(ctx); }
@Override
public void streamClosedReceived(String result, int id, String message) {
Sink sink = null;
synchronized (_remotePeers) {
......@@ -90,6 +91,7 @@ public class SAMStreamSink {
_log.error("wtf, not connected to " + id + " but we were just closed?");
}
}
@Override
public void streamDataReceived(int id, byte data[], int offset, int length) {
Sink sink = null;
synchronized (_remotePeers) {
......@@ -101,6 +103,7 @@ public class SAMStreamSink {
_log.error("wtf, not connected to " + id + " but we received " + length + "?");
}
}
@Override
public void streamConnectedReceived(String dest, int id) {
_log.debug("Connection " + id + " received from " + dest);
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment