com.pusher.client
Class Pusher

java.lang.Object
  com.pusher.client.Pusher

public class Pusher
extends Object

This class is the main entry point for accessing Pusher.

By creating a new Pusher instance and calling Pusher.connect() a connection to Pusher is established.

Subscriptions for data are represented by Channel objects, or subclasses thereof. Subscriptions are created by calling #Pusher.subscribe(String), #Pusher.subscribePrivate(String), #Pusher.subscribePresence(String) or one of the overloads.

Constructor Summary

Pusher(String apiKey)
Creates a new instance of Pusher.

Pusher(String apiKey, PusherOptions pusherOptions)
Creates a new instance of Pusher.

Method Summary

void	connect() Connects to Pusher.
void	connect(ConnectionEventListener eventListener, ConnectionState... connectionStates) Binds a ConnectionEventListener to the specified events and then connects to Pusher.
void	disconnect() Disconnect from Pusher.
Connection	getConnection() Gets the underlying Connection object that is being used by this instance of Pusher.
Channel	subscribe(String channelName) Subscribes to a public Channel.
Channel	subscribe(String channelName, ChannelEventListener listener, String... eventNames) Binds a ChannelEventListener to the specified events and then subscribes to a public Channel.
PresenceChannel	subscribePresence(String channelName) Subscribes to a PresenceChannel which requires authentication.
PresenceChannel	subscribePresence(String channelName, PresenceChannelEventListener listener, String... eventNames) Subscribes to a PresenceChannel which requires authentication.
PrivateChannel	subscribePrivate(String channelName) Subscribes to a PrivateChannel which requires authentication.
PrivateChannel	subscribePrivate(String channelName, PrivateChannelEventListener listener, String... eventNames) Subscribes to a PrivateChannel which requires authentication.
void	unsubscribe(String channelName) Unsubscribes from a channel using via the name of the channel.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Pusher

public Pusher(String apiKey)

Creates a new instance of Pusher.

Note that if you use this constructor you will not be able to subscribe to private or presence channels because no Authorizer has been set. If you want to use private or presence channels:

• Create an implementation of the Authorizer interface, or use the HttpAuthorizer provided.
• Create an instance of PusherOptions and set the authorizer on it by calling PusherOptions.setAuthorizer(Authorizer).
• Use the Pusher(String, PusherOptions) constructor to create an instance of Pusher.

The PrivateChannelExampleApp and PresenceChannelExampleApp example applications show how to do this.

Parameters:

apiKey - Your Pusher API key.

Pusher

public Pusher(String apiKey,
              PusherOptions pusherOptions)

Creates a new instance of Pusher.

Parameters:

apiKey - Your Pusher API key.

pusherOptions - Options for the Pusher client library to use.

Method Detail

getConnection

public Connection getConnection()

Gets the underlying Connection object that is being used by this instance of Pusher.

Returns:

The Connection object.

connect

public void connect()

Connects to Pusher. Any ConnectionEventListeners that have already been registered using the Connection.bind(ConnectionState, ConnectionEventListener) method will receive connection events.

Calls are ignored (a connection is not attempted) if the Pusher.getConnection().getState() is not com.pusher.client.connection.ConnectionState.DISCONNECTED.

connect

public void connect(ConnectionEventListener eventListener,
                    ConnectionState... connectionStates)

Binds a ConnectionEventListener to the specified events and then connects to Pusher. This is equivalent to binding a ConnectionEventListener using the Connection.bind(ConnectionState, ConnectionEventListener) method before connecting.

Calls are ignored (a connection is not attempted) if the Pusher.getConnection().getState() is not com.pusher.client.connection.ConnectionState.DISCONNECTED.

Parameters:

eventListener - A ConnectionEventListener that will receive connection events. This can be null if you are not interested in receiving connection events, in which case you should call connect() instead of this method.

