Skip to main content
aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorAntonio Gutierrez2016-07-26 20:51:48 +0000
committerAntonio Gutierrez2016-07-26 21:42:22 +0000
commitfd158c97078535d87142a696514f5f00090f8909 (patch)
tree310522b9cbfb8d715b0f2113c26f8d85d5ed0e3c /plugins
parentd6840e70b5c7307cd2e1da374cb258d83eea678f (diff)
downloadorg.eclipse.tcf-fd158c97078535d87142a696514f5f00090f8909.tar.gz
org.eclipse.tcf-fd158c97078535d87142a696514f5f00090f8909.tar.xz
org.eclipse.tcf-fd158c97078535d87142a696514f5f00090f8909.zip
Add javadoc comments to tcf core
Adding comments of this type will facilitate comprehension and ramp up of newcomers while browsing using any Java IDE. Change-Id: I0bfc60113ffa8466ce0da849891fa8756799128d Signed-off-by: Antonio Gutierrez <chibby0ne@gmail.com>
Diffstat (limited to 'plugins')
-rw-r--r--plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/core/AbstractChannel.java175
-rw-r--r--plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/core/AbstractPeer.java44
-rw-r--r--plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/core/ChannelTCP.java23
-rw-r--r--plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/core/Command.java10
-rw-r--r--plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/core/TransientPeer.java3
-rw-r--r--plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/core/ChannelLoop.java6
-rw-r--r--plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/core/RemotePeer.java4
-rw-r--r--plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/core/ServiceManager.java8
-rw-r--r--plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/core/Token.java26
-rw-r--r--plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/core/TransportManager.java85
-rw-r--r--plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/services/local/LocatorService.java282
-rw-r--r--plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/protocol/IServiceProvider.java11
-rw-r--r--plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/protocol/Protocol.java25
-rw-r--r--plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/services/ILocator.java3
-rw-r--r--plugins/org.eclipse.tcf/src/org/eclipse/tcf/Activator.java3
15 files changed, 660 insertions, 48 deletions
diff --git a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/core/AbstractChannel.java b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/core/AbstractChannel.java
index 0c42ad814..1a4b0db3a 100644
--- a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/core/AbstractChannel.java
+++ b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/core/AbstractChannel.java
@@ -63,11 +63,34 @@ public abstract class AbstractChannel implements IChannel {
public void onChannelClosed(Throwable error);
}
+ /**
+ * Represents a message sent through a channel between peers
+ */
private static class Message {
+ /**
+ * Type of message.
+ * "C" for Commands.
+ * "R" for Command Results.
+ * "N" for Unkown Command Result.
+ * "P" for Progress Result.
+ * "E" for Events.
+ */
final char type;
+ /**
+ * Token associated with the Command
+ */
Token token;
+ /**
+ * Name of the service
+ */
String service;
+ /**
+ * In case of a Command ("C" Message) or an Event ("E" Message), the name of it
+ */
String name;
+ /**
+ * The array of bytes that accompanies the message
+ */
byte[] data;
boolean is_sent;
@@ -75,6 +98,10 @@ public abstract class AbstractChannel implements IChannel {
Collection<TraceListener> trace;
+ /**
+ * Constructs a Message of the given type. Type could be 'C', 'R', 'N' 'P' or 'E'
+ * @param type type of message
+ */
Message(char type) {
this.type = type;
}
@@ -126,6 +153,9 @@ public abstract class AbstractChannel implements IChannel {
private final Collection<IChannelListener> channel_listeners = new ArrayList<IChannelListener>();
private final Map<String,IChannel.IEventListener[]> event_listeners = new HashMap<String,IChannel.IEventListener[]>();
private final Map<String,IChannel.ICommandServer> command_servers = new HashMap<String,IChannel.ICommandServer>();
+ /**
+ * Tokens used for output
+ */
private final Map<String,Message> out_tokens = new LinkedHashMap<String,Message>();
private final Thread inp_thread;
private final Thread out_thread;
@@ -151,8 +181,14 @@ public abstract class AbstractChannel implements IChannel {
protected static final boolean TRACE = Boolean.getBoolean("org.eclipse.tcf.core.tracing.channel");
public static final int
- EOS = -1, // End Of Stream
- EOM = -2; // End Of Message
+ /**
+ * End of Stream
+ */
+ EOS = -1,
+ /**
+ * End of Message
+ */
+ EOM = -2;
protected AbstractChannel(IPeer remote_peer) {
this(LocatorService.getLocalPeer(), remote_peer);
@@ -163,32 +199,58 @@ public abstract class AbstractChannel implements IChannel {
this.remote_peer = remote_peer;
this.local_peer = local_peer;
+ /**
+ * Thread used handles messages received through the channel
+ */
inp_thread = new Thread() {
+ /**
+ * Empty byte array used when returning a zero-length byte array on {@code readBytes}
+ */
final byte[] empty_byte_array = new byte[0];
+ /**
+ * Byte array used as temporary storage of bytes read on {@code readBytes}
+ */
byte[] buf = new byte[1024];
+ /**
+ * Byte array used as temporary storage of bytes read on {@code readString}
+ */
char[] cbf = new char[1024];
+
+ /**
+ * Byte array used to store the error
+ */
byte[] eos_err_report;
+ /**
+ * Throws an IOException when the input thread reads a malformed Message from the channel
+ * @throws IOException with the message "Protocol syntax error"
+ */
private void error() throws IOException {
throw new IOException("Protocol syntax error");
}
+ /**
+ * Reads bytes from a channel
+ * @param end the first byte character
+ * @return a byte array containing all the bytes read
+ * @throws IOException if it finds EOM or EOS reading from input stream
+ */
private byte[] readBytes(int end) throws IOException {
int len = 0;
for (;;) {
- int n = read();
- if (n <= 0) {
- if (n == end) break;
- if (n == EOM) throw new IOException("Unexpected end of message");
- if (n < 0) throw new IOException("Communication channel is closed by remote peer");
+ int ch = read();
+ if (ch <= 0) {
+ if (ch == end) break;
+ if (ch == EOM) throw new IOException("Unexpected end of message");
+ if (ch < 0) throw new IOException("Communication channel is closed by remote peer");
}
if (len >= buf.length) {
byte[] tmp = new byte[buf.length * 2];
System.arraycopy(buf, 0, tmp, 0, len);
buf = tmp;
}
- buf[len++] = (byte)n;
+ buf[len++] = (byte)ch;
}
if (len == 0) return empty_byte_array;
byte[] res = new byte[len];
@@ -196,6 +258,11 @@ public abstract class AbstractChannel implements IChannel {
return res;
}
+ /**
+ * Reads complete strings made of bytes and return the Java string that it forms
+ * @return string containing all the bytes read
+ * @throws IOException if it finds EOM or EOS reading from input stream
+ */
private String readString() throws IOException {
int len = 0;
for (;;) {
@@ -204,6 +271,9 @@ public abstract class AbstractChannel implements IChannel {
if (ch == EOM) throw new IOException("Unexpected end of message");
if (ch < 0) throw new IOException("Communication channel is closed by remote peer");
}
+ /*
+ * Check if ch is not part of the Basic Latin alphabet
+ */
if ((ch & 0x80) != 0) {
int n = 0;
if ((ch & 0xe0) == 0xc0) {
@@ -237,6 +307,9 @@ public abstract class AbstractChannel implements IChannel {
}
}
if (ch == 0) break;
+ /*
+ * Duplicate size of array used to hold the bytes, after the size is bigger than original array
+ */
if (len >= cbf.length) {
char[] tmp = new char[cbf.length * 2];
System.arraycopy(cbf, 0, tmp, 0, len);
@@ -288,6 +361,9 @@ public abstract class AbstractChannel implements IChannel {
default:
error();
}
+ /*
+ * Message handling is done in the dispatch thread
+ */
Protocol.invokeLater(new Runnable() {
public void run() {
handleInput(msg);
@@ -333,6 +409,9 @@ public abstract class AbstractChannel implements IChannel {
}
};
+ /**
+ * Thread used to handle messages sent through the channel
+ */
out_thread = new Thread() {
private final byte[] out_buf = new byte[0x4000];
@@ -591,7 +670,9 @@ public abstract class AbstractChannel implements IChannel {
for (IService service : by_name.values()) {
for (Class<?> fs : service.getClass().getInterfaces()) {
if (fs.equals(IService.class)) continue;
- if (!IService.class.isAssignableFrom(fs)) continue;
+ if (!IService.class.isAssignableFrom(fs)) {
+ continue;
+ }
by_class.put(fs, service);
}
}
@@ -672,7 +753,9 @@ public abstract class AbstractChannel implements IChannel {
public void close() {
assert Protocol.isDispatchThread();
- if (state == STATE_CLOSED) return;
+ if (state == STATE_CLOSED) {
+ return;
+ }
try {
sendEndOfStream(10000);
close(null);
@@ -684,7 +767,9 @@ public abstract class AbstractChannel implements IChannel {
public void terminate(Throwable error) {
assert Protocol.isDispatchThread();
- if (state == STATE_CLOSED) return;
+ if (state == STATE_CLOSED) {
+ return;
+ }
try {
sendEndOfStream(500);
close(error);
@@ -897,32 +982,58 @@ public abstract class AbstractChannel implements IChannel {
return token;
}
+ /**
+ * Send a command's progress response. Used for commands that can deliver partial results.
+ * @param token token associated with this command/response
+ * @param results array of bytes containing the data of the message
+ */
public void sendProgress(IToken token, byte[] results) {
assert Protocol.isDispatchThread();
- if (state != STATE_OPEN) throw new Error("Channel is closed");
+ if (state != STATE_OPEN) {
+ throw new Error("Channel is closed");
+ }
Message msg = new Message('P');
msg.data = results;
msg.token = (Token)token;
addToOutQueue(msg);
}
+ /**
+ * Send a command's result response. There's exactly one result per command
+ * @param token token associated with this command/response
+ * @param results array of bytes containing the data of the message
+ */
public void sendResult(IToken token, byte[] results) {
assert Protocol.isDispatchThread();
- if (state != STATE_OPEN) throw new Error("Channel is closed");
+ if (state != STATE_OPEN) {
+ throw new Error("Channel is closed");
+ }
Message msg = new Message('R');
msg.data = results;
msg.token = (Token)token;
addToOutQueue(msg);
}
+ /**
+ * Sends an "unrecognized command" message for the command corresponding to the given token
+ * @param token token associated with this command/response
+ */
public void rejectCommand(IToken token) {
assert Protocol.isDispatchThread();
- if (state != STATE_OPEN) throw new Error("Channel is closed");
+ if (state != STATE_OPEN) {
+ throw new Error("Channel is closed");
+ }
Message msg = new Message('N');
msg.token = (Token)token;
addToOutQueue(msg);
}
+ /**
+ * Sends an event message with the given name, for the given service with the given arguments
+ * @param service service this event belongs to
+ * @param name event's name
+ * @param args additional arguments of the event
+ */
public void sendEvent(IService service, String name, byte[] args) {
assert Protocol.isDispatchThread();
if (!(state == STATE_OPEN || state == STATE_OPENING && service instanceof ILocator)) {
@@ -939,10 +1050,16 @@ public abstract class AbstractChannel implements IChannel {
return zero_copy;
}
+ /**
+ * Handles the message received from the channel
+ * @param msg
+ */
@SuppressWarnings("unchecked")
private void handleInput(Message msg) {
assert Protocol.isDispatchThread();
- if (state == STATE_CLOSED) return;
+ if (state == STATE_CLOSED) {
+ return;
+ }
if (trace_listeners != null) {
for (TraceListener l : trace_listeners) {
try {
@@ -964,7 +1081,9 @@ public abstract class AbstractChannel implements IChannel {
case 'N':
String token_id = msg.token.getID();
cmd = msg.type == 'P' ? out_tokens.get(token_id) : out_tokens.remove(token_id);
- if (cmd == null) throw new Exception("Invalid token received: " + token_id);
+ if (cmd == null) {
+ throw new Exception("Invalid token received: " + token_id);
+ }
token = cmd.token;
break;
}
@@ -1087,15 +1206,25 @@ public abstract class AbstractChannel implements IChannel {
}
}
+ /**
+ *
+ * @throws IOException
+ */
private void sendCongestionLevel() throws IOException {
- if (++local_congestion_cnt < 8) return;
+ if (++local_congestion_cnt < 8) {
+ return;
+ }
local_congestion_cnt = 0;
if (state != STATE_OPEN) return;
long time = System.currentTimeMillis();
- if (time - local_congestion_time < 500) return;
+ if (time - local_congestion_time < 500) {
+ return;
+ }
assert Protocol.isDispatchThread();
int level = Protocol.getCongestionLevel();
- if (level == local_congestion_level) return;
+ if (level == local_congestion_level) {
+ return;
+ }
int i = (level - local_congestion_level) / 8;
if (i != 0) level = local_congestion_level + i;
local_congestion_time = time;
@@ -1157,7 +1286,9 @@ public abstract class AbstractChannel implements IChannel {
*/
protected void write(byte[] buf) throws IOException {
assert Thread.currentThread() == out_thread;
- for (int i = 0; i < buf.length; i++) write(buf[i] & 0xff);
+ for (int i = 0; i < buf.length; i++) {
+ write(buf[i] & 0xff);
+ }
}
/**
@@ -1171,6 +1302,8 @@ public abstract class AbstractChannel implements IChannel {
*/
protected void write(byte[] buf, int pos, int len) throws IOException {
assert Thread.currentThread() == out_thread;
- for (int i = pos; i < pos + len; i++) write(buf[i] & 0xff);
+ for (int i = pos; i < pos + len; i++) {
+ write(buf[i] & 0xff);
+ }
}
}
diff --git a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/core/AbstractPeer.java b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/core/AbstractPeer.java
index 7827af027..779acbf84 100644
--- a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/core/AbstractPeer.java
+++ b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/core/AbstractPeer.java
@@ -22,46 +22,66 @@ import org.eclipse.tcf.services.ILocator;
import org.eclipse.tcf.services.ILocator.LocatorListener;
/**
- * Abstract implementation of IPeer interface.
- * Objects of this class are stored in Locator service peer table.
- * The class implements sending notification events to Locator listeners.
- * See TransientPeer for IPeer objects that are not stored in the Locator table.
+ * Abstract implementation of IPeer interface. Objects of this class are stored
+ * in Locator service peer table. The class implements sending notification
+ * events to Locator listeners. See TransientPeer for IPeer objects that are not
+ * stored in the Locator table.
*/
public class AbstractPeer extends TransientPeer {
private long last_heart_beat_time;
- public AbstractPeer(Map<String,String> attrs) {
+ /**
+ * Constructs an AbstractPeer object using the given attributes, adds the
+ * peer to the LocatorService Peer Table and sends a "peerAdded" event to
+ * the TCF Channel
+ *
+ * @param attrs attributes maps with which to initialize the peer
+ */
+ public AbstractPeer(Map<String, String> attrs) {
super(attrs);
assert Protocol.isDispatchThread();
String id = getID();
assert id != null;
- Map<String,IPeer> peers = LocatorService.getLocator().getPeers();
+ Map<String, IPeer> peers = LocatorService.getLocator().getPeers();
if (peers.get(id) instanceof RemotePeer) {
- ((RemotePeer)peers.get(id)).dispose();
+ ((RemotePeer) peers.get(id)).dispose();
}
assert peers.get(id) == null;
peers.put(id, this);
sendPeerAddedEvent();
}
+ /**
+ * Removes the Peer from the Locator Service Peer table and sends a
+ * "peerRemoved" event to the TCF Channel
+ */
public void dispose() {
assert Protocol.isDispatchThread();
String id = getID();
assert id != null;
- Map<String,IPeer> peers = LocatorService.getLocator().getPeers();
+ Map<String, IPeer> peers = LocatorService.getLocator().getPeers();
assert peers.get(id) == this;
peers.remove(id);
sendPeerRemovedEvent();
}
+ /**
+ * Method called whenever a channel is terminated
+ */
void onChannelTerminated() {
// A channel to this peer was terminated:
// not delaying next heart beat helps client to recover much faster.
last_heart_beat_time = 0;
}
- public void updateAttributes(Map<String,String> attrs) {
+ /**
+ * Updates Peer properties using the given attributes parameters
+ *
+ * @param attrs
+ * attributes map with which to update the peer
+ */
+ public void updateAttributes(Map<String, String> attrs) {
long time = System.currentTimeMillis();
if (!attrs.equals(ro_attrs)) {
assert attrs.get(ATTR_ID).equals(rw_attrs.get(ATTR_ID));
@@ -104,6 +124,9 @@ public class AbstractPeer extends TransientPeer {
}
}
+ /**
+ * Sends a "peerAdded" event to the TCF Channel
+ */
private void sendPeerAddedEvent() {
for (LocatorListener l : LocatorService.getListeners()) {
try {
@@ -123,6 +146,9 @@ public class AbstractPeer extends TransientPeer {
last_heart_beat_time = System.currentTimeMillis();
}
+ /**
+ * Sends a "PeerRemoved" event to the TCF Channel
+ */
private void sendPeerRemovedEvent() {
for (LocatorListener l : LocatorService.getListeners()) {
try {
diff --git a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/core/ChannelTCP.java b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/core/ChannelTCP.java
index 3f705ef22..0439f4d65 100644
--- a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/core/ChannelTCP.java
+++ b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/core/ChannelTCP.java
@@ -43,6 +43,13 @@ public class ChannelTCP extends StreamChannel {
ChannelTCP.ssl_context = ssl_context;
}
+ /**
+ * Main constructor of ChannelTCP
+ * @param remote_peer Remote Peer to which we want to connect
+ * @param host Hostname or IP Address of the Remote Peer
+ * @param port Port of the Remote Peer
+ * @param ssl true if the socket needs to be an SSL socket, false otherwise
+ */
public ChannelTCP(IPeer remote_peer, final String host, final int port, final boolean ssl) {
super(remote_peer);
socket = new Socket();
@@ -74,10 +81,23 @@ public class ChannelTCP extends StreamChannel {
});
}
+ /**
+ * Constructs a non-secured ChannelTCP, i.e: the socket underlying the ChannelTCP is non-SSL socket
+ * @param remote_peer Remote Peer to which we want to connect
+ * @param host Hostname or IP Address of the Remote Peer
+ * @param port Port of the Remote Peer
+ */
public ChannelTCP(IPeer remote_peer, String host, int port) {
this(remote_peer, host, port, false);
}
+ /**
+ * Construct a non-secured ChannelTCP, i.e: the socket underlying the ChannelTCP is non-SSL socket.
+ * @param local_peer local peer
+ * @param remote_peer Remote Peer to which we want to connect
+ * @param socket socket for the underlying tcp connection
+ * @throws IOException
+ */
public ChannelTCP(IPeer local_peer, IPeer remote_peer, Socket socket) throws IOException {
super(local_peer, remote_peer);
this.socket = socket;
@@ -116,6 +136,9 @@ public class ChannelTCP extends StreamChannel {
socket.setPerformancePreferences(connection_time, latency, bandwidth);
}
+ /**
+ * @param x exception object, or null if there was no exception creating the ChannelTCP object
+ */
private void onSocketConnected(final Throwable x) {
Protocol.invokeLater(new Runnable() {
public void run() {
diff --git a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/core/Command.java b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/core/Command.java
index 629f59c53..9f3405a06 100644
--- a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/core/Command.java
+++ b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/core/Command.java
@@ -69,6 +69,13 @@ public abstract class Command implements IChannel.ICommandListener {
private static final SimpleDateFormat timestamp_format = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS");
private static int arg_size_limit = Integer.MAX_VALUE;
+ /**
+ * Constructs a Command message on the given channel, belong to the given service, with the given command name, and with the given array of arguments
+ * @param channel
+ * @param service
+ * @param command
+ * @param args
+ */
public Command(IChannel channel, IService service, String command, Object[] args) {
this.service = service;
this.command = command;
@@ -92,6 +99,9 @@ public abstract class Command implements IChannel.ICommandListener {
token = t;
}
+ /**
+ * l
+ */
public void progress(IToken token, byte[] data) {
assert this.token == token;
}
diff --git a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/core/TransientPeer.java b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/core/TransientPeer.java
index 671c2e87e..cbb75a148 100644
--- a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/core/TransientPeer.java
+++ b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/core/TransientPeer.java
@@ -26,6 +26,9 @@ import org.eclipse.tcf.protocol.IPeer;
public class TransientPeer implements IPeer {
protected final Map<String, String> ro_attrs;
+ /**
+ * Attributes
+ */
protected final Map<String, String> rw_attrs;
public TransientPeer(Map<String,String> attrs) {
diff --git a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/core/ChannelLoop.java b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/core/ChannelLoop.java
index c2617f73d..d0cc5f8b1 100644
--- a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/core/ChannelLoop.java
+++ b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/core/ChannelLoop.java
@@ -16,7 +16,11 @@ import java.io.InterruptedIOException;
import org.eclipse.tcf.core.StreamChannel;
import org.eclipse.tcf.protocol.IPeer;
-
+/**
+ * Simulates a loopback connection, which feeds a received signal back to
+ * the sender
+ *
+ */
public class ChannelLoop extends StreamChannel {
private final byte[] buf = new byte[0x1000];
diff --git a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/core/RemotePeer.java b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/core/RemotePeer.java
index 20c93a37f..7f78b577d 100644
--- a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/core/RemotePeer.java
+++ b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/core/RemotePeer.java
@@ -27,6 +27,10 @@ public class RemotePeer extends AbstractPeer {
private long last_update_time;
+ /**
+ * Constructs a Remote Peer and initializes it with the given attributes
+ * @param attrs attributes map used to initialize the Peer Properties
+ */
public RemotePeer(Map<String,String> attrs) {
super(attrs);
last_update_time = System.currentTimeMillis();
diff --git a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/core/ServiceManager.java b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/core/ServiceManager.java
index f7248eadf..23caf6a54 100644
--- a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/core/ServiceManager.java
+++ b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/core/ServiceManager.java
@@ -22,6 +22,10 @@ import org.eclipse.tcf.protocol.IService;
import org.eclipse.tcf.protocol.IServiceProvider;
import org.eclipse.tcf.protocol.Protocol;
+/**
+ * ServiceManager class provides static methods used to handle ServiceProviders.
+ * These methods are used by the Protocol class and the LocatorService Class.
+ */
public class ServiceManager {
private static final Collection<IServiceProvider> providers = new ArrayList<IServiceProvider>();
@@ -49,6 +53,10 @@ public class ServiceManager {
});
}
+ /**
+ * Get the ServiceManager ID
+ * @return ServiceManagerID
+ */
public static String getID() {
// In current implementation ServiceManager is a singleton,
// so its ID is same as agent ID.
diff --git a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/core/Token.java b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/core/Token.java
index f1f38b012..4ceb3e79f 100644
--- a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/core/Token.java
+++ b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/core/Token.java
@@ -13,13 +13,27 @@ package org.eclipse.tcf.internal.core;
import org.eclipse.tcf.protocol.IChannel;
import org.eclipse.tcf.protocol.IToken;
-
+/**
+ * Implementation of the {@code IToken} interface. Used to match commands to results and to cancel pending commands
+ */
public class Token implements IToken {
+ /**
+ * Internal static variable used to update the Token ID for the given command
+ */
private static int cnt = 0;
+ /**
+ * Token ID. This is what is seen when we
+ */
private final String id;
+ /**
+ * Byte representation of the Token ID
+ */
private final byte[] bytes;
+ /**
+ * ICommandListener associated with this token
+ */
private final IChannel.ICommandListener listener;
public Token() {
@@ -28,6 +42,11 @@ public class Token implements IToken {
listener = null;
}
+ /**
+ * Constructs a token with the given ICommandListener.
+ * Used when sending a command/result to the channel
+ * @param listener ICommandListener
+ */
public Token(IChannel.ICommandListener listener) {
this.listener = listener;
id = Integer.toString(cnt++);
@@ -36,6 +55,11 @@ public class Token implements IToken {
for (int i = 0; i < l; i++) bytes[i] = (byte)id.charAt(i);
}
+ /**
+ * Constructs a token from an array of bytes.
+ * Used when receiving a command/result from the channel
+ * @param bytes
+ */
public Token(byte[] bytes) {
this.bytes = bytes;
listener = null;
diff --git a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/core/TransportManager.java b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/core/TransportManager.java
index f5042d4e2..ecb27113f 100644
--- a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/core/TransportManager.java
+++ b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/core/TransportManager.java
@@ -28,13 +28,28 @@ import org.eclipse.tcf.protocol.ITransportProvider;
import org.eclipse.tcf.protocol.Protocol;
import org.eclipse.tcf.services.ILocator;
-
+/**
+ * Class TansportManager provides static methods for other core and internal TCF
+ * classes which concern the maintenance of Channels, ChannelOpenListeners and
+ * TransportProviders </br>
+ *
+ * These methods are used by Protocol, TransientPeer, AbstractChannel, and others.
+ */
public class TransportManager {
+ /**
+ * Collection of Channels
+ */
private static final Collection<AbstractChannel> channels =
new LinkedList<AbstractChannel>();
+ /**
+ * Collection of ChannelOpenListeners
+ */
private static final Collection<Protocol.ChannelOpenListener> listeners =
new LinkedList<Protocol.ChannelOpenListener>();
+ /**
+ * Map of TransportProviders and their names
+ */
private static final HashMap<String,ITransportProvider> transports =
new HashMap<String,ITransportProvider>();
@@ -98,6 +113,12 @@ public class TransportManager {
});
}
+ /**
+ * Converts a port number from String representation to int
+ *
+ * @param port port number
+ * @return port number as an int
+ */
private static int parsePort(String port) {
if (port == null) throw new Error("No port number");
try {
@@ -111,6 +132,16 @@ public class TransportManager {
}
}
+ /**
+ * Adds different transport providers to the private collection of
+ * transports, if a transport was already in the collection, then it a Error
+ * is thrown
+ *
+ * This is internal API, TCF clients should use {@code org.eclipse.tcf.protocol.Protocol}
+ *
+ * @param transport
+ * TransportProviders such as TCP, Pipe, etc..
+ */
public static void addTransportProvider(ITransportProvider transport) {
String name = transport.getName();
assert name != null;
@@ -120,6 +151,14 @@ public class TransportManager {
}
}
+ /**
+ * Remove transport providers to the private collection of transports, if a
+ * transport if a transport was already in the collection
+ *
+ * This is internal API, TCF clients should use {@code org.eclipse.tcf.protocol.Protocol}
+ *
+ * @param transport TransportProviders such as TCP, Pipe, etc..
+ */
public static void removeTransportProvider(ITransportProvider transport) {
String name = transport.getName();
assert name != null;
@@ -128,6 +167,15 @@ public class TransportManager {
}
}
+ /**
+ * Opens the Channel to which the peer belongs to, using the underlying
+ * TransportProvider. The channel is not added to the list of open channels
+ * yet because the channel is not fully open.
+ *
+ * @param peer
+ * on which to open the channel
+ * @return the channel instance to be opened
+ */
public static IChannel openChannel(IPeer peer) {
String name = peer.getTransportName();
if (name == null) throw new Error("No transport name");
@@ -139,6 +187,12 @@ public class TransportManager {
return transport.openChannel(peer);
}
+ /**
+ * Adds the channel to the collection of open channels. The channel is fully
+ * open by this time.
+ *
+ * @param channel the channel
+ */
public static void channelOpened(final AbstractChannel channel) {
assert !channels.contains(channel);
channels.add(channel);
@@ -153,20 +207,45 @@ public class TransportManager {
}
}
+ /**
+ * Removes the channel from the collection of channels. This method is called by the Channel whenever it closes.
+ *
+ * @param channel channel to close
+ * @param x Error to throw
+ */
public static void channelClosed(final AbstractChannel channel, final Throwable x) {
assert channels.contains(channel);
channels.remove(channel);
}
+ /**
+ * Returns an array of all the open channels
+ *
+ * This is internal API, TCF clients should use {@code org.eclipse.tcf.protocol.Protocol}
+ */
public static IChannel[] getOpenChannels() {
return channels.toArray(new IChannel[channels.size()]);
}
+ /**
+ * Add a Channel Open Listener, i.e: a listener that will be notified when a channel is opened
+ *
+ * This is internal API, TCF clients should use {@code org.eclipse.tcf.protocol.Protocol}
+ *
+ * @param listener listener to be added
+ */
public static void addChanelOpenListener(Protocol.ChannelOpenListener listener) {
assert listener != null;
listeners.add(listener);
}
+ /**
+ * Remove a Channel Open Listener, i.e: a listener that will be notified when a channel is opened
+ *
+ * This is internal API, TCF clients should use {@code org.eclipse.tcf.protocol.Protocol}
+ *
+ * @param listener to be removed
+ */
public static void removeChanelOpenListener(Protocol.ChannelOpenListener listener) {
listeners.remove(listener);
}
@@ -176,6 +255,10 @@ public class TransportManager {
* The message is sent to all open communication channels - broadcasted.
*
* This is internal API, TCF clients should use {@code org.eclipse.tcf.protocol.Protocol}.
+ *
+ * @param service_name service name
+ * @param event_name
+ * @param data
*/
public static void sendEvent(String service_name, String event_name, byte[] data) {
for (AbstractChannel c : channels) {
diff --git a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/services/local/LocatorService.java b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/services/local/LocatorService.java
index b5f9e57c8..4e05ff9c5 100644
--- a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/services/local/LocatorService.java
+++ b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/services/local/LocatorService.java
@@ -57,8 +57,17 @@ import org.eclipse.tcf.services.ILocator;
// TODO: research usage of DNS-SD (DNS Service Discovery) to discover TCF peers
public class LocatorService implements ILocator {
+ /**
+ * Default discovery port
+ */
private static final int DISCOVERY_PORT = 1534;
+ /**
+ * Max packet size
+ */
private static final int MAX_PACKET_SIZE = 9000 - 40 - 8;
+ /**
+ * Preferred packet size
+ */
private static final int PREF_PACKET_SIZE = 1500 - 40 - 8;
private static LocatorService locator;
@@ -80,6 +89,9 @@ public class LocatorService implements ILocator {
*/
private static boolean TRACE_DISCOVERY = System.getProperty("org.eclipse.tcf.core.tracing.discovery") != null;
+ /**
+ * Internal Subnetwork Representation
+ */
private static class SubNet {
final int prefix_length;
final InetAddress address;
@@ -94,6 +106,11 @@ public class LocatorService implements ILocator {
this.broadcast = broadcast;
}
+ /**
+ * Check whether the IP Address in part the subnetwork
+ * @param addr IP Address
+ * @return true if the IP Address is contained, otherwise false
+ */
boolean contains(InetAddress addr) {
if (addr == null || address == null) return false;
byte[] a1 = addr.getAddress();
@@ -136,14 +153,16 @@ public class LocatorService implements ILocator {
}
}
+ /** Represents a peer which was discovered, that is a peer whose Locator was not the first Locator in the network.
+ * A master is the peer which discovered a slave, that is a peer whose Locator was the first Locator in the network */
private static class Slave {
final InetAddress address;
final int port;
- /* Time of last packet receiver from this slave */
+ /** Time of last packet receiver from this slave */
long last_packet_time;
- /* Time of last REQ_SLAVES packet received from this slave */
+ /** Time of last REQ_SLAVES packet received from this slave */
long last_req_slaves_time;
Slave(InetAddress address, int port) {
@@ -157,6 +176,12 @@ public class LocatorService implements ILocator {
}
}
+ /**
+ * Represents a hostname/address item that is used when resolving IP addresses from hostnames.
+ * It contains a timestamp of the last time the resolution of hostname -> ip was done.
+ * As well as if it the mapping was used in a DATA_RETENTION_PERIOD
+ *
+ */
private static class AddressCacheItem {
final String host;
InetAddress address;
@@ -168,12 +193,32 @@ public class LocatorService implements ILocator {
}
}
+ /**
+ * Stores Hostname/IP addresses mappings that are used when resolving an IP Address from a hostname
+ */
private static final HashMap<String,AddressCacheItem> addr_cache = new HashMap<String,AddressCacheItem>();
+
+ /**
+ * Used to request an inmediate prune and update of addr_cache mappings
+ */
private static boolean addr_request;
+ /**
+ * Socket used to send/receive the packets to/from remote peers
+ */
private DatagramSocket socket;
+
+ /**
+ * The timestamp of the last received packet from a Locator master.
+ * If there is no remote locator master, meaning that this is the locator master, then the value is 0.
+ */
private long last_master_packet_time;
+ /**
+ * LocatorService's thread for refreshing subnet list of peers, as part of the discovery.
+ * Its run method delegates the refresh of the subnet list of peers to the dispatch thread, using the {@code refresh_timer} method.
+ * Thread's name is: TCF Locator Timer
+ */
private final Thread timer_thread = new Thread() {
public void run() {
while (true) {
@@ -197,6 +242,11 @@ public class LocatorService implements ILocator {
}
};
+ /**
+ * LocatorService's thread for maintaining the hostname/ip mapping held in addr_cache as part of the discovery.
+ * It runs while the <code>getInetAddress(String hostname)</code> is not running, to refresh ip resolution of hostsnames that getInetAddress has already added to addr_cache
+ * Thread's name is: TCF Locator DNS Lookup
+ */
private Thread dns_lookup_thread = new Thread() {
public void run() {
while (true) {
@@ -209,17 +259,26 @@ public class LocatorService implements ILocator {
for (Iterator<AddressCacheItem> i = addr_cache.values().iterator(); i.hasNext();) {
AddressCacheItem a = i.next();
if (a.time_stamp + DATA_RETENTION_PERIOD * 10 < time) {
+ /*
+ * Remove entries that have not been used in between sucessive runs of this method
+ */
if (a.used) {
if (set == null) set = new HashSet<AddressCacheItem>();
set.add(a);
- }
+ }
else {
i.remove();
}
}
}
+ /*
+ * Once we have pruned the addr_cache we wait for the DATA_RETENTION_PERIOD unless the getInetAddress method sets addr_request true
+ */
addr_request = false;
}
+ /*
+ * Update the used AddressCacheItems of addr_cache
+ */
if (set != null) {
for (AddressCacheItem a : set) {
InetAddress addr = null;
@@ -283,6 +342,11 @@ public class LocatorService implements ILocator {
}
}
+ /**
+ * LocatorService's thread for handling packets received from other Peers, as part of the discovery.
+ * Its run method delegates the handling of the packet to the dispatch thread, using the {@code handleDatagramPacket} method.
+ * Thread's name is: TCF Locator Receiver
+ */
private final Thread input_thread = new Thread() {
public void run() {
try {
@@ -317,6 +381,9 @@ public class LocatorService implements ILocator {
static {
ServiceManager.addServiceProvider(new IServiceProvider() {
+ /*
+ * LocatorService's ServiceProvider only implements getLocalService, as this service is implemented locally and not remotely
+ */
public IService[] getLocalService(final IChannel channel) {
channel.addCommandServer(locator, new IChannel.ICommandServer() {
public void command(IToken token, String name, byte[] data) {
@@ -343,6 +410,12 @@ public class LocatorService implements ILocator {
}
}
+ /**
+ * Creates a socket which will behave either as a slave locator or master locator, depending on the given slave parameter
+ * @param slave true if the socket is representing a slave locator, false otherwise
+ * @return the newly created socket
+ * @throws SocketException thrown when the socket could not be created on the discovery port (couldn't be a master locator)
+ */
private static DatagramSocket createSocket(boolean slave) throws SocketException {
DatagramSocket socket = null;
if (slave) {
@@ -357,11 +430,19 @@ public class LocatorService implements ILocator {
return socket;
}
+ /**
+ * Creates a local instance of the LocatorService which involves creating:
+ * 1. LocalPeer
+ * 2. LocatorService itself
+ */
public static void createLocalInstance() {
local_peer = new LocalPeer();
locator = new LocatorService();
}
+ /**
+ * LocatorService constructor used in {@code createLocalInstace}
+ */
public LocatorService() {
try {
loopback_addr = InetAddress.getByName(null);
@@ -383,6 +464,7 @@ public class LocatorService implements ILocator {
socket = createSocket(true);
if (TRACE_DISCOVERY) {
LoggingUtil.trace("Became a slave agent (bound to port " + socket.getLocalPort() + ")");
+
}
}
input_thread.setName("TCF Locator Receiver");
@@ -391,6 +473,9 @@ public class LocatorService implements ILocator {
input_thread.setDaemon(true);
timer_thread.setDaemon(true);
dns_lookup_thread.setDaemon(true);
+ /*
+ * All the locator thread's are run in the dispatch thread
+ */
Protocol.invokeLater(new Runnable() {
@Override
public void run() {
@@ -421,14 +506,28 @@ public class LocatorService implements ILocator {
}
}
+ /**
+ * Get the LocalPeer instance
+ * @return LocalPeer instance
+ */
public static LocalPeer getLocalPeer() {
return local_peer;
}
+ /**
+ * Get the Locator Event listeners
+ * @return array of locator listeners
+ */
public static LocatorListener[] getListeners() {
return listeners.toArray(new LocatorListener[listeners.size()]);
}
+ /**
+ * Creates an error report using the given TCF error code, and msg parameters
+ * @param code the error code, from the Standard TCF error codes
+ * @param msg an error message
+ * @return return a map representation of the error report
+ */
private Map<String,Object> makeErrorReport(int code, String msg) {
Map<String,Object> err = new HashMap<String,Object>();
err.put(IErrorReport.ERROR_TIME, Long.valueOf(System.currentTimeMillis()));
@@ -437,8 +536,19 @@ public class LocatorService implements ILocator {
return err;
}
+ /**
+ * Handles all command messages received through the channel
+ *
+ * @param channel the channel through which the commands are received/sent
+ * @param token handle associated with the command
+ * @param name command name
+ * @param data command arguments in byte array format
+ */
private void command(final AbstractChannel channel, final IToken token, String name, byte[] data) {
try {
+ /*
+ * Redirect command
+ */
if (name.equals("redirect")) {
String peer_id = (String)JSON.parseSequence(data)[0];
IPeer peer = peers.get(peer_id);
@@ -455,15 +565,24 @@ public class LocatorService implements ILocator {
}
new ChannelProxy(channel, peer.openChannel());
}
+ /*
+ * Sync command
+ */
else if (name.equals("sync")) {
channel.sendResult(token, null);
}
+ /*
+ * getPeers command
+ */
else if (name.equals("getPeers")) {
int i = 0;
Object[] arr = new Object[peers.size()];
for (IPeer p : peers.values()) arr[i++] = p.getAttributes();
channel.sendResult(token, JSON.toJSONSequence(new Object[]{ null, arr }));
}
+ /*
+ * Unrecognized command
+ */
else {
channel.rejectCommand(token);
}
@@ -473,6 +592,11 @@ public class LocatorService implements ILocator {
}
}
+ /**
+ * Logs the given message and Exception/Error
+ * @param msg message to be logged
+ * @param x exception or error to be logged
+ */
private void log(String msg, Throwable x) {
// Don't report same error multiple times to avoid filling up the log file.
synchronized (error_log) {
@@ -482,6 +606,16 @@ public class LocatorService implements ILocator {
Protocol.log(msg, x);
}
+ /**
+ * Gets the IP Address from a Hostname.
+ * To do that it uses the addr_cache, to search for an entry with the given host.
+ * If there's such an entry, it returns the address.
+ * If there isn't such an entry it constructs an AddressCacheItem entry and adds it to the addr_cache.
+ * Marks the given AddressCacheItem's used field as true.
+ *
+ * @param host Host in Hostname format
+ * @return IP Address of the Host
+ */
private InetAddress getInetAddress(String host) {
if (host == null || host.length() == 0) return null;
synchronized (addr_cache) {
@@ -509,6 +643,10 @@ public class LocatorService implements ILocator {
}
}
+ /**
+ * Refreshes the Subnetworks lists for slaves
+ * @param nets Subnetwork lists
+ */
private void refresh_timer(HashSet<SubNet> nets) {
long time = System.currentTimeMillis();
/* Cleanup slave table */
@@ -516,6 +654,7 @@ public class LocatorService implements ILocator {
int i = 0;
while (i < slaves.size()) {
Slave s = slaves.get(i);
+ /* Removes slave if there is no recent packet receveid from it */
if (s.last_packet_time + DATA_RETENTION_PERIOD < time) {
slaves.remove(i);
}
@@ -560,7 +699,17 @@ public class LocatorService implements ILocator {
sendAll(null, 0, null, time);
}
+ /**
+ * Add a slaves with the given Address, port number and timestamp to the array of slaves, and return it
+ * @param addr IP Address of the slave
+ * @param port Port of the slave
+ * @param timestamp timestamp at which the last packet was received
+ * @return the slave which was created using the given parameters
+ */
private Slave addSlave(InetAddress addr, int port, long timestamp) {
+ /*
+ * Check if there's an slave already in the list of known slaves, and if there is refresh the timestamp of the last packet received and return it
+ */
for (Slave s : slaves) {
if (s.port == port && s.address.equals(addr)) {
if (s.last_packet_time < timestamp) s.last_packet_time = timestamp;
@@ -570,6 +719,9 @@ public class LocatorService implements ILocator {
final Slave s = new Slave(addr, port);
s.last_packet_time = timestamp;
slaves.add(s);
+ /*
+ * Crea
+ */
Protocol.invokeLater(new Runnable() {
public void run() {
long time_now = System.currentTimeMillis();
@@ -605,6 +757,10 @@ public class LocatorService implements ILocator {
return new_nets;
}
+ /**
+ * Finds all subnetworks, adds them to the {@code subnet} set and returns it.
+ * @return set of SubNets
+ */
private HashSet<SubNet> getSubNetList() {
HashSet<SubNet> set = new HashSet<SubNet>();
try {
@@ -631,6 +787,11 @@ public class LocatorService implements ILocator {
return set;
}
+ /**
+ * Find and adds all subnets to the given set
+ * @param set set of subnetworks
+ * @throws SocketException
+ */
private void getSubNetList(HashSet<SubNet> set) throws SocketException {
for (Enumeration<NetworkInterface> e = NetworkInterface.getNetworkInterfaces(); e.hasMoreElements();) {
NetworkInterface f = e.nextElement();
@@ -658,6 +819,11 @@ public class LocatorService implements ILocator {
}
}
+ /**
+ * Finds and adds Subnetworks to the
+ * @param set
+ * @throws Exception
+ */
private void getWindowsSubNetList(HashSet<SubNet> set) throws Exception {
HashMap<String,InetAddress> map = new HashMap<String,InetAddress>();
for (Enumeration<NetworkInterface> e = NetworkInterface.getNetworkInterfaces(); e.hasMoreElements();) {
@@ -760,6 +926,14 @@ public class LocatorService implements ILocator {
"CONF_PEER_REMOVE"
};
+ /**
+ * Sends a Datagram packet of the given length to the Peer in the given subnet, with the given address and port
+ * @param subnet the subnet on which the the peer address is located
+ * @param size the datagram packet size
+ * @param addr the peer's IP address
+ * @param port the destination port number
+ * @return true if the datagram was sent, false is the datagram was not sent
+ */
private boolean sendDatagramPacket(SubNet subnet, int size, InetAddress addr, int port) {
try {
if (addr == null) {
@@ -845,6 +1019,11 @@ public class LocatorService implements ILocator {
return map;
}
+ /**
+ * Sends a Peer Request to the given Address and Port on all subnets
+ * @param addr IP Address of the Peer
+ * @param port Port number of the Peer
+ */
private void sendPeersRequest(InetAddress addr, int port) {
out_buf[4] = CONF_REQ_INFO;
for (SubNet subnet : subnets) {
@@ -852,6 +1031,12 @@ public class LocatorService implements ILocator {
}
}
+ /**
+ *
+ * @param peer
+ * @param addr
+ * @param port
+ */
private void sendPeerInfo(IPeer peer, InetAddress addr, int port) {
Map<String,String> attrs = peer.getAttributes();
InetAddress peer_addr = getInetAddress(attrs.get(IPeer.ATTR_IP_HOST));
@@ -885,6 +1070,11 @@ public class LocatorService implements ILocator {
}
}
+ /**
+ * Sends a CONF_SLAVES_INFO empty packet to the given address/port
+ * @param addr IP address of the peer
+ * @param port port number of the peer
+ */
private void sendEmptyPacket(InetAddress addr, int port) {
out_buf[4] = CONF_SLAVES_INFO;
for (SubNet subnet : subnets) {
@@ -893,6 +1083,13 @@ public class LocatorService implements ILocator {
}
}
+ /**
+ * Sends a packet to
+ * @param addr IP address of the slave/peer
+ * @param port port number of the slave/peer
+ * @param sl slave to which the packet is going to be sent to
+ * @param time
+ */
private void sendAll(InetAddress addr, int port, Slave sl, long time) {
for (SubNet subnet : subnets) subnet.send_all_ok = false;
for (IPeer peer : peers.values()) sendPeerInfo(peer, addr, port);
@@ -902,11 +1099,22 @@ public class LocatorService implements ILocator {
sendEmptyPacket(addr, port);
}
+ /**
+ * Sends a CONF_REQ_SLAVES packet to the given address and port number in the given subnet
+ * @param subnet subnet in which the address belongs to
+ * @param addr IP address of the slave
+ * @param port port number of the slave
+ */
private void sendSlavesRequest(SubNet subnet, InetAddress addr, int port) {
out_buf[4] = CONF_REQ_SLAVES;
sendDatagramPacket(subnet, 8, addr, port);
}
+ /**
+ * Sends a CONF_SLAVES_INFO packet to the given slave with the given timestamp
+ * @param x slave
+ * @param time
+ */
private void sendSlaveInfo(Slave x, long time) {
int ttl = (int)(x.last_packet_time + DATA_RETENTION_PERIOD - time);
if (ttl <= 0) return;
@@ -927,6 +1135,12 @@ public class LocatorService implements ILocator {
}
}
+ /**
+ * Sends a CONF_SLAVES_INFO packet to the given address, port number with the given timestamp
+ * @param addr IP Address of slave
+ * @param port Port number of slave
+ * @param time timestamp of
+ */
private void sendSlavesInfo(InetAddress addr, int port, long time) {
out_buf[4] = CONF_SLAVES_INFO;
for (SubNet subnet : subnets) {
@@ -954,6 +1168,12 @@ public class LocatorService implements ILocator {
}
}
+ /**
+ * Checks if the the address and port are from a RemotePeer
+ * @param address IP address of peer
+ * @param port port number of peer
+ * @return true is the address and port are not from a Remote Peer but instead is the Local Peer, else false
+ */
private boolean isRemote(InetAddress address, int port) {
if (port != socket.getLocalPort()) return true;
for (SubNet s : subnets) {
@@ -962,6 +1182,13 @@ public class LocatorService implements ILocator {
return true;
}
+ /**
+ * Handles packets received during the auto discovery.
+ * It verifies the packet is indeed a TCF packet, and handles it depending on the auto-configuration command and responses codes e.g: CONF_PEER_INFO,
+ * CONF_REQ_INFO, etc..
+ *
+ * @param p packet received
+ */
private void handleDatagramPacket(InputPacket p) {
try {
long time = System.currentTimeMillis();
@@ -1018,6 +1245,10 @@ public class LocatorService implements ILocator {
}
}
+ /**
+ * Handles a received CONF_PEER_INFO packet
+ * @param p packet received
+ */
private void handlePeerInfoPacket(InputPacket p) {
try {
Map<String,String> map = parsePeerAtrributes(p.getData(), p.getLength());
@@ -1053,11 +1284,23 @@ public class LocatorService implements ILocator {
}
}
+ /**
+ * Handles a CONF_REQ_INFO packet received from the given slave, at the given time
+ * It sendsAll
+ * @param p packet received
+ * @param sl slave
+ * @param time timestamp at which the packet was received
+ */
private void handleReqInfoPacket(InputPacket p, Slave sl, long time) {
if (TRACE_DISCOVERY) traceDiscoveryPacket(true, "CONF_REQ_INFO", null, p);
sendAll(p.getAddress(), p.getPort(), sl, time);
}
+ /**
+ * Handles a received CONF_SLAVES_INFO
+ * @param p packet received
+ * @param time_now timestamp when the packet was received
+ */
private void handleSlavesInfoPacket(InputPacket p, long time_now) {
try {
Map<String,String> map = parseIDs(p.getData(), p.getLength());
@@ -1115,12 +1358,24 @@ public class LocatorService implements ILocator {
}
}
+ /**
+ * Handles CONF_REQ_SLAVES packet
+ * SendsSlavesInfo
+ * @param p packet received
+ * @param sl slave from which the packet was received
+ * @param time timestamp of when the packet was received
+ */
private void handleReqSlavesPacket(InputPacket p, Slave sl, long time) {
if (TRACE_DISCOVERY) traceDiscoveryPacket(true, "CONF_REQ_SLAVES", null, p);
if (sl != null) sl.last_req_slaves_time = time;
sendSlavesInfo(p.getAddress(), p.getPort(), time);
}
+ /**
+ * Handles a received CONF_PEER_REMOVED packet
+ * @param p packet received
+ * @param master_exited true if the master locator was removed, false if it was a slave locator
+ */
private void handlePeerRemovedPacket(InputPacket p, boolean master_exited) {
try {
Map<String,String> map = parseIDs(p.getData(), p.getLength());
@@ -1200,17 +1455,11 @@ public class LocatorService implements ILocator {
* sent to stdout. This should be called only if the tracing has been turned
* on via java property definitions.
*
- * @param received
- * true if the packet was sent, otherwise it was received
- * @param type
- * a string specifying the type of packet, e.g., "CONF_PEER_INFO"
- * @param attrs
- * a set of attributes relevant to the type of packet (typically
- * a peer's attributes)
- * @param addr
- * the network address the packet is being sent to
- * @param port
- * the port the packet is being sent to
+ * @param received false if the packet was sent, otherwise it was received
+ * @param type a string specifying the type of packet, e.g., "CONF_PEER_INFO"
+ * @param attrs a set of attributes relevant to the type of packet (typically a peer's attributes)
+ * @param addr the network address the packet is being sent to
+ * @param port the port the packet is being sent to
*/
private static void traceDiscoveryPacket(boolean received, String type, Map<String,String> attrs, InetAddress addr, int port) {
assert TRACE_DISCOVERY;
@@ -1228,6 +1477,11 @@ public class LocatorService implements ILocator {
/**
* Convenience variant that takes a DatagramPacket for specifying
* the target address and port.
+ *
+ * @param received false if the packet was sent, otherwise it was received
+ * @param type a string specifying the type of packet, e.g., "CONF_PEER_INFO"
+ * @param attrs a set of attributes relevant to the type of packet (typically a peer's attributes)
+ * @param packet packet received
*/
private static void traceDiscoveryPacket(boolean received, String type, Map<String,String> attrs, InputPacket packet) {
traceDiscoveryPacket(received, type, attrs, packet.getAddress(), packet.getPort());
diff --git a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/protocol/IServiceProvider.java b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/protocol/IServiceProvider.java
index 6b4ced40f..6b3ee9330 100644
--- a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/protocol/IServiceProvider.java
+++ b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/protocol/IServiceProvider.java
@@ -16,7 +16,18 @@ package org.eclipse.tcf.protocol;
*/
public interface IServiceProvider {
+ /**
+ * Get the local services available in the given channel
+ * @param channel channel
+ * @return an array of services
+ */
public IService[] getLocalService(IChannel channel);
+ /**
+ * Get the service o in the given channel for the given service name
+ * @param channel
+ * @param service_name
+ * @return the service
+ */
public IService getServiceProxy(IChannel channel, String service_name);
}
diff --git a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/protocol/Protocol.java b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/protocol/Protocol.java
index 1bad1daba..5dd466aff 100644
--- a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/protocol/Protocol.java
+++ b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/protocol/Protocol.java
@@ -36,12 +36,31 @@ import org.eclipse.tcf.services.ILocator;
*/
public final class Protocol {
+ /**
+ * Event queue instance that holds all the Runnables to be run in the dispatch thread
+ */
private static IEventQueue event_queue;
+ /**
+ * Main Logger instance used by the TCF Framework
+ */
private static ILogger logger;
+ /**
+ * Set that holds the Timer objects for dispatch by the timer_dispatcher thread
+ */
private static final TreeSet<Timer> timer_queue = new TreeSet<Timer>();
+ /**
+ * Agent ID constant generated pseudorandomly by UUID
+ */
private static final String agent_id = UUID.randomUUID().toString();
+ /**
+ * Static variable that is incremented for every new Timer object added to the timer_queue, and whose value is used as ID of the Timer object,
+ * for resolving a time in the timestamps of different Timer objects
+ */
private static int timer_cnt;
+ /**
+ * Class used for by the timer_dispatcher thread, that binds a Timestamp and a Runnable, and that enables the ordering of objects, according the Time
+ */
private static class Timer implements Comparable<Timer> {
final int id;
final long time;
@@ -75,6 +94,10 @@ public final class Protocol {
}
}
+ /**
+ * Thread used for dispatching Runnables which must wait for a certain delay to be dispatched in the dispatch thread.
+ * @see #invokeLater(long delay, Runnable runnable)
+ */
private static final Thread timer_dispatcher = new Thread() {
public void run() {
try {
@@ -174,7 +197,7 @@ public final class Protocol {
/**
* Causes <code>runnable</code> event to have its <code>run</code>
* method called in the dispatch thread of the framework.
- * The event is dispatched after given delay.
+ * The event is dispatched after the given delay.
*
* This method can be invoked from any thread.
*
diff --git a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/services/ILocator.java b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/services/ILocator.java
index 4d9a0466f..fd68c2152 100644
--- a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/services/ILocator.java
+++ b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/services/ILocator.java
@@ -122,6 +122,9 @@ public interface ILocator extends IService {
*/
void removeListener(LocatorListener listener);
+ /**
+ * ILocator service event listener interface
+ */
interface LocatorListener {
/**
* A new peer is added into locator peer table.
diff --git a/plugins/org.eclipse.tcf/src/org/eclipse/tcf/Activator.java b/plugins/org.eclipse.tcf/src/org/eclipse/tcf/Activator.java
index 7d4c26136..84d959e9b 100644
--- a/plugins/org.eclipse.tcf/src/org/eclipse/tcf/Activator.java
+++ b/plugins/org.eclipse.tcf/src/org/eclipse/tcf/Activator.java
@@ -133,6 +133,9 @@ public class Activator extends Plugin {
}
}
});
+ /*
+ * Starts the timer_queue and sets the event_queue
+ */
Protocol.setEventQueue(queue);
Protocol.invokeLater(new Runnable() {
public void run() {

Back to the top