pidgin/android/android

Commented the core classes
soc.2012.android tip
2012-08-20, Michael Zangl
e0ee0749df86
Parents 435f55eca061
Children
Commented the core classes
--- a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/AbstractPurpleManaged.java Mon Aug 20 16:02:15 2012 +0200
+++ b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/AbstractPurpleManaged.java Mon Aug 20 16:14:06 2012 +0200
@@ -1,21 +1,25 @@
package im.pidgin.libpurple.core;
/**
- *
* Objects that use this class belong to a purple instance, which is referenced
* by the main manager.
- *
+ *
* @author michaelz
- *
*/
-public class AbstractPurpleManaged implements PurpleManaged {
-
+public class AbstractPurpleManaged {
+
private final CoreManager manager;
+ /**
+ * Creates a new object that is managed by libpurple.
+ *
+ * @param manager
+ * The manager to use.
+ */
public AbstractPurpleManaged(CoreManager manager) {
this.manager = manager;
}
-
+
protected CoreManager getManager() {
return manager;
}
--- a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/CoreManager.java Mon Aug 20 16:02:15 2012 +0200
+++ b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/CoreManager.java Mon Aug 20 16:14:06 2012 +0200
@@ -16,32 +16,50 @@
* This is the core purple manager, that provides access to all functionality.
* <p>
* It also implements the core UI ops.
- *
- * @author michaelz
- *
+ *
+ * @author michael
*/
public class CoreManager {
+ /**
+ * The purple account list.
+ */
private final PurpleAccountManager accountList = new PurpleAccountManager(
- this);
+ this);
+ /**
+ * The purple event loop.
+ */
private final EventLoop eventloop = new EventLoop(this);
+ /**
+ * The thread to run all purple tasks on.
+ */
private final PurpleThread purpleThread = new PurpleThread();
- private final PurplePluginList pluginManager = new PurplePluginManager(this);
+ /**
+ * The plugin manager we are using.
+ */
+ private final PurplePluginList pluginManager =
+ new PurplePluginManager(this);
+ /**
+ * The blist manager we use.
+ */
private final PurpleBlistManager blist = new PurpleBlistManager(this);
- private final ConversationManager conversationManager = new ConversationManager(
- this);
+ /**
+ * The conversation manager we use.
+ */
+ private final ConversationManager conversationManager =
+ new ConversationManager(this);
/**
* Initializes libpurple by setting all the ui ops and calling
* purple_core_init().
- *
+ *
* @param uiName
* The name of the UI.
- * @param baseDirectory
+ * @param baseDirectory
*/
public boolean startCore(String uiName, File baseDirectory) {
eventloop.register();
@@ -50,6 +68,11 @@
private native boolean startCore_native(String uiName, String baseDirectory);
+ /**
+ * Gets the event loop to use.
+ *
+ * @return The loop.
+ */
public EventLoop getEventloop() {
return eventloop;
}
@@ -68,22 +91,42 @@
new RequestUiOps().register();
}
+ /**
+ * Gets the thread to run all purple tasks on.
+ * @return The thread.
+ */
public PurpleThread getThread() {
return purpleThread;
}
+ /**
+ * Gets the account list manager.
+ * @return The account list.
+ */
public PurpleAccountManager getAccountList() {
return accountList;
}
+ /**
+ * Gets the plugin manager.
+ * @return The plugin manager.
+ */
public PurplePluginList getPluginManager() {
return pluginManager;
}
+ /**
+ * Gets the blist manager.
+ * @return The blist manager.
+ */
public PurpleBlistManager getBlist() {
return blist;
}
-
+
+ /**
+ * Gets the conversation manager.
+ * @return The conversation manager.
+ */
public ConversationManager getConversationManager() {
return conversationManager;
}
--- a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/EventLoop.java Mon Aug 20 16:02:15 2012 +0200
+++ b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/EventLoop.java Mon Aug 20 16:14:06 2012 +0200
@@ -9,17 +9,26 @@
/**
* This is the eventloop implementation that is used to schedule libpruple
* events on the purple thread.
- *
+ *
* @author michaelz
- *
*/
public class EventLoop extends AbstractPurpleManaged {
- Timer eventTimer = new Timer("Event queue timer");
+ /**
+ * The main event timer
+ */
+ private final Timer eventTimer = new Timer("Event queue timer");
private final Object scheduledTimersMutex = new Object();
- private final Hashtable<Integer, EventloopTask> scheduledTimers = new Hashtable<Integer, EventloopTask>();
+ /**
+ * A list of tasks that are currently scheduled and might be aborted.
+ */
+ private final Hashtable<Integer, EventloopTask> scheduledTimers =
+ new Hashtable<Integer, EventloopTask>();
+ /**
+ * A steadily increasing counter to create unique timeout ids.
+ */
private int timeoutCounter = 0;
public EventLoop(CoreManager manager) {
@@ -47,16 +56,12 @@
/**
* Should create a callback timer with an interval measured in milliseconds.
- *
* The supplied function should be called every interval seconds until it
- * returns FALSE, after which it should not be called again.
- *
- * Analogous to g_timeout_add in glib.
- *
- * Note: On Win32, this function may be called from a thread other than the
- * libpurple thread. You should make sure to detect this situation and to
- * only call "function" from the libpurple thread.
- *
+ * returns FALSE, after which it should not be called again. Analogous to
+ * g_timeout_add in glib. Note: On Win32, this function may be called from a
+ * thread other than the libpurple thread. You should make sure to detect
+ * this situation and to only call "function" from the libpurple thread.
+ *
* @param interval
* the interval in milliseconds between calls to function.
* @param function
@@ -71,10 +76,10 @@
key = timeoutCounter;
System.out.println("Adding eventloop task " + key
- + " to be scheduled every " + interval + " milliseconds.");
- EventloopTask task = new EventloopTask(
- new EventloopFunctionExecutor(key, function, data),
- getManager().getThread());
+ + " to be scheduled every " + interval + " milliseconds.");
+ EventloopTask task =
+ new EventloopTask(new EventloopFunctionExecutor(key,
+ function, data), getManager().getThread());
if (interval <= 0) {
interval = 1;
}
@@ -87,7 +92,6 @@
}
/**
- *
* @param handle
* an identifier for a timeout, as returned by timeout_add.
* @return TRUE if the timeout identified by handle was found and removed.
@@ -109,9 +113,8 @@
/**
* This is a {@link WaitableRunnable} that executes the given function.
- *
+ *
* @author michaelz
- *
*/
private class EventloopFunctionExecutor extends AbstractWaitableRunnable {
private final long function;
@@ -147,10 +150,13 @@
private native boolean exeucte_native(long function, long data);
+ /* UI ops callbacks and runners */
+
public void ioInvoke(long function, long data, int fd, int cond) {
- getManager().getThread().scheduleAndWaitForUninterruptable(new IoInvokeRunner(function, data, fd, cond));
+ getManager().getThread().scheduleAndWaitForUninterruptable(
+ new IoInvokeRunner(function, data, fd, cond));
}
-
+
private static class IoInvokeRunner extends AbstractWaitableRunnable {
private final long function;
private final long data;
@@ -169,8 +175,8 @@
ioInvoke_native(function, data, fd, cond);
}
- private native void ioInvoke_native(long function2, long data2, int fd2,
- int cond2);
-
+ private native void ioInvoke_native(long function2, long data2,
+ int fd2, int cond2);
+
}
}
--- a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/EventloopTask.java Mon Aug 20 16:02:15 2012 +0200
+++ b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/EventloopTask.java Mon Aug 20 16:14:06 2012 +0200
@@ -7,13 +7,18 @@
/**
* This is a special task for the eventloop.
- *
+ *
* @author michaelz
- *
*/
public class EventloopTask extends TimerTask {
+ /**
+ * The runnable we need to run.
+ */
private final WaitableRunnable runnable;
+ /**
+ * The thread we need to run it on.
+ */
private final PurpleThread thread;
public EventloopTask(WaitableRunnable runnable, PurpleThread thread) {
@@ -32,7 +37,7 @@
* interrupted.
*/
System.err.println("Unexpected interupt exception"
- + " during an EventloopTask executioon.");
+ + " during an EventloopTask executioon.");
}
}
--- a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/PeeredPurpleManaged.java Mon Aug 20 16:02:15 2012 +0200
+++ b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/PeeredPurpleManaged.java Mon Aug 20 16:14:06 2012 +0200
@@ -3,22 +3,25 @@
import im.pidgin.libpurple.peering.Peered;
/**
- *
* Objects that use this class belong to a purple instance, which is referenced
* by the main manager.
- *
+ *
* @author michaelz
- *
*/
-public class PeeredPurpleManaged extends Peered implements PurpleManaged {
-
+public class PeeredPurpleManaged extends Peered {
+
private final CoreManager manager;
public PeeredPurpleManaged(long nativePointer, CoreManager manager) {
super(nativePointer);
this.manager = manager;
}
-
+
+ /**
+ * Gets the manager that is used to construct this object.
+ *
+ * @return The core manager.
+ */
protected CoreManager getManager() {
return manager;
}
--- a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/PurpleInstance.java Mon Aug 20 16:02:15 2012 +0200
+++ b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/PurpleInstance.java Mon Aug 20 16:14:06 2012 +0200
@@ -14,18 +14,18 @@
* libpurple instance.
* <p>
* There can only be one instance per process.
- *
+ *
* @author michaelz
- *
*/
public class PurpleInstance {
private static Object instanceActiveMutex = new Object();
private static boolean instanceActive = false;
-
+
private final CoreManager coreManager = new CoreManager();
/**
* Creates a new instance and loads libpurple. This might take some time.
+ *
* @param uiName
* @param baseDirectory
*/
@@ -33,7 +33,7 @@
PurpleLibraryLoader.load();
setDebugEnabled(true);
-
+
File pluginDirectory = new File(baseDirectory, "plugins");
if (!pluginDirectory.exists()) {
pluginDirectory.mkdirs();
@@ -42,29 +42,51 @@
if (!coreManager.startCore(uiName, baseDirectory)) {
throw new PurpleRuntimeException(
- "Initialization of the libpurple core failed.");
+ "Initialization of the libpurple core failed.");
}
}
+ /**
+ * Sets the debug enabled flag.
+ *
+ * @param enabled
+ * <code>true</code> to enable debugging.
+ */
public void setDebugEnabled(boolean enabled) {
setDebugEnabled_native(enabled);
}
private native void setDebugEnabled_native(boolean enabled);
+ /**
+ * Adds a directory to search for plugins.
+ *
+ * @param directory
+ * The direcotry.
+ */
public void addPluginSearchpath(File directory) {
addPluginSearchpath_native(directory.getAbsolutePath());
}
private native void addPluginSearchpath_native(String absolutePath);
-
+ /**
+ * Creates a new purple instance.
+ *
+ * @param uiName
+ * The UI name to use.
+ * @param baseDirectory
+ * The base directory (like <code>.libpurple</code>).
+ * @return The purple instance.
+ * @throws IllegalStateException
+ * if there is already a libpurple instance.
+ */
public static PurpleInstance createInstance(String uiName,
- File baseDirectory) {
+ File baseDirectory) {
synchronized (instanceActiveMutex) {
if (instanceActive) {
throw new IllegalStateException(
- "There is already a libpurple running");
+ "There is already a libpurple running");
}
instanceActive = true;
}
@@ -74,7 +96,7 @@
/**
* Gets the current version of libpurple.
- *
+ *
* @return The version as version String.
*/
public String getVersion() {
@@ -82,15 +104,30 @@
}
private native String getVersion_native();
-
+
+ /**
+ * Gets the account list.
+ *
+ * @return The account list.
+ */
public PurpleAccountList getAccountList() {
return coreManager.getAccountList();
}
-
+
+ /**
+ * Gets the plugin list.
+ *
+ * @return The plugin list.
+ */
public PurplePluginList getPluginList() {
return coreManager.getPluginManager();
}
-
+
+ /**
+ * Gets the buddy list.
+ *
+ * @return The buddy list.
+ */
public PurpleBlist getBlist() {
return coreManager.getBlist();
}