001package com.pusher.client.user;
002
003import com.pusher.client.channel.SubscriptionEventListener;
004
005/**
006 * An object that represents a user on a Pusher connection. An implementation of this
007 * interface is returned when you call {@link com.pusher.client.Pusher#user()}.
008 */
009public interface User {
010    /**
011     * @return The user id of the signed in user. Null if no user is signed in;
012     */
013    String userId();
014
015    /**
016     * Binds a {@link SubscriptionEventListener} to an event. The
017     * {@link SubscriptionEventListener} will be notified whenever the specified
018     * event is received for this user.
019     *
020     * @param eventName The name of the event to listen to.
021     * @param listener  A listener to receive notifications when the event is
022     *                  received.
023     * @throws IllegalArgumentException If either of the following are true:
024     *                                  <ul>
025     *                                  <li>The name of the event is null.</li>
026     *                                  <li>The {@link SubscriptionEventListener} is null.</li>
027     *                                  </ul>
028     */
029    void bind(String eventName, SubscriptionEventListener listener);
030
031    /**
032     * Binds a {@link SubscriptionEventListener} to all events. The
033     * {@link SubscriptionEventListener} will be notified whenever an
034     * event is received for this user.
035     *
036     * @param listener A listener to receive notifications when the event is
037     *                 received.
038     * @throws IllegalArgumentException If the {@link SubscriptionEventListener} is null.
039     */
040    void bindGlobal(SubscriptionEventListener listener);
041
042    /**
043     * <p>
044     * Unbinds a previously bound {@link SubscriptionEventListener} from an
045     * event. The {@link SubscriptionEventListener} will no longer be notified
046     * whenever the specified event is received for this user.
047     * </p>
048     *
049     * @param eventName The name of the event to stop listening to.
050     * @param listener  The listener to unbind from the event.
051     * @throws IllegalArgumentException If either of the following are true:
052     *                                  <ul>
053     *                                  <li>The name of the event is null.</li>
054     *                                  <li>The {@link SubscriptionEventListener} is null.</li>
055     *                                  </ul>
056     */
057    void unbind(String eventName, SubscriptionEventListener listener);
058
059    /**
060     * <p>
061     * Unbinds a previously bound {@link SubscriptionEventListener} from global
062     * events. The {@link SubscriptionEventListener} will no longer be notified
063     * whenever the any event is received for this user.
064     * </p>
065     *
066     * @param listener The listener to unbind from the event.
067     * @throws IllegalArgumentException If the {@link SubscriptionEventListener} is null.
068     */
069    void unbindGlobal(SubscriptionEventListener listener);
070}