If you're planning to use emite, this guide is for you.

This doc is a little out of date. Please take a look to the chat example: com.calclab.emite.examples.chat.client.ChatEntryPoint. There is all the logic to implement a simple chat with roster and conversations.

Create the xmpp object

All the interaction with emite is done thought the xmpp facade object. This is the way to obtain it:

Xmpp xmpp = Xmpp.create(new BoshOptions("http-bind", "localhost"));

We need to give the httpBase (where our server proxy is located) and the server domain name. Take a look to the BoshOptions class to know what parameters are susceptible of configuration.

The xmpp object provides references to different "managers" (ie: ChatManager, RosterManager). All the interaction between emite and you is done by adding listerers to those managers.

Login/logout and control the session state

To login the session we use the login method on xmpp:

xmpp.login("theUserName", "theUserPassword");

When the login method returns the login process begins. You could (and probably want) to know about the state of the login process. For this purpose we use a session listener:

xmpp.getSession().addListener(new SessionListener() {
	public void onStateChanged(final State old, final State current) {
		switch (current) {
		case connected:
			// NOW WE CAN SEND AND RECEIVE XMPP STANZAS!
			break;
		case connecting:
			break;
		case disconnected:
			break;
		}
	}

We shouln't send any message before the 'connected' state is received. The disconnected state is received when an error makes the xmpp stop (connection errors, etc...)

We can logout whenever we want:

xmpp.logout();

Chat: user to user message exchanging

This is a proposal. Please Vicente read it and give me some feedback

We use the ChatManager to handle all the user to user message exchanging. As always, to obtain the ChatManager we use the xmpp object:

ChatManager chatManager = xmpp.getChatManager();

Create a chat, send and receive messages

To start a conversation with someone we should create a chat object:

Chat chat = xmpp.getChatManager().newChat("destinationUserJID");

We can, now send messages, or change the subject:

chat.send("hello, friend");
chat.setSubject("welcome");

Or we can receive messages:

chat.addListener(new ChatListener() {
	public void onMessageReceived(Message receivedMessage) {
		// here we have the message 
	}
});

If we start a new chat, the ChatManager always assigns a thread property to that chat.

Manage created chats

Chats can be created by us (as the last example) or by other connected xmpp users. To know when a chat is created (either by us or by other) we can add a listener to the ChatManager object:

xmpp.getChatManager().addListener(new ChatManagerListener() {
	public void onChatCreated(Chat chat) {
		// this is only an example... ChatView object doesnt exist within emite
		final ChatView view = new ChatPanel();
		chat.addListener(new ChatListener() {
			public void onMessageReceived(Message message) {
				view.add(message.getFrom() + ": " + message.getBody());
			}
			public void onMessageSent(Message message) {
				view.add(message.getFrom() + ": " + message.getBody());
			}
		});			
	}
});

Roster

You can retrieve the roster directly using xmpp:

xmpp.getRoster(); 

Retrieve the initial roster

By default, the xmpp object retrieves the roster after connected state. We can retrieve the roster by using (as always in asynchronous programs) a listener:

xmpp.getRoster().addListener(new RosterListener() {
	public void onRosterInitialized(final List<RosterItem> rosterItems) {
		// THE ROSTER IS READY AND YOU GET THE ITEMS FOR FREE ;) 
	}
});

Presence

We use the PresenceManager to receive and send presence information. The roster handle automatically the presence. Take a look to PresenceManager javadoc to see what this object is capable to do.