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/08 11:48:26 UTC
git commit: more javadoc for wicket-atmosphere
Updated Branches:
refs/heads/master 6bc3be659 -> 3d20bc157
more javadoc for wicket-atmosphere
Project: http://git-wip-us.apache.org/repos/asf/wicket/repo
Commit: http://git-wip-us.apache.org/repos/asf/wicket/commit/3d20bc15
Tree: http://git-wip-us.apache.org/repos/asf/wicket/tree/3d20bc15
Diff: http://git-wip-us.apache.org/repos/asf/wicket/diff/3d20bc15
Branch: refs/heads/master
Commit: 3d20bc1570fbdf7db8086b07ce5072fec140214b
Parents: 6bc3be6
Author: Emond Papegaaij <pa...@apache.org>
Authored: Tue May 8 11:23:22 2012 +0200
Committer: Emond Papegaaij <pa...@apache.org>
Committed: Tue May 8 11:23:22 2012 +0200
----------------------------------------------------------------------
.../wicket/atmosphere/AtmosphereBehavior.java | 20 +++++++++++++-
.../AtmosphereEventSubscriptionCollector.java | 21 +++++++++++---
.../atmosphere/AtmosphereRequestHandler.java | 13 +++++++++
.../wicket/atmosphere/AtmosphereRequestMapper.java | 8 +++++-
.../wicket/atmosphere/AtmosphereWebRequest.java | 13 +++++++--
.../wicket/atmosphere/AtmosphereWebResponse.java | 14 ++++++++-
.../org/apache/wicket/atmosphere/EventBus.java | 13 +++++++++
.../org/apache/wicket/atmosphere/EventFilter.java | 11 +++++++
.../wicket/atmosphere/EventSubscription.java | 22 +++++++++++++++
9 files changed, 124 insertions(+), 11 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/wicket/blob/3d20bc15/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 a5a53ee..a80ce61 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
@@ -24,6 +24,14 @@ import org.atmosphere.cpr.Meteor;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
+/**
+ * {@code AtmosphereBehavior} manages the suspended connection from the client. It adds the required
+ * javascript libraries to the markup which setup a suspended connection. This connection can be
+ * websocket, streaming http or long-polling, depending on what the client and server support. This
+ * behavior is added automatically to pages with components with event subscriptions.
+ *
+ * @author papegaaij
+ */
public class AtmosphereBehavior extends Behavior
implements
IResourceListener,
@@ -31,6 +39,9 @@ public class AtmosphereBehavior extends Behavior
{
private static final Logger log = LoggerFactory.getLogger(AtmosphereBehavior.class);
+ /**
+ * The key under which a unique id is stored in the page. This id is unique for all clients.
+ */
public static MetaDataKey<String> ATMOSPHERE_UUID = new MetaDataKey<String>()
{
private static final long serialVersionUID = 1L;
@@ -40,6 +51,9 @@ public class AtmosphereBehavior extends Behavior
private Component component;
+ /**
+ * Construct.
+ */
public AtmosphereBehavior()
{
}
@@ -134,7 +148,7 @@ public class AtmosphereBehavior extends Behavior
@Override
public void onThrowable(AtmosphereResourceEvent event)
{
- event.throwable().printStackTrace();
+ log.error(event.throwable().getMessage(), event.throwable());
}
@Override
@@ -158,6 +172,10 @@ public class AtmosphereBehavior extends Behavior
}
}
+ /**
+ * @param resource
+ * @return the unique id for the given suspended connection
+ */
public static String getUUID(AtmosphereResource resource)
{
String trackingId = resource.getRequest().getHeader(HeaderConfig.X_ATMOSPHERE_TRACKING_ID);
http://git-wip-us.apache.org/repos/asf/wicket/blob/3d20bc15/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/AtmosphereEventSubscriptionCollector.java
----------------------------------------------------------------------
diff --git a/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/AtmosphereEventSubscriptionCollector.java b/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/AtmosphereEventSubscriptionCollector.java
index 195a723..3225a7f 100644
--- a/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/AtmosphereEventSubscriptionCollector.java
+++ b/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/AtmosphereEventSubscriptionCollector.java
@@ -8,10 +8,23 @@ import org.apache.wicket.WicketRuntimeException;
import org.apache.wicket.ajax.AjaxRequestTarget;
import org.apache.wicket.application.IComponentOnBeforeRenderListener;
+/**
+ * Collects {@linkplain Subscribe event subscriptions} on components. Subscriptions are refreshed on
+ * every render of component. If a page contains a component with a subscription, an
+ * {@link AtmosphereBehavior} is added to the page. There is no need to register this listener, it
+ * is added automatically by {@link EventBus}.
+ *
+ * @author papegaaij
+ */
public class AtmosphereEventSubscriptionCollector implements IComponentOnBeforeRenderListener
{
private EventBus eventBus;
+ /**
+ * Construct.
+ *
+ * @param eventBus
+ */
public AtmosphereEventSubscriptionCollector(EventBus eventBus)
{
this.eventBus = eventBus;
@@ -24,11 +37,11 @@ public class AtmosphereEventSubscriptionCollector implements IComponentOnBeforeR
{
if (curMethod.isAnnotationPresent(Subscribe.class))
{
- Class< ? >[] params = curMethod.getParameterTypes();
+ Class<?>[] params = curMethod.getParameterTypes();
if (params.length != 2 || !params[0].equals(AjaxRequestTarget.class))
- throw new WicketRuntimeException("@Subscribe can only be used on "
- + "methods with 2 params, of which the first is AjaxRequestTarget. "
- + curMethod + " does conform to this signature.");
+ throw new WicketRuntimeException("@Subscribe can only be used on " +
+ "methods with 2 params, of which the first is AjaxRequestTarget. " +
+ curMethod + " does conform to this signature.");
subscribeComponent(component, curMethod);
}
}
http://git-wip-us.apache.org/repos/asf/wicket/blob/3d20bc15/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/AtmosphereRequestHandler.java
----------------------------------------------------------------------
diff --git a/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/AtmosphereRequestHandler.java b/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/AtmosphereRequestHandler.java
index 45a3d50..0af6e44 100644
--- a/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/AtmosphereRequestHandler.java
+++ b/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/AtmosphereRequestHandler.java
@@ -13,6 +13,12 @@ import org.apache.wicket.protocol.http.WebApplication;
import org.apache.wicket.request.IRequestCycle;
import org.apache.wicket.request.IRequestHandler;
+/**
+ * Handles pseudo requests triggered by an event. An {@link AjaxRequestTarget} is scheduled and the
+ * subscribed methods are invoked.
+ *
+ * @author papegaaij
+ */
public class AtmosphereRequestHandler implements IRequestHandler
{
private PageKey pageKey;
@@ -21,6 +27,13 @@ public class AtmosphereRequestHandler implements IRequestHandler
private Collection<EventSubscription> subscriptions;
+ /**
+ * Construct.
+ *
+ * @param pageKey
+ * @param subscriptions
+ * @param event
+ */
public AtmosphereRequestHandler(PageKey pageKey, Collection<EventSubscription> subscriptions,
Object event)
{
http://git-wip-us.apache.org/repos/asf/wicket/blob/3d20bc15/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/AtmosphereRequestMapper.java
----------------------------------------------------------------------
diff --git a/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/AtmosphereRequestMapper.java b/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/AtmosphereRequestMapper.java
index 25b5f86..8834211 100644
--- a/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/AtmosphereRequestMapper.java
+++ b/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/AtmosphereRequestMapper.java
@@ -5,6 +5,12 @@ import org.apache.wicket.request.IRequestMapper;
import org.apache.wicket.request.Request;
import org.apache.wicket.request.Url;
+/**
+ * Internal {@link IRequestMapper} to map {@link AtmosphereWebRequest} to
+ * {@link AtmosphereRequestHandler}. This mapper is registered automatically by {@link EventBus}.
+ *
+ * @author papegaaij
+ */
public class AtmosphereRequestMapper implements IRequestMapper
{
@Override
@@ -12,7 +18,7 @@ public class AtmosphereRequestMapper implements IRequestMapper
{
if (request instanceof AtmosphereWebRequest)
{
- AtmosphereWebRequest pushRequest = (AtmosphereWebRequest) request;
+ AtmosphereWebRequest pushRequest = (AtmosphereWebRequest)request;
return new AtmosphereRequestHandler(pushRequest.getPageKey(),
pushRequest.getSubscriptions(), pushRequest.getEvent());
}
http://git-wip-us.apache.org/repos/asf/wicket/blob/3d20bc15/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/AtmosphereWebRequest.java
----------------------------------------------------------------------
diff --git a/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/AtmosphereWebRequest.java b/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/AtmosphereWebRequest.java
index 3e9c79f..722b3aa 100644
--- a/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/AtmosphereWebRequest.java
+++ b/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/AtmosphereWebRequest.java
@@ -11,7 +11,14 @@ import org.apache.wicket.request.Url;
import org.apache.wicket.request.http.WebRequest;
import org.apache.wicket.util.time.Time;
-public class AtmosphereWebRequest extends WebRequest
+/**
+ * Internal request to signal the processing of an event. This request will be mapped by
+ * {@link AtmosphereRequestMapper} to an {@link AtmosphereRequestHandler}. The response will be
+ * written to the client of a suspended connection.
+ *
+ * @author papegaaij
+ */
+class AtmosphereWebRequest extends WebRequest
{
private WebRequest wrappedRequest;
@@ -21,8 +28,8 @@ public class AtmosphereWebRequest extends WebRequest
private Object event;
- public AtmosphereWebRequest(WebRequest wrappedRequest, PageKey pageKey,
- Collection<EventSubscription> subscriptions, Object event)
+ AtmosphereWebRequest(WebRequest wrappedRequest, PageKey pageKey,
+ Collection<EventSubscription> subscriptions, Object event)
{
this.wrappedRequest = wrappedRequest;
this.pageKey = pageKey;
http://git-wip-us.apache.org/repos/asf/wicket/blob/3d20bc15/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/AtmosphereWebResponse.java
----------------------------------------------------------------------
diff --git a/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/AtmosphereWebResponse.java b/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/AtmosphereWebResponse.java
index 19e9b3e..ded9d66 100644
--- a/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/AtmosphereWebResponse.java
+++ b/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/AtmosphereWebResponse.java
@@ -7,13 +7,23 @@ import org.apache.wicket.util.string.AppendingStringBuffer;
import org.apache.wicket.util.time.Time;
import org.atmosphere.cpr.AtmosphereResponse;
-public class AtmosphereWebResponse extends WebResponse
+/**
+ * Internal response class to wrap {@code AtmosphereResponse} to a {@link WebResponse}.
+ *
+ * @author papegaaij
+ */
+class AtmosphereWebResponse extends WebResponse
{
private AtmosphereResponse response;
private final AppendingStringBuffer out;
private boolean redirect;
- public AtmosphereWebResponse(AtmosphereResponse response)
+ /**
+ * Construct.
+ *
+ * @param response
+ */
+ AtmosphereWebResponse(AtmosphereResponse response)
{
this.response = response;
out = new AppendingStringBuffer(128);
http://git-wip-us.apache.org/repos/asf/wicket/blob/3d20bc15/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 8784fda..38d5364 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
@@ -102,6 +102,12 @@ public class EventBus implements UnboundListener
new Object[] { pageKey.getPageId(), pageKey.getSessionId() });
}
+ /**
+ * Registers an {@link EventSubscription} for the given page.
+ *
+ * @param page
+ * @param subscription
+ */
public synchronized void register(Page page, EventSubscription subscription)
{
log.info("registering component for {} for session {}: {}", new Object[] {
@@ -109,6 +115,13 @@ public class EventBus implements UnboundListener
subscriptions.put(new PageKey(page.getPageId(), Session.get().getId()), subscription);
}
+ /**
+ * Post an event to all pages that have a suspended connection. This will invoke the event
+ * handlers on components, annotated with {@link Subscribe}. The resulting AJAX updates are
+ * pushed to the clients.
+ *
+ * @param event
+ */
public void post(Object event)
{
ThreadContext oldContext = ThreadContext.get(false);
http://git-wip-us.apache.org/repos/asf/wicket/blob/3d20bc15/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/EventFilter.java
----------------------------------------------------------------------
diff --git a/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/EventFilter.java b/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/EventFilter.java
index e93c196..19d8c3a 100644
--- a/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/EventFilter.java
+++ b/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/EventFilter.java
@@ -2,10 +2,21 @@ package org.apache.wicket.atmosphere;
import com.google.common.base.Predicate;
+/**
+ * Used by {@link EventBus} to filters subscriptions for a given event. Both event type and
+ * {@linkplain Subscribe#filter() subscription filter} are taken into account.
+ *
+ * @author papegaaij
+ */
public class EventFilter implements Predicate<EventSubscription>
{
private Object event;
+ /**
+ * Construct.
+ *
+ * @param event
+ */
public EventFilter(Object event)
{
this.event = event;
http://git-wip-us.apache.org/repos/asf/wicket/blob/3d20bc15/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/EventSubscription.java
----------------------------------------------------------------------
diff --git a/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/EventSubscription.java b/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/EventSubscription.java
index c31c765..db9a341 100644
--- a/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/EventSubscription.java
+++ b/wicket-experimental/wicket-atmosphere/src/main/java/org/apache/wicket/atmosphere/EventSubscription.java
@@ -9,6 +9,12 @@ import com.google.common.base.Objects;
import com.google.common.base.Predicate;
import com.google.common.base.Predicates;
+/**
+ * The subscription of a method on a component to certain events. This is used by {@link EventBus}
+ * to track the subscriptions.
+ *
+ * @author papegaaij
+ */
public class EventSubscription
{
private String componentPath;
@@ -17,6 +23,12 @@ public class EventSubscription
private Predicate<Object> filter;
+ /**
+ * Construct.
+ *
+ * @param component
+ * @param method
+ */
public EventSubscription(Component component, Method method)
{
componentPath = component.getPageRelativePath();
@@ -43,16 +55,26 @@ public class EventSubscription
}
}
+ /**
+ * @return The path of the subscribed component
+ */
public String getComponentPath()
{
return componentPath;
}
+ /**
+ * @return The filter on incomming events, a combination of the type and the
+ * {@link Subscribe#filter()} parameter.
+ */
public Predicate<Object> getFilter()
{
return filter;
}
+ /**
+ * @return The method that is subscribed
+ */
public String getMethodName()
{
return methodName;