About ColdFusion and instant messages



ColdFusion includes two instant messaging gateway types: one for messaging using the XMPP protocol, and one for IBM Lotus Instant Messaging (Sametime). These gateway types use identical interfaces for sending and receiving messages and for managing the IM presence information and infrastructure. This documentation, therefore, refers to IM gateways, and only describes the two types where differences exist.

The ColdFusion IM gateways act as IM clients and let you do the following:

  • Send and receive instant messages.

  • Send and respond to buddy or friend requests and manage buddy/friend information.

  • Set and get status and other information.

  • Receive and handle messages from the IM server.

About XMPP

XMPP (Extensible Messaging and Presence Protocol) is an open, XML-based protocol for instant messaging. It is the core protocol of the Jabber Instant Messaging and Presence technology that the Jabber Software Foundation develops. As of November 2004, four Internet Engineering Task Force (IETF) specifications (RFCs) defined XMPP, numbers 3920-3923. RFC 3920 covers the XMPP core, and 3921 covers instant messaging and presence. Numerous XMPP servers and clients are available. ColdFusion supports the IETF XMPP protocol.

The following websites provide additional information about the XMPP protocol:

  • Jabber Software Foundation: www.jabber.org/. This site includes information on available XMPP servers and clients.

  • IETF has copies of the Internet standards for XMPP: www.ietf.org/rfc.html.

  • The xmpp.org website was under development as of December 2004; at that time it included several useful links, including links to relevant specifications: www.xmpp.org/.

About IBM Lotus Instant Messaging (Sametime)

IBM Lotus Instant Messaging, commonly referred to as Lotus Sametime, is the IBM product for real-time collaboration. For more information about this product, see www.lotus.com/sametime.

Note: In the Enterprise Edition, to use the Lotus Sametime event gateway, disable FIPS-140 Compliant Strong Cryptography by adding the following to the JVM arguments in the ColdFusion Administrator:

-Dcoldfusion.disablejsafe=false

About IM application development and deployment

The following information introduces the ColdFusion IM application development tools and process, and discuss IM messaging providers.

ColdFusion IM gateway classes

ColdFusion provides the following instant messaging gateway classes:

XMPPGateway
The class for the XMPP event gateway type

SAMETIMEGateway
The class for the IBM Lotus Instant Messaging event gateway

You implement your IM application by configuring a gateway instance in ColdFusion Administrator that uses one of these gateway classes and creating a ColdFusion application that uses the gateway instance to communicate with an instant messaging server.

Application development and deployment process

The following is a typical process for developing and deploying an IM application:

  1. Design your application.

  2. Configure an IM event gateway instance to use an available XMPP or Lotus Sametime server.

  3. Write your CFCs, CFM pages, and any other application elements.

  4. Test your application using your XMPP or Lotus Sametime server and an appropriate client application.

  5. Deploy the application (see Deploying event gateways and applications).

How the IM event gateway and provider interact

Each IM event gateway instance has a single instant messaging ID. Establish the ID and its related password on the IM server using server-specific tools, such as a standard instant messaging client. In ColdFusion, you set the ID, password, and other gateway-specific information in a gateway configuration file, and you create a gateway instance that uses this file.

When you start the gateway, it logs on to the IM server with the ID and password, and receives and sends the messages for the ID. The gateway sends incoming messages to a CFC, which you specify when you configure the gateway instance in the ColdFusion Administrator. The gateway passes outgoing messages from this CFC and from other CFML code to the IM server.

The IM event gateway also provides several helper methods for managing the gateway and its configuration information.

Incoming message handling

You write the following ColdFusion CFC methods to handle incoming messages and requests from the IM event gateway. These CFCs receive messages from the IM server and can respond to them by setting a return value.

CFC method

Message type

onIncomingMessage

Standard message from IM users.

onAddBuddyRequest

Requests from others to add the gateway ID to their buddy list.

onAddBuddyResponse

Responses from others to requests from your gateway to add them to your buddy lists. Also used by buddies to ask to be removed from your list.

onBuddyStatus

Presence status messages from other users.

onIMServerMessage

Error and status messages from the IM server.

For more information on these methods, see Handling incoming messages.

Outgoing message handling

Applications send outgoing instant messages using the CFML SendGatewayMessage method. Incoming message-handling CFC methods can also send messages, including responses to requests from others to add the ColdFusion gateway’s ID to their buddy list. For more information on sending messages, see Sending outgoing messages.

IMGatewayHelper methods

The ColdFusion IM gateway provides the IMGatewayHelper class, a gateway helper that you can access by calling the CFML GetGatewayHelper function. The IMGatewayHelper class has methods that let you do the following:

  • Get and set gateway configuration information and get gateway statistics

  • Get and set the gateway online presence status

  • Manage the gateway’s buddy list

  • Manage permissions for others to get information about the gateway status.

    For more information on using GatewayHelper methods, including lists of all the methods, see Using the GatewayHelper object.