001package com.pusher.client.channel;
002
003/**
004 * Client applications should implement this interface if they want to be
005 * notified when events are received on a public or private channel.
006 *
007 * <p>
008 * To bind your implementation of this interface to a channel, either:
009 * </p>
010 * <ul>
011 * <li>Call {@link com.pusher.client.Pusher#subscribe(String)} to subscribe and
012 * receive an instance of {@link Channel}.</li>
013 * <li>Call {@link Channel#bind(String, SubscriptionEventListener)} to bind your
014 * listener to a specified event.</li>
015 * </ul>
016 *
017 * <p>
018 * Or, call
019 * {@link com.pusher.client.Pusher#subscribe(String, ChannelEventListener, String...)}
020 * to subscribe to a channel and bind your listener to one or more events at the
021 * same time.
022 * </p>
023 *
024 */
025public interface SubscriptionEventListener {
026
027    /**
028     * Callback that is fired whenever an event that this
029     * {@linkplain SubscriptionEventListener} has been bound to is received.
030     *
031     * @param channelName
032     *            The name of the channel that the event has been received on.
033     *            This is useful if your {@linkplain ChannelEventListener} has
034     *            been bound to events on more than one channel.
035     * @param eventName
036     *            The name of the event that has been received. This will always
037     *            be one of the events that your
038     *            {@linkplain ChannelEventListener} has been bound to.
039     * @param data
040     *            The JSON data that was included with the event. This can be
041     *            parsed with Google's Gson library, which is a dependency of
042     *            this library, or your library of choice.
043     */
044    void onEvent(String channelName, String eventName, String data);
045}