Breaking change to pass a PusherEvent object to onEvent

kn100 · WillSewell · commit aeb62de367a2 · 2019-08-08T14:47:26.000+01:00
Introduces a PusherEvent class which is now passed as a single argument to onEvent. onEvent used to take 3 arguments (channel name, event name, data), so this is a breaking change.

The PusherEvent exposes a method getUserId which exposes user_ids which are added to client events on presence channels. This is a new feature, and the motivation for this breaking change.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,12 +2,16 @@
 
 This Changelog is no longer being updated. For any further changes please see the Releases section on this Github repository - https://github.com/pusher/pusher-websocket-java/releases
 
+## Version 2.0.0
+* The onEvent handler now gets called with one parameter, called the PusherEvent. This PusherEvent has all the same information available as was available before with the 3 parameters, but now is accessible by calling getChannelName(), getData() or getEventName() on the PusherEvent object you receive. In addition, for presence channel client events, you can now retrieve an authenticated User ID by calling getUserId() on the PusherEvent object. To read more on Authenticated users, see the README or our docs [here](https://pusher.com/docs/channels/using_channels/events#user-id-in-client-events).
+
+
 ## Version 1.4.0
 * Update the dependency to use pusher/java-websocket fork and remove dependency on clojars.org repository.
 
 ## Version 1.3.0
 * Add retry logic when the connection is lost
-* Accept 201 status code from auth endpoints 
+* Accept 201 status code from auth endpoints
 
 ## Version 1.2.2
 
diff --git a/README.md b/README.md
@@ -107,12 +107,12 @@ Channel channel = pusher.subscribe("my-channel");
 // Bind to listen for events called "my-event" sent to "my-channel"
 channel.bind("my-event", new SubscriptionEventListener() {
     @Override
-    public void onEvent(String channel, String event, String data) {
-        System.out.println("Received event with data: " + data);
+    public void onEvent(PusherEvent event) {
+        System.out.println("Received event with data: " + event.toString());
     }
 });
 
-// Disconnect from the service (or become disconnected my network conditions)
+// Disconnect from the service
 pusher.disconnect();
 
 // Reconnect, with all channel subscriptions and event bindings automatically recreated
@@ -340,6 +340,21 @@ UserInfo info = gson.fromJson(jsonInfo, UserInfo.class);
 
 For more information on defining the user id and user info on the server see [Implementing the auth endpoint for a presence channel](https://pusher.com/docs/channels/server_api/authenticating-users#implementing-the-auth-endpoint-for-a-presence-channel) documentation.
 
+#### Client event authenticity
+
+Channels now provides a 'user-id' with client events sent from the server. With presence channels, your authentication endpoint provides your user with a user-id. Previously, it was up to you to include this user-id in every client-event triggered by your clients. Now, when a client of yours triggers a client event, Channels will append their user-id to their triggered message, so that the other clients in the channel receive it. This allows you to trust that a given user really did trigger a given payload.
+
+If you’d like to make use of this feature, you’ll need to extract the user-id from the message delivered by Channels. To do this, call getUserId() on the event payload your event handler gets called with, like so:
+
+```java
+channel.bind("client-my-event", new SubscriptionEventListener() {
+    @Override
+    public void onEvent(PusherEvent event) {
+        System.out.println("Received event with userId: " + event.getUserId());
+    }
+});
+```
+
 ## Binding and handling events
 
 There are two types of events that occur on channel subscriptions.
@@ -359,7 +374,7 @@ Channel channel = pusher.subscribe("my-channel", new ChannelEventListener() {
     }
 
     @Override
-    public void onEvent(String channelName, String eventName, String data) {
+    public void onEvent(PusherEvent event) {
         // Called for incoming events names "foo", "bar" or "baz"
     }
 }, "foo", "bar", "baz");
@@ -375,13 +390,13 @@ Events triggered by your application are received by the `onEvent` method on the
 Channel channel = pusher.subscribe("my-channel");
 channel.bind("my-event", new ChannelEventListener() {
     @Override
-    public void onEvent(String channelName, String eventName, String data) {
+    public void onEvent(PusherEvent event) {
         // Called for incoming events named "my-event"
     }
 });
 ```
 
-The event data will be passed as the third parameter to the `onEvent` method. From there you can handle the data as you like. Since we encourage data to be in JSON here's an example that uses [Gson object deserialization](https://sites.google.com/site/gson/gson-user-guide#TOC-Object-Examples):
+The event data is accessible by calling the `getData()` method on the event. From there you can handle the data as you like. Since we encourage data to be in JSON here's an example that uses [Gson object deserialization](https://sites.google.com/site/gson/gson-user-guide#TOC-Object-Examples):
 
 ```java
 public class Example implements ChannelEventListener {
@@ -392,9 +407,9 @@ public class Example implements ChannelEventListener {
     }
 
     @Override
-    public void onEvent(String channelName, String eventName, String data) {
+    public void onEvent(PusherEvent event) {
         Gson gson = new Gson();
-        EventExample exampleEvent = gson.fromJson(data, EventExample.class);
+        EventExample exampleEvent = gson.fromJson(event.getData(), EventExample.class);
     }
 }
 
diff --git a/src/main/java/com/pusher/client/channel/PusherEvent.java b/src/main/java/com/pusher/client/channel/PusherEvent.java
@@ -0,0 +1,45 @@
+package com.pusher.client.channel;
+
+import java.util.Map;
+
+public class PusherEvent {
+    private Map<String, Object> eventData;
+
+    public PusherEvent(Map<String, Object> eventData) {
+        this.eventData = eventData;
+    }
+
+    /**
+     * getProperty returns the value associated with the key, or null.
+     * It is recommended that you use the specialized getters in this class instead.
+     *
+     * @param key The key you wish to get.
+     * @return
+     *      The object can be casted as follows:
+     *      - JSON strings - java.lang.String
+     *      - JSON number - java.lang.Double
+     *      - JSON boolean - java.lang.Boolean
+     *      - JSON array - java.util.ArrayList
+     *      - JSON object - java.util.Map
+     *      - JSON null - null
+     */
+    public Object getProperty(String key) {
+        return eventData.get(key);
+    }
+
+    /**
+     * Returns the userId associated with this event.
+     *
+     * @return
+     *      The userID string: https://pusher.com/docs/channels/using_channels/events#user-id-in-client-events,
+     *      or null if the event is not a client event on a presence channel.
+     */
+    public String getUserId() { return (String)eventData.get("user_id"); }
+    public String getChannelName() { return (String)eventData.get("channel"); }
+    public String getEventName() { return (String)eventData.get("event"); }
+    public String getData() { return (String)eventData.get("data"); }
+
+    public String toString() {
+        return eventData.toString();
+    }
+}
diff --git a/src/main/java/com/pusher/client/channel/PusherEventDeserializer.java b/src/main/java/com/pusher/client/channel/PusherEventDeserializer.java
@@ -0,0 +1,20 @@
+package com.pusher.client.channel;
+
+import java.lang.reflect.Type;
+import java.util.Map;
+
+import com.google.gson.Gson;
+import com.google.gson.JsonDeserializationContext;
+import com.google.gson.JsonDeserializer;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonParseException;
+
+public class PusherEventDeserializer implements JsonDeserializer<PusherEvent> {
+    private final Gson GSON = new Gson();
+
+    @Override
+    @SuppressWarnings("unchecked")
+    public PusherEvent deserialize(JsonElement json, Type typeOfT, JsonDeserializationContext context) throws JsonParseException {
+        return new PusherEvent(GSON.fromJson(json, Map.class));
+    }
+}
diff --git a/src/main/java/com/pusher/client/channel/SubscriptionEventListener.java b/src/main/java/com/pusher/client/channel/SubscriptionEventListener.java
@@ -28,18 +28,9 @@ public interface SubscriptionEventListener {
      * Callback that is fired whenever an event that this
      * {@linkplain SubscriptionEventListener} has been bound to is received.
      *
-     * @param channelName
-     *            The name of the channel that the event has been received on.
-     *            This is useful if your {@linkplain ChannelEventListener} has
-     *            been bound to events on more than one channel.
-     * @param eventName
-     *            The name of the event that has been received. This will always
-     *            be one of the events that your
-     *            {@linkplain ChannelEventListener} has been bound to.
-     * @param data
-     *            The JSON data that was included with the event. This can be
-     *            parsed with Google's Gson library, which is a dependency of
-     *            this library, or your library of choice.
+     * @param event
+     *            A PusherEvent object which exposes the whole event.
+     *            See {@linkplain PusherEvent} for more.
      */
-    void onEvent(String channelName, String eventName, String data);
+    void onEvent(final PusherEvent event);
 }
diff --git a/src/main/java/com/pusher/client/channel/impl/ChannelImpl.java b/src/main/java/com/pusher/client/channel/impl/ChannelImpl.java
@@ -1,6 +1,5 @@
 package com.pusher.client.channel.impl;
 
-import java.util.Collections;
 import java.util.HashMap;
 import java.util.HashSet;
 import java.util.LinkedHashMap;
@@ -9,14 +8,12 @@
 
 import com.google.gson.Gson;
 
-import com.pusher.client.channel.ChannelEventListener;
-import com.pusher.client.channel.ChannelState;
-import com.pusher.client.channel.SubscriptionEventListener;
+import com.google.gson.GsonBuilder;
+import com.pusher.client.channel.*;
 import com.pusher.client.util.Factory;
 
 public class ChannelImpl implements InternalChannel {
-
-    private static final Gson GSON = new Gson();
+    private final Gson GSON;
     private static final String INTERNAL_EVENT_PREFIX = "pusher_internal:";
     protected static final String SUBSCRIPTION_SUCCESS_EVENT = "pusher_internal:subscription_succeeded";
     protected final String name;
@@ -27,7 +24,9 @@ public class ChannelImpl implements InternalChannel {
     private final Object lock = new Object();
 
     public ChannelImpl(final String channelName, final Factory factory) {
-
+        GsonBuilder gsonBldr = new GsonBuilder();
+        gsonBldr.registerTypeAdapter(PusherEvent.class, new PusherEventDeserializer());
+        GSON = gsonBldr.create();
         if (channelName == null) {
             throw new IllegalArgumentException("Cannot subscribe to a channel with a null name");
         }
@@ -110,19 +109,19 @@ public void onMessage(final String event, final String message) {
 
             if (listeners != null) {
                 for (final SubscriptionEventListener listener : listeners) {
-                    final String data = extractDataFrom(message);
-
+                    final PusherEvent e = GSON.fromJson(message, PusherEvent.class);
                     factory.queueOnEventThread(new Runnable() {
                         @Override
                         public void run() {
-                            listener.onEvent(name, event, data);
+                            listener.onEvent(e);
                         }
                     });
                 }
             }
         }
     }
 
+
     @Override
     public String toSubscribeMessage() {
 
@@ -189,11 +188,6 @@ public String toString() {
         return String.format("[Public Channel: name=%s]", name);
     }
 
-    @SuppressWarnings("unchecked")
-    private String extractDataFrom(final String message) {
-        final Map<Object, Object> jsonObject = GSON.fromJson(message, Map.class);
-        return (String)jsonObject.get("data");
-    }
 
     protected String[] getDisallowedNameExpressions() {
         return new String[] { "^private-.*", "^presence-.*" };
diff --git a/src/main/java/com/pusher/client/example/ExampleApp.java b/src/main/java/com/pusher/client/example/ExampleApp.java
@@ -7,6 +7,7 @@
 import com.pusher.client.Pusher;
 import com.pusher.client.PusherOptions;
 import com.pusher.client.channel.ChannelEventListener;
+import com.pusher.client.channel.PusherEvent;
 import com.pusher.client.connection.ConnectionEventListener;
 import com.pusher.client.connection.ConnectionStateChange;
 
@@ -64,14 +65,12 @@ public void onError(final String message, final String code, final Exception e)
     /* ChannelEventListener implementation */
 
     @Override
-    public void onEvent(final String channelName, final String eventName, final String data) {
-
-        System.out.println(String.format("[%d] Received event [%s] on channel [%s] with data [%s]", timestamp(),
-                eventName, channelName, data));
+    public void onEvent(final PusherEvent event) {
+        System.out.println(String.format("[%d] Received event [%s]", timestamp(), event.toString()));
 
         final Gson gson = new Gson();
         @SuppressWarnings("unchecked")
-        final Map<String, String> jsonObject = gson.fromJson(data, Map.class);
+        final Map<String, String> jsonObject = gson.fromJson(event.getData(), Map.class);
         System.out.println(jsonObject);
     }
 
diff --git a/src/main/java/com/pusher/client/example/PresenceChannelExampleApp.java b/src/main/java/com/pusher/client/example/PresenceChannelExampleApp.java
@@ -4,6 +4,7 @@
 
 import com.pusher.client.Pusher;
 import com.pusher.client.PusherOptions;
+import com.pusher.client.channel.PusherEvent;
 import com.pusher.client.channel.PresenceChannel;
 import com.pusher.client.channel.PresenceChannelEventListener;
 import com.pusher.client.channel.User;
@@ -93,10 +94,9 @@ public void userUnsubscribed(final String channelName, final User user) {
     }
 
     @Override
-    public void onEvent(final String channelName, final String eventName, final String data) {
+    public void onEvent(final PusherEvent event) {
 
-        System.out.println(String.format("Received event [%s] on channel [%s] with data [%s]", eventName, channelName,
-                data));
+        System.out.println(String.format("Received event [%s]", event.toString()));
     }
 
     @Override
diff --git a/src/main/java/com/pusher/client/example/PrivateChannelExampleApp.java b/src/main/java/com/pusher/client/example/PrivateChannelExampleApp.java
@@ -2,6 +2,7 @@
 
 import com.pusher.client.Pusher;
 import com.pusher.client.PusherOptions;
+import com.pusher.client.channel.PusherEvent;
 import com.pusher.client.channel.PrivateChannel;
 import com.pusher.client.channel.PrivateChannelEventListener;
 import com.pusher.client.connection.ConnectionEventListener;
@@ -66,10 +67,9 @@ public void onError(final String message, final String code, final Exception e)
     /* PrivateChannelEventListener implementation */
 
     @Override
-    public void onEvent(final String channelName, final String eventName, final String data) {
+    public void onEvent(final PusherEvent event) {
 
-        System.out.println(String.format("Received event [%s] on channel [%s] with data [%s]", eventName, channelName,
-                data));
+        System.out.println(String.format("Received event [%s] on channel [%s] with data [%s] and event [%s]", event.getEventName(), event.getChannelName(), event.getData(), event.toString()));
     }
 
     @Override
diff --git a/src/test/java/com/pusher/client/channel/PusherEventTest.java b/src/test/java/com/pusher/client/channel/PusherEventTest.java
diff --git a/src/test/java/com/pusher/client/channel/impl/ChannelImplTest.java b/src/test/java/com/pusher/client/channel/impl/ChannelImplTest.java
