src/com/android/im/engine/ImConnection.java - platform/packages/apps/IM - Git at Google

 /*
  * 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);

 }
	/*
	* 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);

	}