Package org.jivesoftware.smackx.mam

Class MamManager

java.lang.Object

org.jivesoftware.smack.Manager

org.jivesoftware.smackx.mam.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

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	MamManager.MamPrefs
static final class	MamManager.MamPrefsResult	MAM preferences result class.
final class	MamManager.MamQuery
static final class	MamManager.MamQueryArgs
static final class	MamManager.MamQueryPage

Method Summary

Modifier and Type	Method	Description
MamManager.MamPrefsResult	enableMamForAllMessages()
MamManager.MamPrefsResult	enableMamForRosterMessages()
org.jivesoftware.smackx.commands.AdHocCommand	getAdvancedConfigurationCommand()
org.jxmpp.jid.Jid	getArchiveAddress()	the XMPP address of this MAM archive.
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.
static MamManager	getInstanceFor(org.jivesoftware.smack.XMPPConnection connection, org.jxmpp.jid.Jid archiveAddress)
static MamManager	getInstanceFor(org.jivesoftware.smackx.muc.MultiUserChat multiUserChat)	Get a MamManager for the MAM archive of the given MultiUserChat.
String	getMamNamespace()	Returns the MAM namespace used by this MamManager.
String	getMessageUidOfLatestMessage()	Lookup the archive's message ID of the latest message in the archive.
boolean	isAdvancedConfigurationSupported()
boolean	isSupported()	Check if this MamManager's archive address supports MAM.
MamManager.MamQuery	queryArchive(MamManager.MamQueryArgs mamQueryArgs)
MamManager.MamQuery	queryMostRecentPage(org.jxmpp.jid.Jid jid, int max)
MamManager.MamPrefsResult	retrieveArchivingPreferences()	Get the preferences stored in the server.
List<org.jivesoftware.smackx.xdata.FormField>	retrieveFormFields()	Get the form fields supported by the server.
List<org.jivesoftware.smackx.xdata.FormField>	retrieveFormFields(String node)	Get the form fields supported by the server.
MamManager.MamPrefsResult	setDefaultBehavior(MamPrefsIQ.DefaultBehavior desiredDefaultBehavior)
MamManager.MamPrefsResult	updateArchivingPreferences(MamManager.MamPrefs mamPrefs)	Update the preferences in the server.

Methods inherited from class org.jivesoftware.smack.Manager

connection, getAuthenticatedConnectionOrThrow, schedule, schedule, scheduleBlocking

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

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 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

getMamNamespace

public String getMamNamespace()
                       throws org.jivesoftware.smack.XMPPException.XMPPErrorException,
org.jivesoftware.smack.SmackException.NotConnectedException,
org.jivesoftware.smack.SmackException.NoResponseException,
InterruptedException

Returns the MAM namespace used by this MamManager. If the archive does not support any MAM namespace supported by Smack, null is returned.

Returns:

the MAM namespace used by this manager, null if MAM is not supported

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.

InterruptedException - if the calling thread was interrupted.

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,
InterruptedException

Throws:

org.jivesoftware.smack.SmackException.NoResponseException

org.jivesoftware.smack.XMPPException.XMPPErrorException

org.jivesoftware.smack.SmackException.NotConnectedException

org.jivesoftware.smack.SmackException.NotLoggedInException

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,
InterruptedException

Throws:

org.jivesoftware.smack.SmackException.NoResponseException

org.jivesoftware.smack.XMPPException.XMPPErrorException

org.jivesoftware.smack.SmackException.NotConnectedException

org.jivesoftware.smack.SmackException.NotLoggedInException

InterruptedException

retrieveFormFields

public List<org.jivesoftware.smackx.xdata.FormField> retrieveFormFields()
                                                                 throws org.jivesoftware.smack.SmackException.NoResponseException,
org.jivesoftware.smack.XMPPException.XMPPErrorException,
org.jivesoftware.smack.SmackException.NotConnectedException,
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.

InterruptedException - if the calling thread was interrupted.

org.jivesoftware.smack.SmackException.NotLoggedInException - if the XMPP connection is not authenticated.

retrieveFormFields

public List<org.jivesoftware.smackx.xdata.FormField> retrieveFormFields(String node)
                                                                 throws org.jivesoftware.smack.SmackException.NoResponseException,
org.jivesoftware.smack.XMPPException.XMPPErrorException,
org.jivesoftware.smack.SmackException.NotConnectedException,
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.

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,
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.

InterruptedException - if the calling thread was interrupted.

Since:

4.2.1

See Also:

• XEP-0313 § 7. Determining support

isAdvancedConfigurationSupported

public boolean isAdvancedConfigurationSupported()
                                         throws InterruptedException,
org.jivesoftware.smack.XMPPException,
org.jivesoftware.smack.SmackException

Throws:

InterruptedException

org.jivesoftware.smack.XMPPException

org.jivesoftware.smack.SmackException

getAdvancedConfigurationCommand

public org.jivesoftware.smackx.commands.AdHocCommand getAdvancedConfigurationCommand()
                                                                              throws InterruptedException,
org.jivesoftware.smack.XMPPException,
org.jivesoftware.smack.SmackException

Throws:

InterruptedException

org.jivesoftware.smack.XMPPException

org.jivesoftware.smack.SmackException

getMessageUidOfLatestMessage

public String getMessageUidOfLatestMessage()
                                    throws org.jivesoftware.smack.SmackException.NoResponseException,
org.jivesoftware.smack.XMPPException.XMPPErrorException,
org.jivesoftware.smack.SmackException.NotConnectedException,
org.jivesoftware.smack.SmackException.NotLoggedInException,
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.

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,
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.

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,
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.

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,
InterruptedException

Throws:

org.jivesoftware.smack.SmackException.NoResponseException

org.jivesoftware.smack.XMPPException.XMPPErrorException

org.jivesoftware.smack.SmackException.NotConnectedException

org.jivesoftware.smack.SmackException.NotLoggedInException

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,
InterruptedException

Throws:

org.jivesoftware.smack.SmackException.NoResponseException

org.jivesoftware.smack.XMPPException.XMPPErrorException

org.jivesoftware.smack.SmackException.NotConnectedException

org.jivesoftware.smack.SmackException.NotLoggedInException

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,
InterruptedException

Throws:

org.jivesoftware.smack.SmackException.NoResponseException

org.jivesoftware.smack.XMPPException.XMPPErrorException

org.jivesoftware.smack.SmackException.NotConnectedException

org.jivesoftware.smack.SmackException.NotLoggedInException

InterruptedException