You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@wicket.apache.org by pa...@apache.org on 2012/05/04 14:12:21 UTC
[6/24] git commit: started documenting the code
started documenting the code
Project: http://git-wip-us.apache.org/repos/asf/wicket/repo
Commit: http://git-wip-us.apache.org/repos/asf/wicket/commit/2bf905a8
Tree: http://git-wip-us.apache.org/repos/asf/wicket/tree/2bf905a8
Diff: http://git-wip-us.apache.org/repos/asf/wicket/diff/2bf905a8
Branch: refs/heads/master
Commit: 2bf905a8f81bb5913ddbf6abf97b6bf8a6bfd745
Parents: ae3685d
Author: Emond Papegaaij <pa...@apache.org>
Authored: Fri May 4 10:12:12 2012 +0200
Committer: Emond Papegaaij <pa...@apache.org>
Committed: Fri May 4 10:12:12 2012 +0200
----------------------------------------------------------------------
.../wicket/atmosphere/AtmosphereBehavior.java | 11 +-----
.../org/apache/wicket/atmosphere/EventBus.java | 29 ++++++++++++++
.../JQueryWicketAtmosphereResourceReference.java | 19 ++++++++-
.../wicket/atmosphere/NoFilterPredicate.java | 5 ++
.../java/org/apache/wicket/atmosphere/PageKey.java | 21 ++++++++++
.../org/apache/wicket/atmosphere/Subscribe.java | 30 +++++++++++++-
6 files changed, 100 insertions(+), 15 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/wicket/blob/2bf905a8/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/AtmosphereBehavior.java
----------------------------------------------------------------------
diff --git a/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/AtmosphereBehavior.java b/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/AtmosphereBehavior.java
index c9ee43d..a5a53ee 100644
--- a/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/AtmosphereBehavior.java
+++ b/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/AtmosphereBehavior.java
@@ -1,7 +1,5 @@
package org.apache.wicket.atmosphere;
-import java.util.Enumeration;
-
import javax.servlet.http.HttpServletRequest;
import org.apache.wicket.Component;
@@ -63,13 +61,6 @@ public class AtmosphereBehavior extends Behavior
{
RequestCycle requestCycle = RequestCycle.get();
ServletWebRequest request = (ServletWebRequest)requestCycle.getRequest();
- System.out.println(request.getUrl());
- Enumeration<String> e = request.getContainerRequest().getHeaderNames();
- while (e.hasMoreElements())
- {
- String header = e.nextElement();
- System.out.println(header + ": " + request.getHeader(header));
- }
// Grab a Meteor
Meteor meteor = Meteor.build(request.getContainerRequest());
@@ -153,7 +144,7 @@ public class AtmosphereBehavior extends Behavior
{
CoreLibrariesContributor.contributeAjax(component.getApplication(), response);
- response.render(JavaScriptHeaderItem.forReference(new JQueryWicketAtmosphereResourceReference()));
+ response.render(JavaScriptHeaderItem.forReference(JQueryWicketAtmosphereResourceReference.get()));
JSONObject options = new JSONObject();
options.put("url",
component.urlFor(this, IResourceListener.INTERFACE, new PageParameters())
http://git-wip-us.apache.org/repos/asf/wicket/blob/2bf905a8/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/EventBus.java
----------------------------------------------------------------------
diff --git a/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/EventBus.java b/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/EventBus.java
index 7cbc06a..06279e1 100644
--- a/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/EventBus.java
+++ b/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/EventBus.java
@@ -29,6 +29,21 @@ import com.google.common.collect.HashMultimap;
import com.google.common.collect.Iterators;
import com.google.common.collect.Multimap;
+/**
+ * Broadcasts events to methods on components annotated with {@link Subscribe}.
+ * {@linkplain EventBus#post(Object) Posted} events are broadcasted to all components on active
+ * pages if they have a method annotated with {@link Subscribe}. To create and register an
+ * {@code EventBus}, put the following code in your application's init method:
+ *
+ * <pre>
+ * this.eventBus = new EventBus(this);
+ * </pre>
+ *
+ * The {@code EventBus} will register itself in the application once instantiated. It might be
+ * practical to keep a reference in the application, but you can always get it using {@link #get()}.
+ *
+ * @author papegaaij
+ */
public class EventBus implements UnboundListener
{
private static final Logger log = LoggerFactory.getLogger(EventBus.class);
@@ -38,6 +53,9 @@ public class EventBus implements UnboundListener
private static final long serialVersionUID = 1L;
};
+ /**
+ * @return the {@code EventBus} registered for the current Wicket application.
+ */
public static EventBus get()
{
return Application.get().getMetaData(EVENT_BUS_KEY);
@@ -51,6 +69,11 @@ public class EventBus implements UnboundListener
private BiMap<String, PageKey> trackedPages = HashBiMap.create();
+ /**
+ * Creates and registers an {@code EventBus} for the given application
+ *
+ * @param application
+ */
public EventBus(WebApplication application)
{
this.application = application;
@@ -62,6 +85,12 @@ public class EventBus implements UnboundListener
broadcaster = BroadcasterFactory.getDefault().lookup("/*");
}
+ /**
+ * Registers a page for the given tracking-id in the {@code EventBus}.
+ *
+ * @param trackingId
+ * @param page
+ */
public synchronized void registerPage(String trackingId, Page page)
{
PageKey oldPage = trackedPages.remove(trackingId);
http://git-wip-us.apache.org/repos/asf/wicket/blob/2bf905a8/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/JQueryWicketAtmosphereResourceReference.java
----------------------------------------------------------------------
diff --git a/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/JQueryWicketAtmosphereResourceReference.java b/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/JQueryWicketAtmosphereResourceReference.java
index 9bf8248..db13c89 100644
--- a/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/JQueryWicketAtmosphereResourceReference.java
+++ b/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/JQueryWicketAtmosphereResourceReference.java
@@ -7,17 +7,32 @@ import org.apache.wicket.markup.head.JavaScriptHeaderItem;
import org.apache.wicket.request.resource.JavaScriptResourceReference;
import org.apache.wicket.resource.JQueryPluginResourceReference;
+/**
+ * Resource reference for the jquery.atmosphere.js module and the wicket glue.
+ *
+ * @author papegaaij
+ */
public class JQueryWicketAtmosphereResourceReference extends JavaScriptResourceReference
{
private static final long serialVersionUID = 1L;
- public JQueryWicketAtmosphereResourceReference()
+ private static final JQueryWicketAtmosphereResourceReference INSTANCE = new JQueryWicketAtmosphereResourceReference();
+
+ /**
+ * @return the singleton instance of this resource reference.
+ */
+ public static JQueryWicketAtmosphereResourceReference get()
+ {
+ return INSTANCE;
+ }
+
+ private JQueryWicketAtmosphereResourceReference()
{
super(JQueryWicketAtmosphereResourceReference.class, "jquery.wicketatmosphere.js");
}
@Override
- public Iterable< ? extends HeaderItem> getDependencies()
+ public Iterable<? extends HeaderItem> getDependencies()
{
return Arrays.asList(JavaScriptHeaderItem.forReference(new JQueryPluginResourceReference(
JQueryWicketAtmosphereResourceReference.class, "jquery.atmosphere.js")));
http://git-wip-us.apache.org/repos/asf/wicket/blob/2bf905a8/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/NoFilterPredicate.java
----------------------------------------------------------------------
diff --git a/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/NoFilterPredicate.java b/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/NoFilterPredicate.java
index b16108d..5cfcdd5 100644
--- a/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/NoFilterPredicate.java
+++ b/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/NoFilterPredicate.java
@@ -2,6 +2,11 @@ package org.apache.wicket.atmosphere;
import com.google.common.base.Predicate;
+/**
+ * A filter that always returns true.
+ *
+ * @author papegaaij
+ */
public class NoFilterPredicate implements Predicate<Object>
{
@Override
http://git-wip-us.apache.org/repos/asf/wicket/blob/2bf905a8/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/PageKey.java
----------------------------------------------------------------------
diff --git a/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/PageKey.java b/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/PageKey.java
index 07092ee..ae4e11b 100644
--- a/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/PageKey.java
+++ b/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/PageKey.java
@@ -2,28 +2,49 @@ package org.apache.wicket.atmosphere;
import com.google.common.base.Objects;
+/**
+ * Identifies a page by its id and the session it belongs to.
+ *
+ * @author papegaaij
+ */
public class PageKey
{
private Integer pageId;
private String sessionId;
+ /**
+ * Construct.
+ *
+ * @param pageId
+ * @param sessionId
+ */
public PageKey(Integer pageId, String sessionId)
{
this.pageId = pageId;
this.sessionId = sessionId;
}
+ /**
+ * @return The id of the page
+ */
public Integer getPageId()
{
return pageId;
}
+ /**
+ * @return The id of the session
+ */
public String getSessionId()
{
return sessionId;
}
+ /**
+ * @param sessionId
+ * @return true if this {@code PageKey} is for the same session
+ */
public boolean isForSession(String sessionId)
{
return getSessionId().equals(sessionId);
http://git-wip-us.apache.org/repos/asf/wicket/blob/2bf905a8/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/Subscribe.java
----------------------------------------------------------------------
diff --git a/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/Subscribe.java b/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/Subscribe.java
index 35bbea6..4554d39 100644
--- a/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/Subscribe.java
+++ b/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/Subscribe.java
@@ -5,11 +5,35 @@ import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+import org.apache.wicket.Session;
+import org.apache.wicket.ajax.AjaxRequestTarget;
+import org.apache.wicket.request.cycle.RequestCycle;
+
import com.google.common.base.Predicate;
+/**
+ * Subscribes a method on a component to receive events of a certain type. The method should have 2
+ * parameters: the first must be {@link AjaxRequestTarget}, the second defines the type of events to
+ * receive. This method will receive any event posted to the {@link EventBus} if it matches the type
+ * of the second parameter and the filter accepts it. Any context a Wicket component expects to be
+ * available, such as the {@link RequestCycle} and {@link Session}, is accessible on invocation of
+ * the method.
+ *
+ * <p>
+ * Annotated methods will automatically be detected by {@link AtmosphereEventSubscriptionCollector}.
+ * The page on which the component is placed will get a {@link AtmosphereBehavior}, which sets up a
+ * persistent connection (for example websocket or streaming http).
+ *
+ * @author papegaaij
+ */
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
-public @interface Subscribe
-{
- Class< ? extends Predicate< ? >> filter() default NoFilterPredicate.class;
+public @interface Subscribe {
+ /**
+ * An optional filter on events to be received by the method. The filter cannot rely on any
+ * context. For example, the {@link RequestCycle} may not be available.
+ *
+ * @return The filter on events, defaults to no filter.
+ */
+ Class<? extends Predicate<?>> filter() default NoFilterPredicate.class;
}