im/engine/ImConnection.java

/*
 * Copyright (C) 2007-2008 Esmertec AG.
 * Copyright (C) 2007-2008 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.android.im.engine;

import java.util.HashMap;
import java.util.concurrent.CopyOnWriteArrayList;

/**
 * An <code>ImConnection</code> is an abstract representation of a connection
 * to the IM server.
 */
public abstract class ImConnection {
    /**
     * Connection state that indicates the connection is not connected yet.
     */
    public static final int DISCONNECTED = 0;

    /**
     * Connection state that indicates the user is logging into the server.
     */
    public static final int LOGGING_IN = 1;

    /**
     * Connection state that indicates the user has logged into the server.
     */
    public static final int LOGGED_IN = 2;

    /**
     * Connection state that indicates the user is logging out the server.
     */
    public static final int LOGGING_OUT = 3;

    /**
     * Connection state that indicate the connection is suspending.
     */
    public static final int SUSPENDING = 4;

    /**
     * Connection state that indicate the connection has been suspended.
     */
    public static final int SUSPENDED = 5;

    /**
     * The capability of supporting group chat.
     */
    public static final int CAPABILITY_GROUP_CHAT = 1;
    /**
     * The capability of supporting session re-establishment.
     */
    public static final int CAPABILITY_SESSION_REESTABLISHMENT = 2;

    /**
     * The current state of the connection.
     */
    protected int mState;

    protected CopyOnWriteArrayList<ConnectionListener> mConnectionListeners;
    protected Presence mUserPresence;

    protected ImConnection() {
        mConnectionListeners = new CopyOnWriteArrayList<ConnectionListener>();
        mState = DISCONNECTED;
    }

    public void addConnectionListener(ConnectionListener listener) {
        if (listener != null) {
            mConnectionListeners.add(listener);
        }
    }

    public void removeConnectionListener(ConnectionListener listener) {
        mConnectionListeners.remove(listener);
    }

    public abstract Contact getLoginUser();

    public String getLoginUserName() {
        Contact loginUser = getLoginUser();
        return loginUser == null ? null : loginUser.getName();
    }

    public abstract int[] getSupportedPresenceStatus();

    public Presence getUserPresence() {
        if (mState == SUSPENDING || mState == SUSPENDED) {
            return new Presence();
        }

        if (mState != LOGGED_IN) {
            // In most cases we have a valid mUserPresence instance also
            // in the LOGGING_OUT state. However there is one exception:
            // if logout() is called before login finishes, the state may
            // jump from LOGGING_IN directly to LOGGING_OUT, skipping the
            // LOGGED_IN state. In this case we won't have a valid Presence
            // in the LOGGING_OUT state.
            return null;
        }

        return new Presence(mUserPresence);
    }

    public void updateUserPresenceAsync(Presence newPresence) throws ImException {
        if (mState != LOGGED_IN) {
            throw new ImException(ImErrorInfo.NOT_LOGGED_IN, "NOT logged in");
        }

        doUpdateUserPresenceAsync(newPresence);
    }

    /**
     * Tells the engine that the network type has changed, e.g. switch from gprs
     * to wifi. The engine should drop all the network connections created before
     * because they are not available anymore.
     *
     * The engine might also need to redo authentication on the new network depending
     * on the underlying protocol.
     */
    public void networkTypeChanged(){
    }

    /**
     * Tells the current state of the connection.
     */
    public int getState() {
        return mState;
    }

    /**
     * Sets the state of the connection.
     *
     * @param state the new state of the connection.
     * @param error the error information which caused the state change or null.
     */
    protected void setState(int state, ImErrorInfo error) {
        if(state < DISCONNECTED || state > SUSPENDED){
            throw new IllegalArgumentException("Invalid state: " + state);
        }
        if(mState != state){
            mState = state;
            for(ConnectionListener listener : mConnectionListeners){
                listener.onStateChanged(state, error);
            }
        }
    }

    protected void notifyUserPresenceUpdated() {
        for (ConnectionListener listener : mConnectionListeners) {
            listener.onUserPresenceUpdated();
        }
    }

    protected void notifyUpdateUserPresenceError(ImErrorInfo error) {
        for (ConnectionListener listener : mConnectionListeners) {
            listener.onUpdatePresenceError(error);
        }
    }

    /**
     * Gets bit-or of capabilities supported by the underlying protocol. Valid
     * capability bits are: {@value #CAPABILITY_GROUP_CHAT},
     * {@value #CAPABILITY_SESSION_REESTABLISHMENT}
     *
     * @return bit-or of capabilities supported by the underlying protocol
     */
    public abstract int getCapability();

    /**
     * Log in to the IM server.
     *
     * @param loginInfo the login information.
     */
    public abstract void loginAsync(LoginInfo loginInfo);

    /**
     * Re-establish previous session using the session context persisted by the
     * client. Only sessions that were dropped unexpectedly(e.g. power loss, crash,
     * etc) can be re-established using the stored session context. If the
     * session was terminated normally by either user logging out or server
     * initiated disconnection, it can't be re-established again therefore the
     * stored context should be removed by the client.
     * <p>
     * The client can query if session re-establishment is supported through
     * {@link #getCapability()}.
     *
     * @param sessionContext
     *            the session context which was fetched from previous session by
     *            {@link #getSessionContext()} and persisted by the client.
     * @throws UnsupportedOperationException
     *             if session re-establishment is not supported by the
     *             underlying protocol.
     */
    public abstract void reestablishSessionAsync(HashMap<String, String> sessionContext);

    /**
     * Log out from the IM server.
     */
    public abstract void logoutAsync();

    /**
     * Suspend connection with the IM server.
     */
    public abstract void suspend();

    /**
     * Gets the cookie of the current session. The client could store the
     * context and use it to re-establish the session by
     * {@link #reestablishSessionAsync(HashMap)}}. The stored context MUST be
     * removed upon the connection logout/disconnect.
     *
     * @return the context of the current session or <code>null</code> if the
     *         user has not logged in yet.
     * @throws UnsupportedOperationException
     *             if session re-establishment is not supported by the
     *             underlying protocol.
     */
    public abstract HashMap<String, String> getSessionContext();

    /**
     * Gets the instance of ChatSessionManager for the connection.
     *
     * @return the instance of ChatSessionManager for the connection.
     */
    public abstract ChatSessionManager getChatSessionManager();

    /**
     * Gets the instance of ContactListManager for the connection.
     *
     * @return the instance of ContactListManager for the connection.
     */
    public abstract ContactListManager getContactListManager();

    /**
     * Gets the instance of ChatGroupManager for the connection.
     *
     * @return the instance of ChatGroupManager for the connection.
     * @throws UnsupportedOperationException
     *             if group chat is not supported by the underlying protocol.
     */
    public abstract ChatGroupManager getChatGroupManager();

    protected abstract void doUpdateUserPresenceAsync(Presence presence);

}