diff options
author | Mili Verma <mili.verma@isode.com> | 2012-01-06 12:27:41 (GMT) |
---|---|---|
committer | Kevin Smith <git@kismith.co.uk> | 2012-01-12 12:08:21 (GMT) |
commit | d78e4110cd919a4a1f8b2f2ff7aa6640f53c49b3 (patch) | |
tree | af6afb653a21f3304dec0f72ee833259f9c1ff02 /src/com/isode/stroke/eventloop | |
parent | be94e872d9423501c688c84c6cb945a420a5cb18 (diff) | |
download | stroke-d78e4110cd919a4a1f8b2f2ff7aa6640f53c49b3.zip stroke-d78e4110cd919a4a1f8b2f2ff7aa6640f53c49b3.tar.bz2 |
Add Javadoc for CoreClient, EventLoop, JID
Test-information:
Looks okay.
Diffstat (limited to 'src/com/isode/stroke/eventloop')
-rw-r--r-- | src/com/isode/stroke/eventloop/EventLoop.java | 47 |
1 files changed, 41 insertions, 6 deletions
diff --git a/src/com/isode/stroke/eventloop/EventLoop.java b/src/com/isode/stroke/eventloop/EventLoop.java index 145015a..67217b4 100644 --- a/src/com/isode/stroke/eventloop/EventLoop.java +++ b/src/com/isode/stroke/eventloop/EventLoop.java @@ -1,26 +1,50 @@ /* + * Copyright (c) 2010-2012, Isode Limited, London, England. + * All rights reserved. + */ +/* * Copyright (c) 2010 Remko Tronçon * Licensed under the GNU General Public License v3. * See Documentation/Licenses/GPLv3.txt for more information. */ -/* - * Copyright (c) 2010, Isode Limited, London, England. - * All rights reserved. - */ package com.isode.stroke.eventloop; import java.util.ArrayList; import java.util.Vector; +/** + * An event loop is a seemingly infinite loop (runs for the duration of the use + * of the library) that waits for external events + * (e.g. incoming network packets, timers being activated, input happening) to + * happen; when such an event comes in, it notifies interested parties of this + * event, and then continues listening for the next event. + */ public abstract class EventLoop { + /** + * Create an event loop + */ public EventLoop() { } + /** + * Post an event to the loop. + * + * @param callback Callback handler for the event, must not be null. This + * will be called when the event is processed. + */ public void postEvent(Event.Callback callback) { postEvent(callback, null); } + /** + * Post an event to the loop. + * + * @param callback Callback handler for the event, must not be null. This + * will be called when the event is processed. + * @param owner Owner of the event, non-null. This can be used to + * {@link EventLoop#removeEventsFromOwner} later. + */ public void postEvent(Event.Callback callback, EventOwner owner) { Event event; synchronized (eventsMutex_) { @@ -31,6 +55,13 @@ public abstract class EventLoop { post(event); } + /** + * Remove all events from the given owner. + * \p + * This does a reference check (==), not calling owner.equals(). + * + * @param owner Owner of the event, must not be null + */ public void removeEventsFromOwner(EventOwner owner) { synchronized (eventsMutex_) { ArrayList<Event> matches = new ArrayList<Event>(); @@ -44,11 +75,15 @@ public abstract class EventLoop { } /** - * Reimplement this to call handleEvent(event) from the thread in which - * the event loop is residing. + * Reimplement this to call handleEvent(event) from the thread in which the + * event loop is residing. */ protected abstract void post(Event event); + /** + * When reimplementing, call this from within the {@link EventLoop#post} + * method in the application's event loop (main thread). + */ protected void handleEvent(Event event) { if (handlingEvents_) { // We're being called recursively. Push in the list of events to |