This chapter explains how to configure and manage email, file, message, and custom archiving for Oracle Communications Instant Messaging Server.
Instant message archiving can be done in the following ways:
Email Archive. When using this method, chat and conference participants receive email containing the contents of the Instant Messaging Server sessions in which they participated. End users can use any email client to search and manage instant messages.
File Archive allows you to archive the contents of a file that is transferred from one client to another.
Message Archiving allows you to archive all the message data that passes through the server in any one-to-one or a group-chat conversation.
Custom Archive. You can choose to use either the Instant Messaging Server archive providers, or create your own custom archive provider. Instant Messaging Server provides the APIs and SPIs that you use to write custom archive providers. For more information on Instant Messaging Server APIs, see "Using the Web Presence API" and "Instant Messaging Server APIs."
Regardless of which type of archive provider you choose to use, you must enable the archive provider by running the imconfutil command to configure the appropriate property.
You can configure Instant Messaging Server to use one or both archive methods at the same time. Additionally, you can enable the archive so that users can retrieve their messages.
Regardless of whether you choose to use email, a custom archive, or any combination of archives, you enable the archiving capability in Instant Messaging Server the same way as described in this section. Disabling archiving as described in this section disables all archives.
After you enable archiving for Instant Messaging Server, you must enable the archive provider for the type of archive you want to use as described in the following sections:
Use the imconfutil command to set the iim_server.msg_archive property to true.
imconfutil -c InstantMessaging_home/config/iim.conf.xml set-prop iim_server.msg_archive=true
Restart the server.
imadmin refresh server
This procedure disables all archiving for Instant Messaging Server. If you want to disable only email archiving or a custom archive you have configured, see one of the following sections:
Use the imconfutil command to set the iim_server.msg_archive configuration property to false.
imconfutil -c InstantMessaging_home/config/iim.conf.xml set-prop iim_server.msg_archive=false
Restart the server.
imadmin refresh server
The two types of archiving mechanisms exposed by Instant Messaging Server are:
The Archive Provider API allows you to archive the contents of a file that is transferred from one client to another by using an In-Band Bytestreams file transfer feature. The abstract class exposed by Instant Messaging Server to implement file archiving is com.sun.im.provider.ByteStreamFilter.
Following is an example of implementing the custom provider:
package com.sun.im.provider;
/**
* Custom file archival provider must extend this abstract
* class
*/
public abstract class ByteStreamFilter
{
/**
* process a data block contained in a stream.
*
* This method needs to be overridden in order to perform
* archiving
*
* @param stream byte stream handle
* @param block block of bytes to be transferred.
*
*/
public void processData(ByteStream stream,
ByteStreamBlock block)
{
block.commit();
}
/**
* called when a new byte stream is open
*
* @param from data originator address, uses xmpp address
* @param to data recipient address, uses xmpp address format
* @param stream byte stream handle
*/
public void openStream(String to, String from,
ByteStream stream)
{
}
/**
* called when a new byte stream is closed
*
* @param stream byte stream handle
*/
public void closeStream(ByteStream stream)
{
}
}
The Instant Messaging Server enables you to write custom archive providers. The custom archive provider for file archiving stores the contents of the file that is transferred from one client to another to a local file. To write a custom archive provider, you must override methods in the abstract classes ByteStreamFilter and ArchiveProvider. ByteStreamFilter is used for archiving file transfers.
Following is an example of a custom archive provider:
package com.sun.im.provider;
public class FileArchiving extends ByteStreamFilter
{
private FileWriter fstream;
private BufferedWriter out;
private StringBuffer buffer;
public void processData(ByteStream stream,
ByteStreamBlock block)
{
log.debug( {{FileArchiving}}:processData() called );
String data = new String(block.getBytes());
buffer += data;
}
public void openStream(String to, String from,
ByteStream stream)
{
log.debug( {{FileArchiving}}:openStream() called );
fstream = new FileWriter("/tmp/{{FileArchiving}}");
out = new BufferedWriter(fstream);
}
public void closeStream(ByteStream stream)
{
log.debug( {{FileArchiving}}:closeStream() called );
out.write(buffer.toString());
}
}
Compile your custom archive by including the improvider.jar file in your classpath.
imconfutil -c InstantMessaging_home/config/iim.conf.xml set-prop iim_server.classpath=your-custom-provider
This section describes how to enable and disable the Instant Messaging Server file archive provider:
To enable file archiving:
Enable file archiving.
imconfutil -c InstantMessaging_home/config/iim.conf.xml set-prop iim_server.filter.enable=true
Enable your custom file archive provider.
imconfutil -c InstantMessaging_home/config/iim.conf.xml set-prop iim_server.filters=fully-qualified-name-of-your-custom-provider-class
Restart the server.
imadmin refresh server
To disable file archiving:
imconfutil -c InstantMessaging_home/config/iim.conf.xml set-prop iim_server.filter.enable=false
Message Archiving allows you to archive all the message data that passes through the server in any one-to-one or a group-chat conversation. The abstract class exposed by Instant Messaging Server to implement message archiving is com.sun.im.provider.ArchiveProvider.
Following is an example of implementing the custom message archival provider:
/**
* Custom message archival provider must extend this
* abstract class
*/
package com.sun.im.provider;
public abstract class ArchiveProvider
{
/**
* invoked when a user signs on
* @param uid identifier of the authenticated user
*/
public void onLogin(String uid)
{
}
/**
* invoked when a user signs off
* @param uid user identifier
*/
public void onLogout(String uid)
{
}
/**
* invoked when a user creates a private conference
* @param conferenceAddress address of the conference
* @param uid unique identifier of the user who setup
* the conference
*/
public void onSetup(String conferenceAddress, String uid)
{
}
/**
* invoked when a user joins a conference
* @param conferenceAddress address of the conference
* @param uid unique identifier of the new participant
*/
public void onJoin(String conferenceAddress, String uid)
{
}
/**
* invoked when a user leaves conference
* @param conferenceAddress address of the conference
* @param uid unique identifier of the leaving participant
*/
public void onLeave(String conferenceAddress, String uid)
{
}
/**
* invoked when a private conference is terminated
* @param conferenceAddress address of the conference
* @param uid identifier of the user who closed the
* conference
*/
public void onClose(String conferenceAddress, String uid)
{
}
/**
* invoked when a user creates a private conference
* @param conferenceAddress address of the conference
* @param message invite message
*/
public void onInvite(String conferenceAddress,
com.sun.im.service.ReadOnlyMessage message)
{
}
/**
* invoked when a message of type normal, headline or error is
* received by the server. When a chat message is received in a
* one-to-one or a group-chat conversation,onConferenceMessage
* is used instead.Once archived, the message is visible only
* to the originator and recipients of the message.
* The originator and recipients addresses, message
* identifier, message content, and other message attributes
* can be obtained
* using the methods in the com.sun.im.service.ReadOnlyMessage
* interface.
* @param message message
*/
public void onMessage(com.sun.im.service.ReadOnlyMessage message)
{
}
/**
* invoked when a message of type normal, headline or error is
* received by the server. When a chat message is received in a
* one-to-one or a group-chat conversation,onConferenceMessage
* is used instead.Once archived, the message is visible only
* to the originator and recipients of the message.
* The originator and recipients addresses, message
* identifier, message content, and other message attributes
* can be obtained
* using the methods in the com.sun.im.service.ReadOnlyMessage
* interface.
* @param message message
*/
public void onMessage(com.sun.im.service.ReadOnlyMessage message)
{
}
/**
* invoked when a message is received by the server in any
* one-to-one or a group-chat conversation.
* @param conferenceAddress address of the conference
* @param message message
* The originator address, message identifier,
* message content, and other message attributes can be
* obtained using the methods in the Message interface.
* @see com.sun.im.service.Message
*/
public void onConferenceMessage(String conferenceAddress,
com.sun.im.service.ReadOnlyMessage message)
{
}
/**
* Add code store to marker messages
*/
@Override
public void onMarkerMessage(ReadOnlyMarkerMessage mm)
{
}
/**
* open the archive
* @exception Exception failure to open and initialize the
* archive.
*/
public void open() throws Exception
{
}
/**
* close the archive and dispose off all held resources
*/
public void close()
{
}
}
The custom message archive provider example for message archiving stores the messages exchanged in any one-to-one or group-chat conversation in a local file. It also logs invite messages and join and leave events of a group-chat. ArchiveProvider is used to archive one-to-one chat and group chat messages. ArchiveProvider for both files and messages are enabled using the imconfutil command.
Following is an example of an custom message archive provider:
package com.sun.im.provider;
public class MessageArchiving extends ArchiveProvider
{
private FileWriter fstream;
private BufferedWriter out;
public void onLogin(String uid)
{
log.debug( MessageArchiving:onLogin() called );
}
public void onLogout(String uid)
{
log.debug( MessageArchiving:onLogout() called );
}
public void onSetup(String conferenceAddress,
String uid)
{
log.debug( MessageArchiving:onSetup() called );
out.write( Conference has been created );
}
public void onJoin(String conferenceAddress, String uid)
{
log.debug( MessageArchiving:onJoin() called );
out.write(uid + has joined the conference );
}
public void onLeave(String conferenceAddress, String uid)
{
log.debug( MessageArchiving:onLeave() called );
out.write(uid + has left the conference );
}
public void onClose(String conferenceAddress,
String uid)
{
log.debug( MessageArchiving:onClose() called );
out.write( Conference has been closed );
}
public void onInvite(String conferenceAddress,
com.sun.im.service.ReadOnlyMessage message)
{
log.debug( MessageArchiving:onInvite() called );
out.write(message.getOriginator() + has invited + message.getRecipients() + to the conference );
}
public void onMessage(com.sun.im.service.ReadOnlyMessage message)
{
log.debug( MessageArchiving:onMessage() called );
}
public void onMessage(java.util.List accessList,
com.sun.im.service.ReadOnlyMessage message)
{
log.debug( MessageArchiving:onMessage() called );
}
public void onConferenceMessage(String conferenceAddress,
com.sun.im.service.ReadOnlyMessage message)
{
log.debug( MessageArchiving:onConferenceMessage() called );
out.write(message.getOriginator()+ sent a message, +message.getContent()+ to +message.getRecipients());
}
public void onMarkerMessage(ReadOnlyMarkerMessage mm)
{
log.debug( MessageArchiving:onMarkerMessage() called );
}
public void open() throws Exception
{
log.debug( MessageArchiving:open() );
fstream = new FileWriter("/tmp/MessageArchiving");
out = new BufferedWriter(fstream);
}
public void close()
{
log.debug( MessageArchiving:close() );
}
}
Compile your custom archive using the following jar file in the classpath: imservice.jar.
imconfutil -c InstantMessaging_home/config/iim.conf.xml set-prop iim_server.classpath=your-custom-provider
This section describes how to enable and disable the Instant Messaging Server message archive provider.
To enable message archiving:
Run the following imconfutil command.
imconfutil -c InstantMessaging_home/config/iim.conf.xml set-prop iim_server.msg_archive=true
Enable your custom message archive provider.
imconfutil -c InstantMessaging_home/config/iim.conf.xml set-prop iim_server.msg_archive.provider=fully-qualified-name-of-your-custom-provider-class
Restart the server.
imadmin refresh server
You can use Instant Messaging Server to archive chat and conference, content, and email that content to end-users and administrators. You can use any email client to search and manage the archived content. This section describes the Instant Messaging Server email archive in the following sections:
Instant Messaging Server caches archived records until they are emailed. If you enable email archiving, the memory requirements for the server increase. For information on performance tuning see "Improving Instant Messaging Server Performance."
You enable or disable the email archive provider by modifying a the appropriate configuration property.
Ensure that you have enabled archiving for Instant Messaging Server as described in "Enabling Instant Messaging Server Archiving."
Use the imconfutil command to set the iim_server.msg_archive.provider property.
imconfutil -c InstantMessaging_home/config/iim.conf.xml set-prop iim_server.msg_archive.provider=com.iplanet.im.server.EmailIMArchive
The iim_server.msg_archive.provider property contains a comma-separated list of archive providers.
Restart the server.
imadmin refresh
Use the imconfutil command to remove the iim_server.msg_archive.provider property.
imconfutil -c InstantMessaging_home/config/iim.conf.xml del-prop iim_server.msg_archive.provider
Restart the server.
imadmin refresh
You can configure which administrators receive email containing archived instant messages. You can configure a separate list of administrators to receive conference or chat sessions. You can also configure Instant Messaging Server to use the extended RFC 822 header. Doing so enables mail clients to filter messages based on the header content.
Note:
If you run configure after modifying these properties for the email archive, any values you input are overwritten.Table 10-1 describes the configuration properties that you use to define which administrators receive email archives, as well as whether to use the extended RFC 822 header, and the content of that header.
Table 10-1 Email Archive Configuration Properties
| Property | Default Value | Description |
|---|---|---|
|
iim_arch.admin.email |
Empty String |
Comma-separated list of administrator email addresses. |
|
emailiim_arch.alert.admin. |
None |
Comma-separated list of administrator email addresses to which all archived alert messages are sent. This property overrides iim_arch.admin.email for alert messages. |
|
iim_arch.chat.admin.email |
None |
Comma-separated list of administrator email addresses to which all archived chat messages are sent. This property overrides iim_arch.admin.email for chat messages. |
|
iim_arch.conference.admin.email |
None |
Comma-separated list of administrator email addresses to which all archived conference messages are sent. This property overrides iim_arch.admin.email for conference messages. |
|
iim_arch.poll.admin.email |
None |
Comma-separated list of administrator email addresses to which all archived poll messages are sent. This property overrides iim_arch.admin.email for poll messages. |
|
iim_arch.news.admin.email |
None |
Comma-separated list of administrator email addresses to which all archived news messages are sent. This property overrides iim_arch.admin.email for news messages. |
|
iim_arch.email.archiveheader.name |
None |
Name of the extended RFC 822 header. |
|
iim_arch.email.archiveheader.value |
all |
Value corresponding to the header name for iim_arch.email.archiveheader.name. |
To configure administrator recipients:
Run the imconfutil command to add the properties in Table 10-1 and appropriate values to the configuration.
Restart the server.
imadmin refresh
The RFC 822 header content for email messages containing various types of archived Instant Messaging Server content is described in the following sections:
From: Chat session initiator.
To: Receiver and any administrators configured in iim.conf.xml.
See Table 18-1 for more information.
Subject: First useful message over 50 characters in length.
Date: Creation date of the email message by the archive provider.
Reply-to: Not used.
Message-ID Generated by the email archive provider based on
the message thread.
From: Chat session initiator.
To: Other participants and any administrators configured in iim.conf.xml.
See Table 18-1 for more information.
Cc: Chat session initiator.
Subject: If a subject is set for the conference, the conference
subject is used. If no subject is set, first useful
message over 50 characters in length is used.
Date: Creation date of the email message by the archive provider.
Reply-to: Not used.
X-XMPP-Message-ID Generated by the email archive provider based on the
conference ID.
From: Room owner in archive data.
To: Associated mailing list, users with explicit access
to the conference room, and any administrators
configured in iim.conf.xml. See Table 18-1 for more
information.
Cc: Not used
Subject: [Conference name] subject.
Date: Creation date of the email message by the archive provider.
Reply-to: Not used.
X-XMPP-Message-ID Generated by the email archive provider based on the
conference ID.
From: Poll sender.
To: Poll sender and any administrators configured
in iim.conf.xml. See Table 18-1 for more information.
Cc: Not used.
Subject: Poll question.
Date: Creation date of the email message by the archive provider.
Reply-to: Not used.
X-XMPP-Message-ID Generated by the email archive provider.
From: Poll sender.
To: Poll recipients and any administrators configured in
iim.conf.xml. See Table 18-1 for more information.
Cc: Poll sender.
Subject: Poll question.
Date: Creation date of the email message by the archive provider.
Reply-to: Not used.
X-XMPP-Message-ID Generated by the email archive provider.
From: Alert sender.
To: Alert recipient and any administrators configured
in iim.conf.xml. See Table 18-1 for more information.
Cc: Not used.
Subject: Alert subject.
Date: Creation date of the email message by the archive provider.
Reply-to: Not used.
X-XMPP-Message-ID Generated by the email archive provider.
From: News channel post sender.
To: Mailing list associated with the news channel
and any administrators configured in iim.conf.xml.
See Table 18-1 for more information.
Cc: Not used.
Subject: News channel post subject.
Date: Creation date of the email message by the archive provider.
Reply-to: Not used.
X-XMPP-Message-ID Generated by the email archive provider.
In addition to the email archive, you can choose to use a custom archive provider.
Ensure that you have enabled archiving for Instant Messaging Server as described in "Enabling Instant Messaging Server Archiving."
To enable a custom archive provider:
Use the imconfutil command to add the type of archive provider you want to enable.
For example, for a custom archive provider:
imconfutil -c InstantMessaging_home/config/iim.conf.xml set-prop iim_server.msg_archive.provider=provider-name
The iim_server.msg_archive.provider property contains a comma-separated list of archive providers. The following example enables the email provider.
iim_server.msg_archive.provider=com.iplanet.im.server.EmailIMArchive
Restart the server.
imadmin refresh
To disable a custom archive provider:
Use the imconfutil command to delete only the value for the custom archive provider from the iim_server.msg_archive.provider property.
imconfutil -c InstantMessaging_home/config/iim.conf.xml del-prop iim_server.msg_archive.provider=provider-name
Restart the server.
imadmin refresh
Instant Messaging Server supports the retrieval of archived messages (one-to-one chats), even those which have been sent and received from multiple end points. Users can then retrieve these archived messages from the archival store upon login from any end point. Archiving is managed by using the Instant Messaging Server Archive Provider API. Currently, retrieval of conference messages and group messages is not yet available.
The custom message archive management provider is required for retrieving stored messages from the message archive. This provider extends the ArchiveProvider class and provides two additional methods that Instant Message Server invokes when it queries the message archive. In addition, this provider is required for automatic history synchronization between multiple clients.
To enable retrieval of archived messages:
Set the iim_server.msg_archive property to true:
imconfutil -c InstantMessaging_home/config/iim.conf.xml set-prop iim_server.msg_archive=true
Set the iim_server.msg_archive.provider property to the class name of your Archive Provider implementation:
imconfutil -c InstantMessaging_home/config/iim.conf.xml set-prop iim_server.msg_archive.provider="com.example.archiving.MessageArchivingSample"
See "Message Archive Retrieval Provider Example" for information about writing a sample archiving implementation.
Set the iim_server.msg_archive.maxstanzas property to the maximum number of message stanzas to be retrieved from the archive store. (A stanza is a message packet which holds the message information.)
imconfutil -c InstantMessaging_home/config/iim.conf.xml set-prop iim_server.msg_archive.maxstanzas=10
Set the iim_server.classpath property to the location of the JAR file that contains the implementation of the provider:
imconfutil -c InstantMessaging_home/config/iim.conf.xml set-prop iim_server.classpath=path_to_sample/MessageArchivingSample.jar
Restart Instant Messaging Server.
The following sample provider queries the message store.
public List<Message> getArchivedMessages(String user, SearchCriteria sc, int count) {
// Add code to fetch messages for given criteria
// Refer next method to create list of messages
}
public List<Message> getArchivedMessages(String user, int count) {
// Add code to fetch messages
List<Message> list = new ArrayList<Message>;
MessageFactory fac = new MessageFactory()
Message message = fac.createMessage("aeb213", "juliet@capulet.lit/balcony", "romeo@montague.lit/orchard", "Call me but love, and I'll be new baptized; Henceforth I never will be Romeo." );
message.setHeader(MessageHeaders.ARCHIVE_UID_HEADER, "28482-98726-73623");
message.setHeader(MessageHeaders.FORWARDED_TIMESTAMP_HEADER, "2010-07-10T23:08:25Z"); // stamp field of result message
list.add(message);
return list;
}
}
Each message that is part of the list contains an archive UID and a timestamp. The archive UID uniquely identifies the message in the archive store and is used for Result Set Management. The timestamp is in ISO 8061 format, which is the time at which the message was archived into the store. Both UID and timestamp are forwarded to the client.
The MessageFactory class enables message creation. This class is part of the imservice.jar file, which facilitates creation of chat messages and marker messages. You can add archive UID and timestamps of a message to the newly created message by using the setHeader(String name, String value) method of the 'Message' interface. The header constant to be used to set archive UID is MessageHeaders.ARCHIVE_UID_HEADER. The header constant to be used to set the timestamp is MessageHeaders.FORWARDED_TIMESTAMP_HEADER. You can use setHeader to set other message metadata such as thread information and subject.
Chat markers are the visual indications between all the sender's and recipient's resources, indicating when a message has been delivered to any of the recipient's resources, and optionally when it has been displayed (read). In this way, chat markers help to consistently maintain the state of a chat across all end points. These marker messages are also stored to the archive store if message archiving is enabled. Additionally, if one or more of the resources is not connected, it can fetch chat markers from the message archive upon reconnecting.
The chat marker is in itself a kind of message that indicates the status of a message after it has been sent to a client. A chat marker status can be:
Received - Indicates that a user received a message.
Acknowledged - Indicates that the user who received the message acknowledged it.
Displayed - Indicates that the message was displayed to the intended user.
The following code shows how chat markers can be applied to the storage and retrieval of one-to-one messages. Currently, they cannot be applied to group chat or conference messages.
public void onMarkerMessage(ReadOnlyMarkerMessage mm) {
/**
* Add code to store marker messages
*/
}
The onMarkerMesssage method enables chat markers to be included in archived messages.
If the chat markers are stored in the archive store, create a marker message using the MessageFactory class then append the marker to message list. For example:
public List<Message> getArchivedMessages(String user, int count) {
List<Message> list = new ArrayList<Message>;
// create normal messages 1..n
MarkerMessage marker = fac.createMarkerMessage("marker-1");
marker.setMarker("aeb213", MarkerStatus.ACKNOWLEDGED);
marker.setOriginator("romeo@montague.lit/orchard");
marker.addRecipient("juliet@capulet.lit/balcony");
message.setHeader(MessageHeaders.THREAD_HEADER, "thread1");
list.add(marker);
return list;
}