Package tigase.xmpp.impl.roster

# Interface DynamicRosterIfc

All Known Implementing Classes:
  `AnonymousRoster`, `DynamicRosterTest`, `DynamicRosterTest123`

public interface DynamicRosterIfc
Interface `DynamicRosterIfc` is to dynamically generate user roster entries when the user requests the roster content. The dynamic roster feature doesn't replace the normal roster with entries added by the user. It just allows you to inject extra contacts lists to the user roster.
There is a very simple example implementing this interface which creates roster entries for anonymous users - `tigase.xmpp.impl.AnonymousRoster`. You can use it as a starting point for your code.
You can have as many implementations of this interface loaded at the same time as you need and all of them are called for each user roster request.
To load your implementations you have to specify them in the configuration file. The simplest way is to use `config.tdsl` file. Have a look at the example file available in the repository. Following line added to the end of the file tell the server to load the dynamic roster implementation:

    sess-man/plugins-conf/dynamic-roster-classes=tigase.xmpp.impl.AnonymousRoster

If you want to load more implementations you just put a comma separated list of classes instead. If your implementation needs to connect to a database or any other resource or just needs extra configuration parameters you can also specify them in the properties file:

    sess-man/plugins-conf/dynamic-roster-classes=tigase.xmpp.impl.AnonymousRoster
     sess-man/plugins-conf/dbinit=jdbc:jtds:mysql://localhost/roster-db;user=user-name;password=db-passwd
     sess-man/plugins-conf/max-buddies=1000

Basically all parameters starting with string: `sess-man/plugins-conf/` will be provided at initialization time in the `init(....)` method.
There is also a simplified form for providing configuration parameters. It is used if you want to provide just one parameter to the object (like database connection string):

    sess-man/plugins-conf/tigase.xmpp.impl.AnonymousRoster.init=configuration-string

Created: Mon Oct 29 08:52:22 2007

Author:
  Artur Hefczyc

- ## Method Summary

  Modifier and Type
  Method
  Description
  `JID[]`
  `getBuddies(XMPPResourceConnection session)`
  `getBuddies` method returns `String` array with all roster buddies JIDs.
  `Element`
  `getBuddyItem(XMPPResourceConnection session, JID buddy)`
  `getBuddyItem` method returns buddy item element for a given JID or `null` if the buddy doesn't exist on the user roster list.
  `Element`
  `getItemExtraData(Element item)`
  Returns a new roster Item element with additional, non-standard information for a given item.
  `List<Element>`
  `getRosterItems(XMPPResourceConnection session)`
  `getRosterItems` method returns a full list with all buddies generated by this dynamic roster implementation.
  `void`
  `init(String par)`
  Deprecated.
  `void`
  `init(Map<String,Object> props)`
  Deprecated.
  `void`
  `setItemExtraData(Element item)`

- ## Method Details

  - ### init

    @Deprecated void init(Map<String,Object> props)
    Deprecated.
    `init` method is used to provide configuration parameters and initialize the object. Please have a look at the interface description for more details about configuration parameters. The object is never used before it's `init(...)` method is called but it might be used straight away after the method has finished.
    Parameters:
      `props` - a `Map<String, Object> props` is a configuration parameters map in the form: key:value exactly as they were specified in the configuration file.

  - ### init

    @Deprecated void init(String par)
    Deprecated.
    `init` method is called at the initialization time when simple form of startup parameters are used:

        sess-man/plugins-conf/class-name.init=configuration-string

    The `configuration-string` is passed to this `init(...)` method in exact form as it was found in the configuration file.
    Parameters:
      `par` - a `String` value of the configuration string.

  - ### getBuddies

    JID[] getBuddies(XMPPResourceConnection session) throws NotAuthorizedException, RosterRetrievingException, RepositoryAccessException
    `getBuddies` method returns `String` array with all roster buddies JIDs. Normally they are bare JIDs (without resource part). This method is normally used by presence plugin to send probe and initial presence to all contacts in the dynamic roster.
    Parameters:
      `session` - a `XMPPResourceConnection` value of the connection session object.
    Returns:
      a `String[]` array of bare JIDs for the dynamic part of the user roster.
    Throws:
      `NotAuthorizedException` - may be thrown if the connection session is not yet authenticated but authorization is required to access roster data.
      `RosterRetrievingException` - may be thrown when an unknown error in the custom roster retrieving logic occurs. A message from the exception must be sent back to a user as an error message.
      `RepositoryAccessException` - may be thrown when there is an error accessing the roster data repository, even though the user is correctly authenticated. No error is sent back to a user, only an empty roster but the repository exception is logged to the log file.

  - ### getBuddyItem

    Element getBuddyItem(XMPPResourceConnection session, JID buddy) throws NotAuthorizedException, RosterRetrievingException, RepositoryAccessException
    `getBuddyItem` method returns buddy item element for a given JID or `null` if the buddy doesn't exist on the user roster list.
    Parameters:
      `session` - a `XMPPResourceConnection` value of the connection session object.
      `buddy` - a `String` value of the buddy JID. It may be bare JID or full JID.
    Returns:
      an `Element` value of the XML element with all the roster item data - JID, subscription, nick name and groups. Sample code for creating the buddy element could look like this:

          Element item = new Element("item", new Element[] {
               new Element("group", "Tigase devs")},
            new String[] {"jid", "subscription", "name"},
            new String[] {peer, "both", JIDUtils.getNodeNick(peer)});

    Throws:
      `NotAuthorizedException` - may be thrown if the connection session is not yet authenticated but authorization is required to access roster data.
      `RosterRetrievingException` - may be thrown when an unknown error in the custom roster retrieving logic occurs. A message from the exception must be sent back to a user as an error message.
      `RepositoryAccessException` - may be thrown when there is an error accessing the roster data repository, even though the user is correctly authenticated. No error is sent back to a user, only an empty roster but the repository exception is logged to the log file.

  - ### getItemExtraData

    Element getItemExtraData(Element item)
    Returns a new roster Item element with additional, non-standard information for a given item. This is a way to associate custom roster information with a contact.
    Parameters:
      `item` - is a `Element`
    Returns:
      a value of `Element`

  - ### getRosterItems

    List<Element> getRosterItems(XMPPResourceConnection session) throws NotAuthorizedException, RosterRetrievingException, RepositoryAccessException
    `getRosterItems` method returns a full list with all buddies generated by this dynamic roster implementation. The list contains all contacts for the roster with all contacts details - buddy JID, nick name, subscription (typically always both) and groups. Please have a look at `getBuddyItem(...)` description for details how to create an Element entry for the roster item.
    In theory you could here call the `getBuddies(...)` method and then for each entry from the array call the `getBuddyItem(...)`. I strongly advice to not do it. This is a server with thousands of connected users and possibly thousands of packets going through the server. Think of a performance and execute database query once if possible rather then many times.
    Parameters:
      `session` - a `XMPPResourceConnection` value of the connection session object.
    Returns:
      a `List<Element>` value
    Throws:
      `NotAuthorizedException` - may be thrown if the connection session is not yet authenticated but authorization is required to access roster data.
      `RosterRetrievingException` - may be thrown when an unknown error in the custom roster retrieving logic occurs. A message from the exception must be sent back to a user as an error message.
      `RepositoryAccessException` - may be thrown when there is an error accessing the roster data repository, even though the user is correctly authenticated. No error is sent back to a user, only an empty roster but the repository exception is logged to the log file.

  - ### setItemExtraData

    void setItemExtraData(Element item)