/soc/2012/michael/android: 52d1f95ae851: Fixed typo in NodeIter(...
Michael Zangl
michael at soc.pidgin.im
Mon Aug 20 10:15:52 EDT 2012
Changeset: 52d1f95ae851d86ac9cc53bc090b3ad04d71fce6
Author: Michael Zangl <michael at soc.pidgin.im>
Date: 2012-08-20 15:05 +0200
Branch: soc.2012.android
URL: http://hg.pidgin.im/soc/2012/michael/android/rev/52d1f95ae851
Description:
Fixed typo in NodeIter(r)ator class, added documentation to buddy classes
diffstat:
android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/NodeIterator.java | 42 +++++
android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/NodeIterrator.java | 33 ----
android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlist.java | 24 +++
android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistGroup.java | 19 ++
android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistListener.java | 30 +++
android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistManager.java | 78 +++++++--
android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistNode.java | 72 +++++++-
android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleContact.java | 15 +
8 files changed, 252 insertions(+), 61 deletions(-)
diffs (truncated from 542 to 300 lines):
diff --git a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/NodeIterator.java b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/NodeIterator.java
new file mode 100644
--- /dev/null
+++ b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/NodeIterator.java
@@ -0,0 +1,42 @@
+package im.pidgin.libpurple.blist;
+
+import java.util.Iterator;
+
+/**
+ * This is a node iterator that iterates over the children of a node.
+ * @author michael
+ *
+ */
+public class NodeIterator implements Iterator<PurpleBlistNode> {
+
+ private PurpleBlistNode next;
+
+ /**
+ * Creates a new {@link NodeIterator} that iterates over all children of the given node.
+ * @param blistNode The node.
+ */
+ public NodeIterator(PurpleBlistNode blistNode) {
+ next = blistNode.getFirstChild();
+ }
+
+ @Override
+ public boolean hasNext() {
+ return next != null;
+ }
+
+ @Override
+ public PurpleBlistNode next() {
+ if (next == null) {
+ throw new IllegalStateException();
+ }
+ PurpleBlistNode result = next;
+ next = next.getNextSibling();
+ return result;
+ }
+
+ @Override
+ public void remove() {
+ throw new UnsupportedOperationException();
+ }
+
+}
diff --git a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/NodeIterrator.java b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/NodeIterrator.java
deleted file mode 100644
--- a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/NodeIterrator.java
+++ /dev/null
@@ -1,33 +0,0 @@
-package im.pidgin.libpurple.blist;
-
-import java.util.Iterator;
-
-public class NodeIterrator implements Iterator<PurpleBlistNode> {
-
- private PurpleBlistNode next;
-
- public NodeIterrator(PurpleBlistNode blistNode) {
- next = blistNode.getFirstChild();
- }
-
- @Override
- public boolean hasNext() {
- return next != null;
- }
-
- @Override
- public PurpleBlistNode next() {
- if (next == null) {
- throw new IllegalStateException();
- }
- PurpleBlistNode result = next;
- next = next.getNextSibling();
- return result;
- }
-
- @Override
- public void remove() {
- throw new UnsupportedOperationException();
- }
-
-}
diff --git a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlist.java b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlist.java
--- a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlist.java
+++ b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlist.java
@@ -1,11 +1,35 @@
package im.pidgin.libpurple.blist;
+/**
+ * This is the main entry point to the buddy list libpurple provides.
+ *
+ * @author michael
+ */
public interface PurpleBlist {
+ /**
+ * Gets the root node of the buddy list. The root node is normally a group
+ * and it may have some siblings.
+ *
+ * @return The root node.
+ */
PurpleBlistNode getRoot();
+ /**
+ * Adds a listener that listens to buddy list events.
+ *
+ * @param l
+ * The listener to add.
+ */
void addBlistListener(PurpleBlistListener l);
+ /**
+ * Removes a previously added listener from the buddy list, or does nothing
+ * if the listener was not added.
+ *
+ * @param l
+ * The listener to remove.
+ */
void removeBlistListener(PurpleBlistListener l);
}
\ No newline at end of file
diff --git a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistGroup.java b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistGroup.java
--- a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistGroup.java
+++ b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistGroup.java
@@ -3,12 +3,31 @@ package im.pidgin.libpurple.blist;
import im.pidgin.libpurple.buddy.PurpleBuddy;
import im.pidgin.libpurple.core.CoreManager;
+/**
+ * This is a group of contacts in the buddy list.
+ *
+ * @author michael
+ */
public class PurpleBlistGroup extends PurpleBlistNode {
+ /**
+ * Creates a new group.
+ *
+ * @param nativePointer
+ * The native pointer
+ * @param manager
+ * The manager to use.
+ * @see PurpleBlistManager#getGroupPeer(long)
+ */
protected PurpleBlistGroup(long nativePointer, CoreManager manager) {
super(nativePointer, manager);
}
+ /**
+ * Gets the name of the buddy list group.
+ *
+ * @return The name.
+ */
public String getName() {
return getName_native();
}
diff --git a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistListener.java b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistListener.java
--- a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistListener.java
+++ b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistListener.java
@@ -2,12 +2,42 @@ package im.pidgin.libpurple.blist;
import im.pidgin.libpurple.buddy.PurpleBuddy;
+/**
+ * Listeners that listen to the buddy list need to implement this interface.
+ * @author michael
+ *
+ */
public interface PurpleBlistListener {
+ /**
+ * Called when any node was added, also when a buddy was added.
+ * @param node The node that was added
+ */
void nodeAdded(PurpleBlistNode node);
+ /**
+ * Called when any node was removed, also when a buddy was added.
+ * @param node The node that was removed.
+ */
void nodeRemoved(PurpleBlistNode node);
+
+ /**
+ * Called when a buddy was added to the buddy list.
+ * @param node The buddy that was added.
+ * @see PurpleBlistListener#nodeAdded(PurpleBlistNode)
+ */
void buddyAdded(PurpleBuddy node);
+
+ /**
+ * Called when a buddy was removed from the buddy list.
+ * @param node The buddy that was removed.
+ * @see PurpleBlistListener#nodeRemoved(PurpleBlistNode)
+ */
void buddyRemoved(PurpleBuddy node);
+
+ /**
+ * Called when the alias for a node was changed.
+ * @param node The node who's alias was changed.
+ */
void nodeAliasChanged(PurpleBlistNode node);
}
diff --git a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistManager.java b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistManager.java
--- a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistManager.java
+++ b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistManager.java
@@ -13,19 +13,26 @@ import java.util.LinkedList;
* need to have a node cache here.
*
* @author michaelz
- *
*/
public class PurpleBlistManager extends AbstractPurpleManaged implements
- PeerGenerator<PurpleBlistNode>, PurpleBlist {
+ PeerGenerator<PurpleBlistNode>, PurpleBlist {
public PurpleBlistManager(CoreManager coreManager) {
super(coreManager);
}
- private final LinkedList<PurpleBlistListener> blistListeners = new LinkedList<PurpleBlistListener>();
+ /**
+ * This is a list of listeners that listen to structural buddy list changes.
+ */
+ private final LinkedList<PurpleBlistListener> blistListeners =
+ new LinkedList<PurpleBlistListener>();
+ /**
+ * This is the mutex used for synchronizing buddy list listener access.
+ */
private final Object blistMutex = new Object();
- /* (non-Javadoc)
+ /*
+ * (non-Javadoc)
* @see im.pidgin.libpurple.blist.PurpleBlist#getRoot()
*/
@Override
@@ -35,6 +42,10 @@ public class PurpleBlistManager extends
private native long getRoot_native();
+ /**
+ * Registers the native part of this manager. To be called on libpurple
+ * start.
+ */
public void register() {
register_native();
}
@@ -59,6 +70,15 @@ public class PurpleBlistManager extends
return object.getNativePointer();
}
+ /**
+ * Gets the java object for a native buddy pointer.
+ *
+ * @param pointer
+ * The pointer
+ * @return The buddy object
+ * @throws IllegalArgumentException
+ * If the pointer is not a buddy node.
+ */
public PurpleBuddy getBuddyPeer(long pointer) {
PurpleBlistNode peer = getPeer(pointer);
if (peer instanceof PurpleBuddy) {
@@ -68,6 +88,15 @@ public class PurpleBlistManager extends
}
}
+ /**
+ * Gets the java object for a native group pointer.
+ *
+ * @param pointer
+ * The pointer
+ * @return The buddy object
+ * @throws IllegalArgumentException
+ * If the pointer is not a group node.
+ */
public PurpleBlistGroup getGroupPeer(long pointer) {
PurpleBlistNode peer = getPeer(pointer);
if (peer instanceof PurpleBlistGroup) {
@@ -77,19 +106,30 @@ public class PurpleBlistManager extends
}
}
+ /**
+ * Gets the java object for a native contact pointer.
+ *
+ * @param pointer
+ * The pointer
+ * @return The contact object
+ * @throws IllegalArgumentException
+ * If the pointer is not a contact node.
+ */
public PurpleContact getContactPeer(long pointer) {
PurpleBlistNode peer = getPeer(pointer);
if (peer instanceof PurpleContact) {
return (PurpleContact) peer;
More information about the Commits
mailing list