Class MamManager


  • public final class MamManager
    extends org.jivesoftware.smack.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
    • Method Detail

      • getInstanceFor

        public static MamManager getInstanceFor​(org.jivesoftware.smack.XMPPConnection connection)
        Get a MamManager for the MAM archive of the local entity (the "user") of the given connection.
        Parameters:
        connection - the XMPP connection to get the archive for.
        Returns:
        the instance of MamManager.
      • getInstanceFor

        public static MamManager getInstanceFor​(org.jivesoftware.smackx.muc.MultiUserChat multiUserChat)
        Get a MamManager for the MAM archive of the given MultiUserChat. Note that not all MUCs support MAM, hence it is recommended to use isSupported() to check if MAM is supported by the MUC.
        Parameters:
        multiUserChat - the MultiUserChat to retrieve the MamManager for.
        Returns:
        the MamManager for the given MultiUserChat.
        Since:
        4.3.0
      • getInstanceFor

        public static MamManager getInstanceFor​(org.jivesoftware.smack.XMPPConnection connection,
                                                org.jxmpp.jid.Jid archiveAddress)
      • getArchiveAddress

        public org.jxmpp.jid.Jid getArchiveAddress()
        The the XMPP address of this MAM archive. Note that this method may return null if this MamManager handles the local entity's archive and if the connection has never been authenticated at least once.
        Returns:
        the XMPP address of this MAM archive or null.
        Since:
        4.3.0
      • queryArchive

        public MamManager.MamQuery queryArchive​(MamManager.MamQueryArgs mamQueryArgs)
                                         throws org.jivesoftware.smack.SmackException.NoResponseException,
                                                org.jivesoftware.smack.XMPPException.XMPPErrorException,
                                                org.jivesoftware.smack.SmackException.NotConnectedException,
                                                org.jivesoftware.smack.SmackException.NotLoggedInException,
                                                java.lang.InterruptedException
        Throws:
        org.jivesoftware.smack.SmackException.NoResponseException
        org.jivesoftware.smack.XMPPException.XMPPErrorException
        org.jivesoftware.smack.SmackException.NotConnectedException
        org.jivesoftware.smack.SmackException.NotLoggedInException
        java.lang.InterruptedException
      • queryMostRecentPage

        public MamManager.MamQuery queryMostRecentPage​(org.jxmpp.jid.Jid jid,
                                                       int max)
                                                throws org.jivesoftware.smack.SmackException.NoResponseException,
                                                       org.jivesoftware.smack.XMPPException.XMPPErrorException,
                                                       org.jivesoftware.smack.SmackException.NotConnectedException,
                                                       org.jivesoftware.smack.SmackException.NotLoggedInException,
                                                       java.lang.InterruptedException
        Throws:
        org.jivesoftware.smack.SmackException.NoResponseException
        org.jivesoftware.smack.XMPPException.XMPPErrorException
        org.jivesoftware.smack.SmackException.NotConnectedException
        org.jivesoftware.smack.SmackException.NotLoggedInException
        java.lang.InterruptedException
      • retrieveFormFields

        public java.util.List<org.jivesoftware.smackx.xdata.FormField> retrieveFormFields()
                                                                                   throws org.jivesoftware.smack.SmackException.NoResponseException,
                                                                                          org.jivesoftware.smack.XMPPException.XMPPErrorException,
                                                                                          org.jivesoftware.smack.SmackException.NotConnectedException,
                                                                                          java.lang.InterruptedException,
                                                                                          org.jivesoftware.smack.SmackException.NotLoggedInException
        Get the form fields supported by the server.
        Returns:
        the list of form fields.
        Throws:
        org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the remote entity.
        org.jivesoftware.smack.XMPPException.XMPPErrorException - if there was an XMPP error returned.
        org.jivesoftware.smack.SmackException.NotConnectedException - if the XMPP connection is not connected.
        java.lang.InterruptedException - if the calling thread was interrupted.
        org.jivesoftware.smack.SmackException.NotLoggedInException - if the XMPP connection is not authenticated.
      • retrieveFormFields

        public java.util.List<org.jivesoftware.smackx.xdata.FormField> retrieveFormFields​(java.lang.String node)
                                                                                   throws org.jivesoftware.smack.SmackException.NoResponseException,
                                                                                          org.jivesoftware.smack.XMPPException.XMPPErrorException,
                                                                                          org.jivesoftware.smack.SmackException.NotConnectedException,
                                                                                          java.lang.InterruptedException,
                                                                                          org.jivesoftware.smack.SmackException.NotLoggedInException
        Get the form fields supported by the server.
        Parameters:
        node - The PubSub node name, can be null
        Returns:
        the list of form fields.
        Throws:
        org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the remote entity.
        org.jivesoftware.smack.XMPPException.XMPPErrorException - if there was an XMPP error returned.
        org.jivesoftware.smack.SmackException.NotConnectedException - if the XMPP connection is not connected.
        java.lang.InterruptedException - if the calling thread was interrupted.
        org.jivesoftware.smack.SmackException.NotLoggedInException - if the XMPP connection is not authenticated.
      • isSupported

        public boolean isSupported()
                            throws org.jivesoftware.smack.SmackException.NoResponseException,
                                   org.jivesoftware.smack.XMPPException.XMPPErrorException,
                                   org.jivesoftware.smack.SmackException.NotConnectedException,
                                   java.lang.InterruptedException
        Check if this MamManager's archive address supports MAM.
        Returns:
        true if MAM is supported, falseotherwise.
        Throws:
        org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the remote entity.
        org.jivesoftware.smack.XMPPException.XMPPErrorException - if there was an XMPP error returned.
        org.jivesoftware.smack.SmackException.NotConnectedException - if the XMPP connection is not connected.
        java.lang.InterruptedException - if the calling thread was interrupted.
        Since:
        4.2.1
        See Also:
        XEP-0313 ยง 7. Determining support
      • isAdvancedConfigurationSupported

        public boolean isAdvancedConfigurationSupported()
                                                 throws java.lang.InterruptedException,
                                                        org.jivesoftware.smack.XMPPException,
                                                        org.jivesoftware.smack.SmackException
        Throws:
        java.lang.InterruptedException
        org.jivesoftware.smack.XMPPException
        org.jivesoftware.smack.SmackException
      • getAdvancedConfigurationCommand

        public org.jivesoftware.smackx.commands.RemoteCommand getAdvancedConfigurationCommand()
                                                                                       throws java.lang.InterruptedException,
                                                                                              org.jivesoftware.smack.XMPPException,
                                                                                              org.jivesoftware.smack.SmackException
        Throws:
        java.lang.InterruptedException
        org.jivesoftware.smack.XMPPException
        org.jivesoftware.smack.SmackException
      • getMessageUidOfLatestMessage

        public java.lang.String getMessageUidOfLatestMessage()
                                                      throws org.jivesoftware.smack.SmackException.NoResponseException,
                                                             org.jivesoftware.smack.XMPPException.XMPPErrorException,
                                                             org.jivesoftware.smack.SmackException.NotConnectedException,
                                                             org.jivesoftware.smack.SmackException.NotLoggedInException,
                                                             java.lang.InterruptedException
        Lookup the archive's message ID of the latest message in the archive. Returns null if the archive is empty.
        Returns:
        the ID of the lastest message or null.
        Throws:
        org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the remote entity.
        org.jivesoftware.smack.XMPPException.XMPPErrorException - if there was an XMPP error returned.
        org.jivesoftware.smack.SmackException.NotConnectedException - if the XMPP connection is not connected.
        org.jivesoftware.smack.SmackException.NotLoggedInException - if the XMPP connection is not authenticated.
        java.lang.InterruptedException - if the calling thread was interrupted.
        Since:
        4.3.0
      • retrieveArchivingPreferences

        public MamManager.MamPrefsResult retrieveArchivingPreferences()
                                                               throws org.jivesoftware.smack.SmackException.NoResponseException,
                                                                      org.jivesoftware.smack.XMPPException.XMPPErrorException,
                                                                      org.jivesoftware.smack.SmackException.NotConnectedException,
                                                                      java.lang.InterruptedException,
                                                                      org.jivesoftware.smack.SmackException.NotLoggedInException
        Get the preferences stored in the server.
        Returns:
        the MAM preferences result
        Throws:
        org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the remote entity.
        org.jivesoftware.smack.XMPPException.XMPPErrorException - if there was an XMPP error returned.
        org.jivesoftware.smack.SmackException.NotConnectedException - if the XMPP connection is not connected.
        java.lang.InterruptedException - if the calling thread was interrupted.
        org.jivesoftware.smack.SmackException.NotLoggedInException - if the XMPP connection is not authenticated.
      • updateArchivingPreferences

        public MamManager.MamPrefsResult updateArchivingPreferences​(MamManager.MamPrefs mamPrefs)
                                                             throws org.jivesoftware.smack.SmackException.NoResponseException,
                                                                    org.jivesoftware.smack.XMPPException.XMPPErrorException,
                                                                    org.jivesoftware.smack.SmackException.NotConnectedException,
                                                                    java.lang.InterruptedException,
                                                                    org.jivesoftware.smack.SmackException.NotLoggedInException
        Update the preferences in the server.
        Parameters:
        mamPrefs - the MAM preferences to set the archive to
        Returns:
        the currently active preferences after the operation.
        Throws:
        org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the remote entity.
        org.jivesoftware.smack.XMPPException.XMPPErrorException - if there was an XMPP error returned.
        org.jivesoftware.smack.SmackException.NotConnectedException - if the XMPP connection is not connected.
        java.lang.InterruptedException - if the calling thread was interrupted.
        org.jivesoftware.smack.SmackException.NotLoggedInException - if the XMPP connection is not authenticated.
        Since:
        4.3.0
      • enableMamForAllMessages

        public MamManager.MamPrefsResult enableMamForAllMessages()
                                                          throws org.jivesoftware.smack.SmackException.NoResponseException,
                                                                 org.jivesoftware.smack.XMPPException.XMPPErrorException,
                                                                 org.jivesoftware.smack.SmackException.NotConnectedException,
                                                                 org.jivesoftware.smack.SmackException.NotLoggedInException,
                                                                 java.lang.InterruptedException
        Throws:
        org.jivesoftware.smack.SmackException.NoResponseException
        org.jivesoftware.smack.XMPPException.XMPPErrorException
        org.jivesoftware.smack.SmackException.NotConnectedException
        org.jivesoftware.smack.SmackException.NotLoggedInException
        java.lang.InterruptedException
      • enableMamForRosterMessages

        public MamManager.MamPrefsResult enableMamForRosterMessages()
                                                             throws org.jivesoftware.smack.SmackException.NoResponseException,
                                                                    org.jivesoftware.smack.XMPPException.XMPPErrorException,
                                                                    org.jivesoftware.smack.SmackException.NotConnectedException,
                                                                    org.jivesoftware.smack.SmackException.NotLoggedInException,
                                                                    java.lang.InterruptedException
        Throws:
        org.jivesoftware.smack.SmackException.NoResponseException
        org.jivesoftware.smack.XMPPException.XMPPErrorException
        org.jivesoftware.smack.SmackException.NotConnectedException
        org.jivesoftware.smack.SmackException.NotLoggedInException
        java.lang.InterruptedException
      • setDefaultBehavior

        public MamManager.MamPrefsResult setDefaultBehavior​(MamPrefsIQ.DefaultBehavior desiredDefaultBehavior)
                                                     throws org.jivesoftware.smack.SmackException.NoResponseException,
                                                            org.jivesoftware.smack.XMPPException.XMPPErrorException,
                                                            org.jivesoftware.smack.SmackException.NotConnectedException,
                                                            org.jivesoftware.smack.SmackException.NotLoggedInException,
                                                            java.lang.InterruptedException
        Throws:
        org.jivesoftware.smack.SmackException.NoResponseException
        org.jivesoftware.smack.XMPPException.XMPPErrorException
        org.jivesoftware.smack.SmackException.NotConnectedException
        org.jivesoftware.smack.SmackException.NotLoggedInException
        java.lang.InterruptedException