com.pusher.client.channel.Channel Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of pusher-java-client Show documentation
This is a Java client library for Pusher, targeted at core Java and Android.
The newest version!
package com.pusher.client.channel;

/**
 * An object that represents a Pusher channel. An implementation of this
 * interface is returned when you call
 * {@link com.pusher.client.Pusher#subscribe(String)} or
 * {@link com.pusher.client.Pusher#subscribe(String, ChannelEventListener, String...)}
 * .
 */
public interface Channel {
    /**
     * Gets the name of the Pusher channel that this object represents.
     *
     * @return The name of the channel.
     */
    String getName();

    /**
     * Binds a {@link SubscriptionEventListener} to an event. The
     * {@link SubscriptionEventListener} will be notified whenever the specified
     * event is received on this channel.
     *
     * @param eventName The name of the event to listen to.
     * @param listener  A listener to receive notifications when the event is
     *                  received.
     * @throws IllegalArgumentException If either of the following are true:
     *                                  
     *                                  The name of the event is null.
     *                                  The {@link SubscriptionEventListener} is null.
     *                                  
     * @throws IllegalStateException    If the channel has been unsubscribed by calling
     *                                  {@link com.pusher.client.Pusher#unsubscribe(String)}. This
     *                                  puts the {@linkplain Channel} in a terminal state from which
     *                                  it can no longer be used. To resubscribe, call
     *                                  {@link com.pusher.client.Pusher#subscribe(String)} or
     *                                  {@link com.pusher.client.Pusher#subscribe(String, ChannelEventListener, String...)}
     *                                  again to receive a fresh {@linkplain Channel} instance.
     */
    void bind(String eventName, SubscriptionEventListener listener);

    /**
     * Binds a {@link SubscriptionEventListener} to all events. The
     * {@link SubscriptionEventListener} will be notified whenever an
     * event is received on this channel.
     *
     * @param listener A listener to receive notifications when the event is
     *                 received.
     * @throws IllegalArgumentException If the {@link SubscriptionEventListener} is null.
     * @throws IllegalStateException    If the channel has been unsubscribed by calling
     *                                  {@link com.pusher.client.Pusher#unsubscribe(String)}. This
     *                                  puts the {@linkplain Channel} in a terminal state from which
     *                                  it can no longer be used. To resubscribe, call
     *                                  {@link com.pusher.client.Pusher#subscribe(String)} or
     *                                  {@link com.pusher.client.Pusher#subscribe(String, ChannelEventListener, String...)}
     *                                  again to receive a fresh {@linkplain Channel} instance.
     */
    void bindGlobal(SubscriptionEventListener listener);

    /**
     * 
     * Unbinds a previously bound {@link SubscriptionEventListener} from an
     * event. The {@link SubscriptionEventListener} will no longer be notified
     * whenever the specified event is received on this channel.
     * 
     *
     * 
     * Calling this method does not unsubscribe from the channel even if there
     * are no more {@link SubscriptionEventListener}s bound to it. If you want
     * to unsubscribe from the channel completely, call
     * {@link com.pusher.client.Pusher#unsubscribe(String)}. It is not necessary
     * to unbind your {@link SubscriptionEventListener}s first.
     * 
     *
     * @param eventName The name of the event to stop listening to.
     * @param listener  The listener to unbind from the event.
     * @throws IllegalArgumentException If either of the following are true:
     *                                  
     *                                  The name of the event is null.
     *                                  The {@link SubscriptionEventListener} is null.
     *                                  
     * @throws IllegalStateException    If the channel has been unsubscribed by calling
     *                                  {@link com.pusher.client.Pusher#unsubscribe(String)}. This
     *                                  puts the {@linkplain Channel} in a terminal state from which
     *                                  it can no longer be used. To resubscribe, call
     *                                  {@link com.pusher.client.Pusher#subscribe(String)} or
     *                                  {@link com.pusher.client.Pusher#subscribe(String, ChannelEventListener, String...)}
     *                                  again to receive a fresh {@linkplain Channel} instance.
     */
    void unbind(String eventName, SubscriptionEventListener listener);

    /**
     * 
     * Unbinds a previously bound {@link SubscriptionEventListener} from global
     * events. The {@link SubscriptionEventListener} will no longer be notified
     * whenever the any event is received on this channel.
     * 
     *
     * 
     * Calling this method does not unsubscribe from the channel even if there
     * are no more {@link SubscriptionEventListener}s bound to it. If you want
     * to unsubscribe from the channel completely, call
     * {@link com.pusher.client.Pusher#unsubscribe(String)}. It is not necessary
     * to unbind your {@link SubscriptionEventListener}s first.
     * 
     *
     * @param listener The listener to unbind from the event.
     * @throws IllegalArgumentException If the {@link SubscriptionEventListener} is null.
     * @throws IllegalStateException    If the channel has been unsubscribed by calling
     *                                  {@link com.pusher.client.Pusher#unsubscribe(String)}. This
     *                                  puts the {@linkplain Channel} in a terminal state from which
     *                                  it can no longer be used. To resubscribe, call
     *                                  {@link com.pusher.client.Pusher#subscribe(String)} or
     *                                  {@link com.pusher.client.Pusher#subscribe(String, ChannelEventListener, String...)}
     *                                  again to receive a fresh {@linkplain Channel} instance.
     */
    void unbindGlobal(SubscriptionEventListener listener);

    /**
     * @return Whether or not the channel is subscribed.
     */
    boolean isSubscribed();
}