Changed IChatManager.createChat(ID) to IChatManager.createChat(ID,IIMMessageListener). Changed signature of implementations also. Also created IChatRoomCreationEvent (event type sent to remote IIMMessageListeners for remote IChat).

This implements the basic API additions/changes for https://bugs.eclipse.org/bugs/show_bug.cgi?id=182474.

7 files changed, 134 insertions, 34 deletions

diff --git a/framework/bundles/org.eclipse.ecf.presence/src/org/eclipse/ecf/presence/chatroom/IChatRoomContainer.java b/framework/bundles/org.eclipse.ecf.presence/src/org/eclipse/ecf/presence/chatroom/IChatRoomContainer.java
index bf37bdb45..45b9a901e 100644
--- a/framework/bundles/org.eclipse.ecf.presence/src/org/eclipse/ecf/presence/chatroom/IChatRoomContainer.java
+++ b/framework/bundles/org.eclipse.ecf.presence/src/org/eclipse/ecf/presence/chatroom/IChatRoomContainer.java
@@ -15,7 +15,7 @@ import org.eclipse.ecf.presence.IIMMessageListener;
 import org.eclipse.ecf.presence.im.IChatMessageSender;
 
 /**
- * Container for chat rooms.
+ * A container representing a specific chat room.
  */
 public interface IChatRoomContainer extends IContainer {
 
@@ -50,13 +50,13 @@ public interface IChatRoomContainer extends IContainer {
 	 * Get interface for sending messages
 	 * 
 	 * @return IChatRoomMessageSender. Will be <code>null</code> if no message
-	 *         sender available
+	 *         sender available for the provider implementation.
 	 */
 	public IChatRoomMessageSender getChatRoomMessageSender();
 
 	/**
 	 * Add chat room participant listener. The given listener will be notified
-	 * if/when participants are added or removed from given room
+	 * if/when participants are added or removed from given room.
 	 * 
 	 * @param participantListener
 	 *            to add. Must not be <code>null</code>.
diff --git a/framework/bundles/org.eclipse.ecf.presence/src/org/eclipse/ecf/presence/im/ChatMessageEvent.java b/framework/bundles/org.eclipse.ecf.presence/src/org/eclipse/ecf/presence/im/ChatMessageEvent.java
index e30bfe672..2a97aac22 100644
--- a/framework/bundles/org.eclipse.ecf.presence/src/org/eclipse/ecf/presence/im/ChatMessageEvent.java
+++ b/framework/bundles/org.eclipse.ecf.presence/src/org/eclipse/ecf/presence/im/ChatMessageEvent.java
@@ -22,10 +22,16 @@ public class ChatMessageEvent implements IChatMessageEvent {
 
 	protected ID fromID;
 	protected IChatMessage message;
-
-	public ChatMessageEvent(ID fromID, IChatMessage message) {
+    protected IChat chat;
+    
+	public ChatMessageEvent(ID fromID, IChatMessage message, IChat chat) {
 		this.fromID = fromID;
 		this.message = message;
+		this.chat = chat;
+	}
+
+	public ChatMessageEvent(ID fromID, IChatMessage message) {
+		this(fromID,message,null);
 	}
 
 	/*
@@ -46,6 +52,13 @@ public class ChatMessageEvent implements IChatMessageEvent {
 		return message;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.ecf.presence.im.IChatMessageEvent#getChat()
+	 */
+	public IChat getChat() {
+		return chat;
+	}
+	
 	/*
 	 * (non-Javadoc)
 	 * 
@@ -54,7 +67,8 @@ public class ChatMessageEvent implements IChatMessageEvent {
 	public String toString() {
 		StringBuffer buf = new StringBuffer("ChatMessageEvent["); //$NON-NLS-1$
 		buf.append("fromID=").append(getFromID()); //$NON-NLS-1$
-		buf.append(";message=").append(message).append("]"); //$NON-NLS-1$ //$NON-NLS-2$
+		buf.append(";message=").append(message);
+		buf.append(";chat=").append(chat).append("]"); //$NON-NLS-1$ //$NON-NLS-2$
 		return buf.toString();
 	}
 
diff --git a/framework/bundles/org.eclipse.ecf.presence/src/org/eclipse/ecf/presence/im/IChat.java b/framework/bundles/org.eclipse.ecf.presence/src/org/eclipse/ecf/presence/im/IChat.java
index 5b76cd8ab..d20df1d75 100644
--- a/framework/bundles/org.eclipse.ecf.presence/src/org/eclipse/ecf/presence/im/IChat.java
+++ b/framework/bundles/org.eclipse.ecf.presence/src/org/eclipse/ecf/presence/im/IChat.java
@@ -13,16 +13,20 @@ package org.eclipse.ecf.presence.im;
 
 import java.util.Map;
 
+import org.eclipse.core.runtime.IAdaptable;
 import org.eclipse.ecf.core.ContainerCreateException;
+import org.eclipse.ecf.core.IContainer;
 import org.eclipse.ecf.core.identity.ID;
 import org.eclipse.ecf.core.util.ECFException;
+import org.eclipse.ecf.presence.IIMMessageListener;
 import org.eclipse.ecf.presence.IPresenceContainerAdapter;
 import org.eclipse.ecf.presence.chatroom.IChatRoomContainer;
 
 /**
- * Object representing a specific two-way chat.
+ * A two-person chat. Instances are created via
+ * {@link IChatManager#createChat(ID, org.eclipse.ecf.presence.IIMMessageListener).
  */
-public interface IChat {
+public interface IChat extends IAdaptable {
 
 	/**
 	 * Get the receiver for this chat.
@@ -67,32 +71,53 @@ public interface IChat {
 	 * @param messageBody
 	 *            the body of the message to send. May be <code>null</code>.
 	 * @throws ECFException
-	 *             thrown if currently disconnected or some transport error
+	 *             thrown if disconnected or some transport error.
 	 */
 	public void sendChatMessage(String messageBody) throws ECFException;
 
 	/**
-	 * Get typing message sender. If sending typing messages not supported by
-	 * this provider then <code>null</code> will be returned.
+	 * Send typing message to a remote receiver.
+	 * 
+	 * @param isTyping
+	 *            true if user is typing, false if they've stopped typing.
 	 * 
-	 * @return ITypingMessageSender to use for sending typing messages
-	 *         (instances of ITypingMessage). If <code>null</code>, sending
-	 *         typing messages not supported by this provider.
+	 * @param body
+	 *            the content of what has been/is being typed. May be
+	 *            <code>null</code>.
+	 * 
+	 * @throws ECFException
+	 *             thrown if disconnected or some other communications error.
 	 */
-	public ITypingMessageSender getTypingMessageSender();
-	
+	public void sendTypingMessage(boolean isTyping, String body)
+			throws ECFException;
+
 	/**
-	 * Create a new IChatRoomContainer instance. This method can be used to
-	 * create to a chat room identified by this two-way chat. If supported by
-	 * the provider, this allows moving from a two-way chat represented by this
-	 * IChat instance to an n-way chat room container.
+	 * Create a new IChatRoomContainer instance from this chat. This method can
+	 * be used to convert this two-way chat into an n-way chat room. If not
+	 * supported by the provider, this method should return <code>null</code>.
+	 * <p>
+	 * </p>
+	 * If supported by the provider, this allows moving from a two-way chat
+	 * represented by this IChat instance to an n-way chat room container. The
+	 * initial set of participants will be the two participants in this two way
+	 * chat, and the {@link IContainer#getConnectedID()} will be non-null, and
+	 * equal to {@link IChat#getThreadID()}.
+	 * <p>
+	 * </p>
+	 * If this method is called succesfully (no exception and non-<code>null</code>
+	 * instance returned) then the other participant in this IChat (i.e.
+	 * identified by the {@link IChat#getReceiverID()} will be notified
+	 * asynchronously via the delivery of an {@link IChatRoomCreationEvent} to
+	 * the {@link IIMMessageListener} for the remote {@link IChat} instance.
 	 * 
-	 * @return non-null IChatRoomContainer instance. Will not return
-	 *         <code>null</code>.
+	 * @return a new IChatRoomContainer instance. Will return <code>null</code>
+	 *         if underlying provider does not support this functionality.
 	 * @throws ContainerCreateException
-	 *             if chat room container cannot be made.
+	 *             if chat room container cannot be made (e.g. due to
+	 *             disconnection or other failure).
 	 */
-	public IChatRoomContainer createChatRoom() throws ContainerCreateException;
+	public IChatRoomContainer createChatRoomContainer()
+			throws ContainerCreateException;
 
 	/**
 	 * Get presence container adapter for this chat instance.
@@ -101,4 +126,11 @@ public interface IChat {
 	 *         <code>null</code>.
 	 */
 	public IPresenceContainerAdapter getPresenceContainerAdapter();
+
+	/**
+	 * Dispose this chat, making it incapable of receiving any more messages or
+	 * being the source of any more messages. Also results in removing any
+	 * listeners associated with this chat.
+	 */
+	public void dispose();
 }
diff --git a/framework/bundles/org.eclipse.ecf.presence/src/org/eclipse/ecf/presence/im/IChatManager.java b/framework/bundles/org.eclipse.ecf.presence/src/org/eclipse/ecf/presence/im/IChatManager.java
index 5b921eb5a..da5df5f9c 100644
--- a/framework/bundles/org.eclipse.ecf.presence/src/org/eclipse/ecf/presence/im/IChatManager.java
+++ b/framework/bundles/org.eclipse.ecf.presence/src/org/eclipse/ecf/presence/im/IChatManager.java
@@ -57,23 +57,34 @@ public interface IChatManager {
 	 *         typing messages not supported by this provider.
 	 */
 	public ITypingMessageSender getTypingMessageSender();
-	
+
 	/**
 	 * Get the history manager for this chat manager.
-	 * @return IChatRoomHistoryManager the history manager instance.  Will not be <code>null</code>.
+	 * 
+	 * @return IChatRoomHistoryManager the history manager instance. Will not be
+	 *         <code>null</code>.
 	 */
 	public IHistoryManager getHistoryManager();
 
 	/**
 	 * Create chat instance for given target user.
 	 * 
-	 * @param targetUser the targetUser to create chat for.  Should not be <code>null</code>.
-	 * If the user container is offline/disconnected. then an {@link ECFException} will
-	 * be thrown.  If this chat manager implementation does not support creating such chats,
-	 * then <code>null</code> will be returned.
+	 * @param targetUser
+	 *            the targetUser to create chat for. Must not be
+	 *            <code>null</code>. If the user container is
+	 *            offline/disconnected. then an {@link ECFException} will be
+	 *            thrown. If this chat manager implementation does not support
+	 *            creating such chats, then <code>null</code> will be
+	 *            returned.
+	 * 
+	 * @param messageListener
+	 *            the message listener to listen for messages. Must not be
+	 *            <code>null</code>.
 	 * 
-	 * @return IChat for given <code>targetUser</code>.  Will return <code>null</code> if
-	 * the underlying implementation does not support threads/specific chat instances.
+	 * @return IChat for given <code>targetUser</code>. Will return
+	 *         <code>null</code> if the underlying implementation does not
+	 *         support threads/specific chat instances.
 	 */
-	public IChat createChat(ID targetUser) throws ECFException;
+	public IChat createChat(ID targetUser, IIMMessageListener messageListener)
+			throws ECFException;
 }
diff --git a/framework/bundles/org.eclipse.ecf.presence/src/org/eclipse/ecf/presence/im/IChatMessage.java b/framework/bundles/org.eclipse.ecf.presence/src/org/eclipse/ecf/presence/im/IChatMessage.java
index 7222fc10f..15178fad0 100644
--- a/framework/bundles/org.eclipse.ecf.presence/src/org/eclipse/ecf/presence/im/IChatMessage.java
+++ b/framework/bundles/org.eclipse.ecf.presence/src/org/eclipse/ecf/presence/im/IChatMessage.java
@@ -17,7 +17,7 @@ import org.eclipse.ecf.core.identity.ID;
 import org.eclipse.ecf.presence.IIMMessage;
 
 /**
- * Chat message. This is the message class received in when another user sends a
+ * Chat message. This is the message received when another user sends a
  * chat message to us.
  */
 public interface IChatMessage extends IIMMessage {
diff --git a/framework/bundles/org.eclipse.ecf.presence/src/org/eclipse/ecf/presence/im/IChatMessageEvent.java b/framework/bundles/org.eclipse.ecf.presence/src/org/eclipse/ecf/presence/im/IChatMessageEvent.java
index d38d114f2..98aa5037f 100644
--- a/framework/bundles/org.eclipse.ecf.presence/src/org/eclipse/ecf/presence/im/IChatMessageEvent.java
+++ b/framework/bundles/org.eclipse.ecf.presence/src/org/eclipse/ecf/presence/im/IChatMessageEvent.java
@@ -25,4 +25,11 @@ public interface IChatMessageEvent extends IIMMessageEvent {
 	 */
 	public IChatMessage getChatMessage();
 
+	/**
+	 * Get chat associated with this chat message event.
+	 * 
+	 * @return IChat associated with this chat message event.  May be <code>null</code> if
+	 * provider does not support having an IChat.
+	 */
+	public IChat getChat();
 }
diff --git a/framework/bundles/org.eclipse.ecf.presence/src/org/eclipse/ecf/presence/im/IChatRoomCreationEvent.java b/framework/bundles/org.eclipse.ecf.presence/src/org/eclipse/ecf/presence/im/IChatRoomCreationEvent.java
new file mode 100644
index 000000000..17593d435
--- /dev/null
+++ b/framework/bundles/org.eclipse.ecf.presence/src/org/eclipse/ecf/presence/im/IChatRoomCreationEvent.java
@@ -0,0 +1,36 @@
+/****************************************************************************
+ * Copyright (c) 2004 Composent, Inc. and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
+ *    Composent, Inc. - initial API and implementation
+ *****************************************************************************/
+
+package org.eclipse.ecf.presence.im;
+
+import org.eclipse.ecf.core.util.ECFException;
+import org.eclipse.ecf.presence.IIMMessageEvent;
+import org.eclipse.ecf.presence.IIMMessageListener;
+import org.eclipse.ecf.presence.chatroom.IChatRoomContainer;
+
+/**
+ * Event received via {@link IIMMessageListener} when remote
+ * chat has been converted into a chat room.
+ */
+public interface IChatRoomCreationEvent extends IIMMessageEvent {
+
+	/**
+	 * Get the chat room container associated with the new chat room
+	 * created by remote.
+	 * 
+	 * @return IChatRoomContainer created by remote.  Will not be <code>null</code>.
+	 * 
+	 * @throws ECFException if chatroom container cannot be created...e.g. due
+	 * to container disconnect.
+	 */
+	public IChatRoomContainer getChatRoomContainer() throws ECFException;
+	
+}