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     * Callback that is fired whenever the {@link ConnectionState} of the
025     * {@link Connection} changes. The state typically changes during connection
026     * to Pusher and during disconnection and reconnection.
027     *
028     * <p>
029     * This callback is only fired if the {@linkplain ConnectionEventListener}
030     * has been bound to the new state by calling
031     * {@link Connection#bind(ConnectionState, ConnectionEventListener)} with
032     * either the new state or {@link ConnectionState#ALL}.
033     * </p>
034     *
035     * @param change An object that contains the previous state of the connection
036     *               and the new state. The new state can be retrieved by calling
037     *               {@link ConnectionStateChange#getCurrentState()}.
038     */
039    void onConnectionStateChange(ConnectionStateChange change);
040
041    /**
042     * Callback that indicates either:
043     * <ul>
044     * <li>An error message has been received from Pusher, or</li>
045     * <li>An error has occurred in the client library.</li>
046     * </ul>
047     *
048     * <p>
049     * All {@linkplain ConnectionEventListener}s that have been registered by
050     * calling {@link Connection#bind(ConnectionState, ConnectionEventListener)}
051     * will receive this callback, even if the
052     * {@linkplain ConnectionEventListener} is only bound to specific connection
053     * status changes.
054     * </p>
055     *
056     * @param message A message indicating the cause of the error.
057     * @param code    The error code for the message. Can be null.
058     * @param e       The exception that was thrown, if any. Can be null.
059     */
060    void onError(String message, String code, Exception e);
061}