Docs > FAQ

ICEspresso Chat FAQ

This is the Frequently Asked Questions list for ICEspresso Chat project. It attempts to answer conceptualand technical questions alike.

The FAQ compilation will grow as feedbacks from general public are received.

Table of Contents

General Information

1.1 What is ICEspresso Chat Framework?

ICEspresso Chat Framework is a Javascript-based library package that aims to aid developers build chat-related service as well as web presence social system without requiring developers to touch on the networking and server details.

More specifically, it facilitates a manageableway to provide the communication service. This is best described in a situation where application programmer needs only to follow a set of pre-defined event handler to enable the service.

1.2 What is ICEspresso Service?

ICEspresso Service is the counterpart to ICEspresso Chat Framework. The Service keeps tracks of user activity and state and delivers raw data to the Framework which in turn will dispatch the data to application. The Service and the Framework talks to each other. Application is notified when data that the application is interested in receiving arrives.

Speaking strictly, ICEspresso Service is a back-end server that is written in Java language and is hosted and maintained by Push4Free.com (sponsored by ICE Technology).

The ICEspresso Team will consider to provide the package of ICEspresso Service with open source format in the future.

1.3 What is iPush Server?

iPush Server is the communication medium between the Framework and the Service. In technical terms, iPush Server is a middleware that sits in the middle and relays network messages to individual connected party.

The ICEspresso project is built on the support and capability of iPush Server to exchange network data. More information on iPush Server can be found here.

1.4 What is pjax?

pjax is one of the iPush API libraries that sends and receives data from iPush Server. It is also known as the Javascript wrapper for Flash library. Flash plug-in at the lower tier communicates with iPush Server whereas pjax allows the plug-in to relay data to application through Javascript invocation.

ICEspresso Chat Framework takes advantage of pjax. While pjax focuses on the actual communication layer, the Framework processes raw data and converts these data into meaningful events for application.

1.5 What is JSON?

Taken from http://www.json.org, JSON (JavaScript Object Notation) is a lightweight data-interchange format. Both the Framework and the Service resort to JSON for data interchange between themselves.

1.6 How do these components construct the final architecture?

ICEspresso Chat Framework makes use of these two client technologies: JSON and pjax. On top of the technologies, an event model is designed and a set of callable interface is exported for application to handle these events in a customizable way. The three elements form the working blocks of ICEspresso Chat Framework.

ICEspresso Service also makes use of JSON for data interchange purpose. It communicates with many ICEspresso Chat Frameworks (one-to-many) for data sending and data processing request.

iPush Server acts as the communication component between the Framework and the Service.

1.7 How does ICEspresso differ from other chat packages?

We do not attempt to make comparison between specific packages. We intend to highlight the strengths of ICEspresso.

ICEspresso provides true "push" solution for real-time chat service. Traditionally, page refresh is done using <META> tag. Recent technology improvement brings the practical use of AJAX that accounts for dynamic content update in a more viable way. However, AJAX in chat room implementation is still polling-based which creates unnecessary traffic. The real-timeness varies depending on how often client polls. ICEspresso on the hand does not suffer from these two drawbacks. Latest data/message is sent to you right away instead of you asking for it periodically.

1.8 Does it cost me to use ICEspresso-related services?

You can get a free ICEspresso Chat connection pool account for 30 concurrent connections (provided by Push4Free.com). It should be enough for small-to-medium chat application with 30 concurrent chatters.

If you want more concurrent connections, you may apply the ICEspresso Chat Premier program. It is a postpay service, charging in peak-usage-based.

Using ICEspresso Chat Framework

2.1 What is required before using ICEspresso Chat Framework?

For development requirement, you should download the latest packaged library from SourceForge.net. Once you have the package, you need to register a free connection pool account to entitle you to use ICEspresso Service. During the development, you will need a local web server to your preference to host the application.

Reason for requiring a web server is that the Flash agent (pjax.swf) cannot run non-http network functions when executed locally. A more detailed explanation on the Flash security model may be found here.

It was said that the ICEspresso Chat Framework is written in Javascript language. Hence having experience in Javascript language helps shorten the learning curve. The Framework is event-driven so you will find that asynchronous programming skill also helps understand the ICEspresso model.

2.2 What browsers are supported by ICEspresso Chat Framework?

The ICEspresso Chat Framework tested fine on IE6, IE7, Firefox 2, Firefox 3, and Safari 3.1.

Browsers to be supported in the near future are Opera, and Google Chrome (in its official release).

2.3 Do I have to put pjax.swf under the same directory as icespressochat.js?

Yes, both icespressochat.js and pjax.swf need to reside under the same directory.

2.4 What does the error message "pjax.swf was not loaded" mean?

It means the ICEspresso Chat Framework fails to load pjax.swf. There are several possible reasons for this:

1. The running browser does not have Flash plug-in installed. Please check with Adobe's Get Flash page.

2. pjax.swf's physical location is in a different directory from that of icespressochat.js. Please refer to FAQ 2.3.

3. The running browser is known to have Flash plug-in issues. Maxthon, an IE variant, was known to have minor Flash stability issues in its earlier releases.

2.5 Is it safe to call icespresso.initialize() inside HTML <HEAD>...</HEAD> section?