connectionStates - An optional list of ConnectionStates to bind your ConnectionEventListener to before connecting to Pusher. If you do not specify any ConnectionStates then your ConnectionEventListener will be bound to all connection events. This is equivalent to calling connect(ConnectionEventListener, ConnectionState...) with ConnectionState.ALL.

Throws:

IllegalArgumentException - If the ConnectionEventListener is null and at least one connection state has been specified.

disconnect

public void disconnect()

Disconnect from Pusher.

Calls are ignored if the Pusher.getConnection().getState() is not com.pusher.client.connection.ConnectionState.CONNECTED.

subscribe

public Channel subscribe(String channelName)

Subscribes to a public Channel.

Parameters:

channelName - The name of the Channel to subscribe to.

Returns:

The Channel object representing your subscription.

subscribe

public Channel subscribe(String channelName,
                         ChannelEventListener listener,
                         String... eventNames)

Binds a ChannelEventListener to the specified events and then subscribes to a public Channel.

Parameters:

channelName - The name of the Channel to subscribe to.

listener - A ChannelEventListener to receive events. This can be null if you don't want to bind a listener at subscription time, in which case you should call subscribe(String) instead of this method.

eventNames - An optional list of event names to bind your ChannelEventListener to before subscribing.

Returns:

The Channel object representing your subscription.

Throws:

IllegalArgumentException - If any of the following are true:

• The channel name is null.
• You are already subscribed to this channel.
• The channel name starts with "private-". If you want to subscribe to a private channel, call subscribePrivate(String, PrivateChannelEventListener, String...) instead of this method.
• At least one of the specified event names is null.
• You have specified at least one event name and your ChannelEventListener is null.

subscribePrivate

public PrivateChannel subscribePrivate(String channelName)

Subscribes to a PrivateChannel which requires authentication.

Parameters:

channelName - The name of the channel to subscribe to.

Returns:

A new PrivateChannel representing the subscription.

Throws:

IllegalStateException - if a Authorizer has not been set for the Pusher instance via Pusher(String, PusherOptions).

subscribePrivate

public PrivateChannel subscribePrivate(String channelName,
                                       PrivateChannelEventListener listener,
                                       String... eventNames)

Subscribes to a PrivateChannel which requires authentication.

Parameters:

channelName - The name of the channel to subscribe to.

listener - A listener to be informed of both Pusher channel protocol events and subscription data events.

eventNames - An optional list of names of events to be bound to on the channel. The equivalent of calling com.pusher.client.channel.Channel.bind(String, SubscriptionListener) on or more times.

Returns:

A new PrivateChannel representing the subscription.

Throws:

IllegalStateException - if a Authorizer has not been set for the Pusher instance via Pusher(String, PusherOptions).

subscribePresence

public PresenceChannel subscribePresence(String channelName)

Subscribes to a PresenceChannel which requires authentication.

Parameters:

channelName - The name of the channel to subscribe to.

Returns:

A new PresenceChannel representing the subscription.

Throws:

IllegalStateException - if a Authorizer has not been set for the Pusher instance via Pusher(String, PusherOptions).

subscribePresence

public PresenceChannel subscribePresence(String channelName,
                                         PresenceChannelEventListener listener,
                                         String... eventNames)

Subscribes to a PresenceChannel which requires authentication.

Parameters:

channelName - The name of the channel to subscribe to.

listener - A listener to be informed of Pusher channel protocol, including presence-specific events, and subscription data events.

eventNames - An optional list of names of events to be bound to on the channel. The equivalent of calling com.pusher.client.channel.Channel.bind(String, SubscriptionListener) on or more times.

Returns:

A new PresenceChannel representing the subscription.

Throws:

IllegalStateException - if a Authorizer has not been set for the Pusher instance via Pusher(String, PusherOptions).

unsubscribe

public void unsubscribe(String channelName)

Unsubscribes from a channel using via the name of the channel.

Parameters:

channelName - the name of the channel to be unsubscribed from.

Throws:

IllegalStateException - if Pusher.getConnection().getState() is not CONNECTED