Author: vmassol
Date: 2008-02-12 21:46:50 +0100 (Tue, 12 Feb 2008)
New Revision: 7564
Modified:
xwiki-platform/core/branches/xwiki-core-1.2/xwiki-observation/src/main/java/org/xwiki/observation/EventListener.java
xwiki-platform/core/branches/xwiki-core-1.2/xwiki-observation/src/main/java/org/xwiki/observation/ObservationManager.java
xwiki-platform/core/branches/xwiki-core-1.2/xwiki-observation/src/main/java/org/xwiki/observation/event/Event.java
xwiki-platform/core/branches/xwiki-core-1.2/xwiki-observation/src/main/java/org/xwiki/observation/event/filter/EventFilter.java
Log:
XWIKI-1522: Rewrite the notification mechanism
* Added some javadoc
Mergede from trunk (rev 7563)
Modified:
xwiki-platform/core/branches/xwiki-core-1.2/xwiki-observation/src/main/java/org/xwiki/observation/EventListener.java
===================================================================
---
xwiki-platform/core/branches/xwiki-core-1.2/xwiki-observation/src/main/java/org/xwiki/observation/EventListener.java
2008-02-12 20:45:30 UTC (rev 7563)
+++
xwiki-platform/core/branches/xwiki-core-1.2/xwiki-observation/src/main/java/org/xwiki/observation/EventListener.java
2008-02-12 20:46:50 UTC (rev 7564)
@@ -22,7 +22,24 @@
import org.xwiki.observation.event.Event;
+/**
+ * Any Java object wanting to receive events must implement this interface.
+ * For example if you want to be notified when a document is updated you'll
implement this
+ * interface and you'll register the object implementing it against the
+ * [EMAIL PROTECTED] ObservationManager}.
+ */
public interface EventListener
{
+ /**
+ * The [EMAIL PROTECTED] org.xwiki.observation.ObservationManager} calls
this methods when an event
+ * matches the event passed when this object was registered against the
Observation Manager.
+ *
+ * @param event the event triggered. Can be used to differentiate
differente events if your
+ * Object supports several events for example.
+ * @param source the event source i.e. the object for which the event was
triggered. For
+ * example this would be the document Object if the event is
a document update
+ * event.
+ * @param data some additional and optional data passed that can be acted
on.
+ */
void onEvent(Event event, Object source, Object data);
}
Modified:
xwiki-platform/core/branches/xwiki-core-1.2/xwiki-observation/src/main/java/org/xwiki/observation/ObservationManager.java
===================================================================
---
xwiki-platform/core/branches/xwiki-core-1.2/xwiki-observation/src/main/java/org/xwiki/observation/ObservationManager.java
2008-02-12 20:45:30 UTC (rev 7563)
+++
xwiki-platform/core/branches/xwiki-core-1.2/xwiki-observation/src/main/java/org/xwiki/observation/ObservationManager.java
2008-02-12 20:46:50 UTC (rev 7564)
@@ -22,8 +22,15 @@
import org.xwiki.observation.event.Event;
+/**
+ * The main orchestrator for event notification. You register [EMAIL
PROTECTED] EventListener} against this
+ * manager. It's also used to notify event listeners when an event is
triggered.
+ */
public interface ObservationManager
{
+ /**
+ * The component role under which the implementations of this interface
can be looked up.
+ */
String ROLE = ObservationManager.class.getName();
/**
Modified:
xwiki-platform/core/branches/xwiki-core-1.2/xwiki-observation/src/main/java/org/xwiki/observation/event/Event.java
===================================================================
---
xwiki-platform/core/branches/xwiki-core-1.2/xwiki-observation/src/main/java/org/xwiki/observation/event/Event.java
2008-02-12 20:45:30 UTC (rev 7563)
+++
xwiki-platform/core/branches/xwiki-core-1.2/xwiki-observation/src/main/java/org/xwiki/observation/event/Event.java
2008-02-12 20:46:50 UTC (rev 7564)
@@ -20,7 +20,19 @@
*/
package org.xwiki.observation.event;
+/**
+ * All Event types must implement this interface.
+ */
public interface Event
{
+ /**
+ * @param otherEvent
+ * @return true if the passed event matches the current event. The
matching algorithm depends
+ * on the event implementation. For example for Document events
two events match
+ * if they implement the same event class and if their
+ * [EMAIL PROTECTED]
org.xwiki.observation.event.filter.EventFilter} match. Note that the
+ * implementation is left open in order to cater for all the
possible ways this
+ * Observation component can be used.
+ */
boolean matches(Object otherEvent);
}
Modified:
xwiki-platform/core/branches/xwiki-core-1.2/xwiki-observation/src/main/java/org/xwiki/observation/event/filter/EventFilter.java
===================================================================
---
xwiki-platform/core/branches/xwiki-core-1.2/xwiki-observation/src/main/java/org/xwiki/observation/event/filter/EventFilter.java
2008-02-12 20:45:30 UTC (rev 7563)
+++
xwiki-platform/core/branches/xwiki-core-1.2/xwiki-observation/src/main/java/org/xwiki/observation/event/filter/EventFilter.java
2008-02-12 20:46:50 UTC (rev 7564)
@@ -20,8 +20,34 @@
*/
package org.xwiki.observation.event.filter;
+/**
+* Allows writing complex Event algorithms for the
+ [EMAIL PROTECTED] org.xwiki.observation.event.Event#matches(Object)} method.
+ *
+ * <p>
+ * For example this allows
+ * writing [EMAIL PROTECTED]
org.xwiki.observation.event.filter.RegexEventFilter} that can be used to
+ * easily match several documents at once. For example the following will
match all Documents
+ * which are saved which have a name matching the ".*Doc.*" regex:
+ * <code><pre>
+ * new DocumentSaveEvent(new RegexEventFilter(".*Doc.*"))
+ * </pre></code>
+ * </p>
+ */
public interface EventFilter
{
+ /**
+ * @return the filter used in the [EMAIL PROTECTED] #matches(EventFilter)}
method to verify if a
+ * passed event filter matches it.
+ * @see #matches(EventFilter)
+ */
String getFilter();
+
+ /**
+ * @param eventFilter the event filter to compare to the filter value
+ * @return true if both event filters match. The matching algorithm is
left to the filter
+ * event implementation. For example the Regex event filter will
match another
+ * filter if that other filter matches the regex.
+ */
boolean matches(EventFilter eventFilter);
}
_______________________________________________
notifications mailing list
[email protected]
http://lists.xwiki.org/mailman/listinfo/notifications
