001package com.pusher.client.connection;
002
003/**
004 * Client applications should implement this interface if they wish to receive
005 * notifications when the state of a {@link Connection} changes or an error is
006 * thrown.
007 *
008 * <p>
009 * Implementations of this interface can be bound to the connection by calling
010 * {@link Connection#bind(ConnectionState, ConnectionEventListener)}. The
011 * connection itself can be retrieved from the {@link com.pusher.client.Pusher}
012 * object by calling {@link com.pusher.client.Pusher#getConnection()}.
013 * </p>
014 *
015 * <p>
016 * Alternatively, you can bind your implementation of the interface and connect
017 * at the same time by calling
018 * {@link com.pusher.client.Pusher#connect(ConnectionEventListener, ConnectionState...)}
019 * .
020 * </p>
021 */
022public interface ConnectionEventListener {
023
024    /**
025     * Callback that is fired whenever the {@link ConnectionState} of the
026     * {@link Connection} changes. The state typically changes during connection
027     * to Pusher and during disconnection and reconnection.
028     *
029     * <p>
030     * This callback is only fired if the {@linkplain ConnectionEventListener}
031     * has been bound to the new state by calling
032     * {@link Connection#bind(ConnectionState, ConnectionEventListener)} with
033     * either the new state or {@link ConnectionState#ALL}.
034     * </p>
035     *
036     * @param change An object that contains the previous state of the connection
037     *            and the new state. The new state can be retrieved by calling
038     *            {@link ConnectionStateChange#getCurrentState()}.
039     */
040    void onConnectionStateChange(ConnectionStateChange change);
041
042    /**
043     * Callback that indicates either:
044     * <ul>
045     * <li>An error message has been received from Pusher, or</li>
046     * <li>An error has occurred in the client library.</li>
047     * </ul>
048     *
049     * <p>
050     * All {@linkplain ConnectionEventListener}s that have been registered by
051     * calling {@link Connection#bind(ConnectionState, ConnectionEventListener)}
052     * will receive this callback, even if the
053     * {@linkplain ConnectionEventListener} is only bound to specific connection
054     * status changes.
055     * </p>
056     *
057     * @param message
058     *            A message indicating the cause of the error.
059     * @param code
060     *            The error code for the message. Can be null.
061     * @param e
062     *            The exception that was thrown, if any. Can be null.
063     */
064    void onError(String message, String code, Exception e);
065}