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/sandbox/atmosphere Commit: 2bf905a8f81bb5913ddbf6abf97b6bf8a6bfd745 Parents: ae3685d Author: Emond Papegaaij <[email protected]> Authored: Fri May 4 10:12:12 2012 +0200 Committer: Emond Papegaaij <[email protected]> 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; }
