001package com.pusher.client.channel; 002 003/** 004 * An object that represents a Pusher channel. An implementation of this 005 * interface is returned when you call 006 * {@link com.pusher.client.Pusher#subscribe(String)} or 007 * {@link com.pusher.client.Pusher#subscribe(String, ChannelEventListener, String...)} 008 * . 009 */ 010public interface Channel { 011 /** 012 * Gets the name of the Pusher channel that this object represents. 013 * 014 * @return The name of the channel. 015 */ 016 String getName(); 017 018 /** 019 * Binds a {@link SubscriptionEventListener} to an event. The 020 * {@link SubscriptionEventListener} will be notified whenever the specified 021 * event is received on this channel. 022 * 023 * @param eventName The name of the event to listen to. 024 * @param listener A listener to receive notifications when the event is 025 * received. 026 * @throws IllegalArgumentException If either of the following are true: 027 * <ul> 028 * <li>The name of the event is null.</li> 029 * <li>The {@link SubscriptionEventListener} is null.</li> 030 * </ul> 031 * @throws IllegalStateException If the channel has been unsubscribed by calling 032 * {@link com.pusher.client.Pusher#unsubscribe(String)}. This 033 * puts the {@linkplain Channel} in a terminal state from which 034 * it can no longer be used. To resubscribe, call 035 * {@link com.pusher.client.Pusher#subscribe(String)} or 036 * {@link com.pusher.client.Pusher#subscribe(String, ChannelEventListener, String...)} 037 * again to receive a fresh {@linkplain Channel} instance. 038 */ 039 void bind(String eventName, SubscriptionEventListener listener); 040 041 /** 042 * Binds a {@link SubscriptionEventListener} to all events. The 043 * {@link SubscriptionEventListener} will be notified whenever an 044 * event is received on this channel. 045 * 046 * @param listener A listener to receive notifications when the event is 047 * received. 048 * @throws IllegalArgumentException If the {@link SubscriptionEventListener} is null. 049 * @throws IllegalStateException If the channel has been unsubscribed by calling 050 * {@link com.pusher.client.Pusher#unsubscribe(String)}. This 051 * puts the {@linkplain Channel} in a terminal state from which 052 * it can no longer be used. To resubscribe, call 053 * {@link com.pusher.client.Pusher#subscribe(String)} or 054 * {@link com.pusher.client.Pusher#subscribe(String, ChannelEventListener, String...)} 055 * again to receive a fresh {@linkplain Channel} instance. 056 */ 057 void bindGlobal(SubscriptionEventListener listener); 058 059 /** 060 * <p> 061 * Unbinds a previously bound {@link SubscriptionEventListener} from an 062 * event. The {@link SubscriptionEventListener} will no longer be notified 063 * whenever the specified event is received on this channel. 064 * </p> 065 * 066 * <p> 067 * Calling this method does not unsubscribe from the channel even if there 068 * are no more {@link SubscriptionEventListener}s bound to it. If you want 069 * to unsubscribe from the channel completely, call 070 * {@link com.pusher.client.Pusher#unsubscribe(String)}. It is not necessary 071 * to unbind your {@link SubscriptionEventListener}s first. 072 * </p> 073 * 074 * @param eventName The name of the event to stop listening to. 075 * @param listener The listener to unbind from the event. 076 * @throws IllegalArgumentException If either of the following are true: 077 * <ul> 078 * <li>The name of the event is null.</li> 079 * <li>The {@link SubscriptionEventListener} is null.</li> 080 * </ul> 081 * @throws IllegalStateException If the channel has been unsubscribed by calling 082 * {@link com.pusher.client.Pusher#unsubscribe(String)}. This 083 * puts the {@linkplain Channel} in a terminal state from which 084 * it can no longer be used. To resubscribe, call 085 * {@link com.pusher.client.Pusher#subscribe(String)} or 086 * {@link com.pusher.client.Pusher#subscribe(String, ChannelEventListener, String...)} 087 * again to receive a fresh {@linkplain Channel} instance. 088 */ 089 void unbind(String eventName, SubscriptionEventListener listener); 090 091 /** 092 * <p> 093 * Unbinds a previously bound {@link SubscriptionEventListener} from global 094 * events. The {@link SubscriptionEventListener} will no longer be notified 095 * whenever the any event is received on this channel. 096 * </p> 097 * 098 * <p> 099 * Calling this method does not unsubscribe from the channel even if there 100 * are no more {@link SubscriptionEventListener}s bound to it. If you want 101 * to unsubscribe from the channel completely, call 102 * {@link com.pusher.client.Pusher#unsubscribe(String)}. It is not necessary 103 * to unbind your {@link SubscriptionEventListener}s first. 104 * </p> 105 * 106 * @param listener The listener to unbind from the event. 107 * @throws IllegalArgumentException If the {@link SubscriptionEventListener} is null. 108 * @throws IllegalStateException If the channel has been unsubscribed by calling 109 * {@link com.pusher.client.Pusher#unsubscribe(String)}. This 110 * puts the {@linkplain Channel} in a terminal state from which 111 * it can no longer be used. To resubscribe, call 112 * {@link com.pusher.client.Pusher#subscribe(String)} or 113 * {@link com.pusher.client.Pusher#subscribe(String, ChannelEventListener, String...)} 114 * again to receive a fresh {@linkplain Channel} instance. 115 */ 116 void unbindGlobal(SubscriptionEventListener listener); 117 118 /** 119 * @return Whether or not the channel is subscribed. 120 */ 121 boolean isSubscribed(); 122}