It depends. If ICEspresso debug support is turned off then calling icespresso.initialize() inside <head>...</head> section is safe.

However, it is not a recommended way to put icepsresso.initiaize() inside <head>...</head>. The Framework needs document.body defined before it can place Flash agent on the page. Likewise, the ICEspresso log pane also requires the presence of document.body.

As a result, it is recommended that icespresso.initialize() be placed after <body> tag to avoid possible script errors.

2.6 What exactly does the parameter roomName in joinRoom(roomName) represent?

The joinRoom(roomName) may appear innocent at first look. One might think roomName must be a descriptive string that an application assigns to a room so users can distinguish each room. But in fact, the parameter roomName is instead a symbol for application to make the distinction. It is bound by the rule that it only accepts alphanumerical characters (A-Za-z_0-9).

Because of the restriction an application should provide a mapping table to map the roomName used by Framework to the room name perceived by user. Suppose that we host a room whose topic is "Major League Baseball Playoff Talk". A reasonable roomName used inside application may be mlbplayoff. At this point, the application has to provide a way to map these names so they are linked. Please See FAQ 3.2 for sample code.

HOW-TOs

3.1 In a chat room environment, how do I add font color and size to plain text before calling send2room()?

There are many ways to achieve this.

The simplest way is to include format in the string is to wrap up plain text with HTML tags. For example, user picked font size 10pt and navy color. We could simply wrap it up like this:

// Suppose getUserInputColor(), getUserInputFontSize()
// and getUserInputText() are defined somewhere else.
var color = getUserInputColor();
var size = getUserInputFontSize();
var txt = getUserInputText();
var str = ("<span style='color:" + color + "; font-size:" + size + "pt;'>" 
+ txt + "</span>");
chatInst.send2Room(str, roomName);

Another approach that will be more flexible is through the use of JSON. Since ICEspresso Chat Framework uses JSON as the native interchangeformat. We can take advantage of JSON to include the "metadata" in the data to send.

// Suppose getUserInputColor(), getUserInputFontSize()
// and getUserInputText() are defined somewhere else.
var color = getUserInputColor();
var size = getUserInputFontSize();
var txt = getUserInputText();
var h = {
    size: size,
    color: color,
    txt: txt
}
var str = JSON.stringify(h);
chatInst.send2Room(str, roomName);

The receiver's code would look similar to this:

icespresso.onChatEvent(chat, eventId, arg) {
    switch (eventId) {
        case chat.CHAT_ROOMMSG:
        var msg = arg.msg;
        var h = JSON.parse(msg.getMessage());
        /**
         * Now h contains
         * h.txt: the original text input
         * h.color: color picked by message initiator
         * h.size: font size picked by message initiator
         *
         * Application goes ahead to provide a suitable format using
         * the raw data
         */
        break;
    }
}

Why bother with lengthier code if the achieved result is the same? In this example, the desired result is the same through both approaches. However, in a more complicated application requirement, sometimes it is preferred to have raw data to suit diversified needs. Suppose our chat room supports different themes with each them requiring slightly different output format. If we format the final output on the sender side, certain themes might break because of this.

3.2 How do I map roomName in joinRoom(roomName) to an actual room topic??

As discussed in FAQ 2.6, roomName and room topic should be treated differently. roomName is a symbol used inside the Framework to transmit messages to ICEspresso Service. Room topic on the other hand is the decorative name that conveys the type and nature of the room to application user. At application level, a look-up table should be provided to link the two.

In a simplistic way, we could just use hash table to do the mapping. Consider the JSP code that set-up a chat room.

<!--
 Suppose we host 3 chat rooms which share the same look but
 differ in the room topic for different kind of discussion.
 Consider a pseudo scenario where user clicks on a hyperlink
 to join a chat room, we could the following code snippet to.
 demonstrates how we map roomName and its topic.
--> 
<%@page import="java.util.HashMap" %>
<%
// Construct a hash map to do the mapping
HashMap<String, String> roomMap = new HashMap<String, String>();
roomMap.put("room1", "Baseball");
roomMap.put("room2", "Basketball");
roomMap.put("room3", "Hockey");

// the room to be joined when 
String roomName = request.getParameter("roomName");
if (roomName == null) {
    // put application logic here to handle
    // the absence of roomName in query string error
}


String roomTopic = roomMap.get(roomName);
if (roomTopic == null) {
    // roomName has no matching record in hash table
    // put application logic here to process the error
}
%>
<!-- room topic is shown here -->
<h3><%= roomTopic %></h3>

<!-- other chat room layout -->

<script language="javascript">
// Join chat room when ICEspresso Framework has handshaked
var chatInst = null;
icespresso.onSystemEvent(chat, eventId, arg) {
    switch (eventId) {
    // other events omitted for brevity
    case SYS_HANDSHAKED:
    chat.joinRoom("<%= roomName %>");
    break;
    }
}

chatInst = icespresso.initialize();
</script>

The roomMap hash table is hard-coded in the sample code. In real-world application, the information normally comes other data source such as RDBMS. Nonetheless, what we intend to convey is that once the mapping is established, we will have a roomName used for joinRoom(roomName) call and a mapped room topic to display to application user.