Package org.jivesoftware.smackx.mam

Class MamManager

  • public final class MamManager
extends Manager
    A Manager for Message Archive Management (MAM, XEP-0313).

    Get an instance of a manager for a message archive

    In order to work with MamManager you need to obtain an instance for a particular archive. To get the instance for the default archive on the user's server, use the getInstanceFor(XMPPConnection) method. 
     
 XMPPConnection connection = ...
 MamManager mamManager = MamManager.getInstanceFor(connection);
    If you want to retrieve a manager for a different archive use getInstanceFor(XMPPConnection, Jid), which takes the archive's XMPP address as second argument.

    Check if MAM is supported

    After you got your manager instance, you probably first want to check if MAM is supported. Simply use isSupported() to check if there is a MAM archive available. 
     
 boolean isSupported = mamManager.isSupported();

    Message Archive Preferences

    After you have verified that the MAM is supported, you probably want to configure the archive first before using it. One of the most important preference is to enable MAM for your account. Some servers set up new accounts with MAM disabled by default. You can do so by calling enableMamForAllMessages().

    Retrieve current preferences

    The archive's preferences can be retrieved using retrieveArchivingPreferences().

    Update preferences

    Use MamManager.MamPrefsResult.asMamPrefs() to get a modifiable MamManager.MamPrefs instance. After performing the desired changes, use updateArchivingPreferences(MamPrefs) to update the preferences.

    Query the message archive

    Querying a message archive involves a two step process. First you need specify the query's arguments, for example a date range. The query arguments of a particular query are represented by a MamManager.MamQueryArgs instance, which can be build using MamManager.MamQueryArgs.Builder. After you have build such an instance, use queryArchive(MamQueryArgs) to issue the query. 
     
 MamQueryArgs mamQueryArgs = MamQueryArgs.builder()
                                 .limitResultsToJid(jid)
                                 .setResultPageSizeTo(10)
                                 .queryLastPage()
                                 .build();
 MamQuery mamQuery = mamManager.queryArchive(mamQueryArgs);
    On success queryArchive(MamQueryArgs) returns a MamManager.MamQuery instance. The instance will hold one page of the queries result set. Use MamManager.MamQuery.getMessages() to retrieve the messages of the archive belonging to the page. You can get the whole page including all metadata using MamManager.MamQuery.getPage().

    Paging through the results

    Because the matching result set could be potentially very big, a MAM service will probably not return all matching messages. Instead the results are possibly send in multiple pages. To check if the result was complete or if there are further pages, use MamManager.MamQuery.isComplete(). If this method returns false, then you may want to page through the archive. MamManager.MamQuery provides convince methods to do so: MamManager.MamQuery.pageNext(int) and MamManager.MamQuery.pagePrevious(int). 
     
 MamQuery nextPageMamQuery = mamQuery.pageNext(10);

    Get the supported form fields

    You can use retrieveFormFields() to retrieve a list of the supported additional form fields by this archive. Those fields can be used for further restrict a query.
    See Also:
    XEP-0313: Message Archive Management