Package tigase.xmpp.impl

## Class PresenceAbstract

- java.lang.Object
- - tigase.xmpp.XMPPProcessor
  - - tigase.xmpp.impl.annotation.AnnotatedXMPPProcessor
    - - tigase.xmpp.impl.PresenceAbstract

- All Implemented Interfaces:
    `java.lang.Comparable<XMPPImplIfc>`, `XMPPImplIfc`, `XMPPProcessorConcurrencyAwareIfc`, `XMPPProcessorIfc`
  Direct Known Subclasses:
    `PresenceOffline`, `PresenceState`, `PresenceSubscription`

      public abstract class PresenceAbstract
      extends AnnotatedXMPPProcessor
      implements XMPPProcessorIfc

  Class responsible for handling Presence packets
  Author:
    Artur Hefczyc

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static java.lang.String` | `PRESENCE_ELEMENT_NAME` |
    `static java.lang.String` | `PRESENCE_PROBE_FULL_JID_KEY` |
    `protected static boolean` | `probeFullJID` |
    `protected RosterAbstract` | `roster_util` |
    `static java.lang.String` | `SKIP_OFFLINE_PROP_KEY` |
    `static java.lang.String` | `SKIP_OFFLINE_SYS_PROP_KEY` |
    `protected static boolean` | `skipOffline` |
    `static java.lang.String` | `USERS_STATUS_CHANGES` |
    `protected static java.lang.String` | `XMLNS` |

    - ### Fields inherited from class tigase.xmpp.XMPPProcessor

      `ALL_NAMES, ALL_PATHS, cmpInfo`

    - ### Fields inherited from interface tigase.xmpp.XMPPImplIfc

      `CLIENT_XMLNS`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `PresenceAbstract()` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `broadcastProbe​(XMPPResourceConnection session, java.util.Queue<Packet> results, java.util.Map<java.lang.String,​java.lang.Object> settings)` | `sendPresenceBroadcast` method broadcasts given presence to all buddies from roster and to all users to which direct presence was sent.
    `int` | `concurrentQueuesNo()` | Methods returns a preferable number of threads/packets queues for the plugin.
    `protected static void` | `forwardPresence​(java.util.Queue<Packet> results, Packet packet, JID from)` | Simply forwards packet to the destination
    `boolean` | `getProbeFullJID()` |
    `protected static RosterAbstract` | `getRosterUtil()` | Returns shared instance of class implementing `RosterAbstract` - either default one (`RosterFlat`) or the one configured with "roster-implementation" property.
    `boolean` | `isSkipOffline()` |
    `boolean` | `isSkipOfflineSys()` |
    `protected static Element` | `prepareProbe​(XMPPResourceConnection session)` |
    `protected static boolean` | `requiresPresenceSending​(RosterAbstract roster, JID buddy, XMPPResourceConnection session, boolean systemCheck)` | Method checks whether a given contact requires sending presence.
    `static void` | `sendPresence​(StanzaType t, BareJID from, BareJID to, java.util.Queue<Packet> results, Element pres)` | Sends Presence stanza from provided parameters without returning created result `Packet` object.
    `static Packet` | `sendPresence​(StanzaType t, JID from, JID to, java.util.Queue<Packet> results, Element pres)` | Sends Presence stanza from provided parameters as well as returns created result `Packet` object.
    `void` | `setProbeFullJID​(boolean probeFullJID)` |
    `void` | `setSkipOffline​(boolean skipOffline)` |
    `void` | `setSkipOfflineSys​(boolean skipOfflineSys)` |
    `static void` | `updatePresenceChange​(Packet presence, XMPPResourceConnection session, java.util.Queue<Packet> results)` | `updatePresenceChange` method is used to broadcast to all active resources presence stanza received from other users, like incoming availability presence, subscription presence and so on...
    `static void` | `updateUserResources​(Element presence, XMPPResourceConnection session, java.util.Queue<Packet> results, boolean initial)` | `updateUserResources` method is used to broadcast to all other resources presence stanza from one user resource.

    - ### Methods inherited from class tigase.xmpp.impl.annotation.AnnotatedXMPPProcessor

      `id, supDiscoFeatures, supElementNamePaths, supNamespaces, supStreamFeatures, supTypes`

    - ### Methods inherited from class tigase.xmpp.XMPPProcessor

      `canHandle, compareTo, getComponentInfo, getInstance, getQueueSize, getStatistics, getThreadsNo, init, toString`

    - ### Methods inherited from class java.lang.Object

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

    - ### Methods inherited from interface java.lang.Comparable

      `compareTo`

    - ### Methods inherited from interface tigase.xmpp.XMPPImplIfc

      `canHandle, getComponentInfo, getStatistics, id, init, supDiscoFeatures, supElementNamePaths, supNamespaces, supStreamFeatures, supTypes`

    - ### Methods inherited from interface tigase.xmpp.XMPPProcessorIfc

      `process`

- - ### Field Detail

    - #### PRESENCE_ELEMENT_NAME

          public static final java.lang.String PRESENCE_ELEMENT_NAME

      See Also:
        Constant Field Values

    - #### SKIP_OFFLINE_PROP_KEY

          public static final java.lang.String SKIP_OFFLINE_PROP_KEY

      See Also:
        Constant Field Values

    - #### PRESENCE_PROBE_FULL_JID_KEY

          public static final java.lang.String PRESENCE_PROBE_FULL_JID_KEY

      See Also:
        Constant Field Values

    - #### SKIP_OFFLINE_SYS_PROP_KEY

          public static final java.lang.String SKIP_OFFLINE_SYS_PROP_KEY

      See Also:
        Constant Field Values

    - #### USERS_STATUS_CHANGES

          public static final java.lang.String USERS_STATUS_CHANGES

      See Also:
        Constant Field Values

    - #### XMLNS

          protected static final java.lang.String XMLNS

      See Also:
        Constant Field Values

    - #### probeFullJID

          @ConfigField(desc="Probe full JID",
                       alias="probe-full-jid")
          protected static boolean probeFullJID

    - #### skipOffline

          @ConfigField(desc="Skip offline",
                       alias="skip-offline")
          protected static boolean skipOffline

    - #### roster_util

          protected RosterAbstract roster_util

  - ### Constructor Detail

    - #### PresenceAbstract

          public PresenceAbstract()

  - ### Method Detail

    - #### forwardPresence

          protected static void forwardPresence​(java.util.Queue<Packet> results,
                                                Packet packet,
                                                JID from)

      Simply forwards packet to the destination
      Parameters:
        `results` - this a collection with packets which have been generated as input packet processing results.
        `packet` - to forward
        `from` - is a `JID` instance with stanza source address.

    - #### getRosterUtil

          protected static RosterAbstract getRosterUtil()

      Returns shared instance of class implementing `RosterAbstract` - either default one (`RosterFlat`) or the one configured with "roster-implementation" property.
      Returns:
        shared instance of class implementing `RosterAbstract`

    - #### prepareProbe

          protected static Element prepareProbe​(XMPPResourceConnection session)
                                         throws NotAuthorizedException

      Throws:
        `NotAuthorizedException`

    - #### requiresPresenceSending

          protected static boolean requiresPresenceSending​(RosterAbstract roster,
                                                           JID buddy,
                                                           XMPPResourceConnection session,
                                                           boolean systemCheck)
                                                    throws NotAuthorizedException,
                                                           TigaseDBException

      Method checks whether a given contact requires sending presence. In case of enabling option `skipOffline` and user being offline in the roster the presence is not sent. Alternatively enabling option `skipOfflineSys` would cause local environment check for user status and omit sending presence if the local use is offline.
      Parameters:
        `roster` - instance of class implementing `RosterAbstract`.
        `buddy` - JID of a contact for which a check is to be performed.
        `session` - user session which keeps all the user session data and also gives an access to the user's repository data.
        `systemCheck` - indicates whether the check should be only based on local environment state (`true`) or rooster state of given user should also be taken into consideration (`false`).
      Returns:
        {code true} if the contact requires sending presence (e.g. is not online and options skipOffline or skipOfflineSys are enabled)
      Throws:
        `NotAuthorizedException`
        `TigaseDBException`

    - #### sendPresence

          public static Packet sendPresence​(StanzaType t,
                                            JID from,
                                            JID to,
                                            java.util.Queue<Packet> results,
                                            Element pres)

      Sends Presence stanza from provided parameters as well as returns created result `Packet` object. In case of missing `pres` parameter a Presence stanza will be created with provided `StanzaType` type `t`, `JID` type `from` and `JID` type `to`. Otherwise Presence stanza `pres` will be cloned and `to` attribute will be set from parameter `to`.
      Parameters:
        `t` - specifies type of the presence to be send.
        `from` - is a `JID` instance with stanza source address.
        `to` - is a `JID` instance with stanza destination address.
        `results` - this a collection with packets which have been generated as input packet processing results.
        `pres` - an Object of type `Element` holding Presence stanza to be sent.
      Returns:
        an instance of `Packet` holding Presence stanza created from provided parameters.

    - #### sendPresence

          public static void sendPresence​(StanzaType t,
                                          BareJID from,
                                          BareJID to,
                                          java.util.Queue<Packet> results,
                                          Element pres)

      Sends Presence stanza from provided parameters without returning created result `Packet` object. In case of missing `pres` parameter a Presence stanza will be created with provided `StanzaType` type `t`, `JID` type `from` and `JID` type `to`. Otherwise Presence stanza `pres` will be cloned and `to` attribute will be set from parameter `to`.
      Parameters:
        `t` - specifies type of the presence to be send.
        `from` - is a `JID` instance with stanza source address.
        `to` - is a `JID` instance with stanza destination address.
        `results` - this a collection with packets which have been generated as input packet processing results.
        `pres` - an Object of type `Element` holding Presence stanza to be sent.

    - #### updatePresenceChange

          public static void updatePresenceChange​(Packet presence,
                                                  XMPPResourceConnection session,
                                                  java.util.Queue<Packet> results)
                                           throws NotAuthorizedException

      `updatePresenceChange` method is used to broadcast to all active resources presence stanza received from other users, like incoming availability presence, subscription presence and so on... Initial presences are however sent only to those resources which already have sent initial presence.
      Parameters:
        `presence` - an `Element` presence received from other users, we have to change 'to' attribute to full resource JID.
        `session` - user session which keeps all the user session data and also gives an access to the user's repository data.
        `results` - this a collection with packets which have been generated as input packet processing results.
      Throws:
        `NotAuthorizedException` - if an error occurs

    - #### updateUserResources

          public static void updateUserResources​(Element presence,
                                                 XMPPResourceConnection session,
                                                 java.util.Queue<Packet> results,
                                                 boolean initial)
                                          throws NotAuthorizedException

      `updateUserResources` method is used to broadcast to all other resources presence stanza from one user resource. So if new resource connects this method updates presence information about new resource to old resources and about old resources to new resource.
      Parameters:
        `presence` - an `Element` presence received from other users, we have to change 'to' attribute to full resource JID.
        `session` - user session which keeps all the user session data and also gives an access to the user's repository data.
        `results` - this a collection with packets which have been generated as input packet processing results.
        `initial` - specifies whether this is an initial presence or not (i.e. if there is a presence data from the presence stored within user session object or not)
      Throws:
        `NotAuthorizedException` - if an error occurs

    - #### isSkipOfflineSys

          public boolean isSkipOfflineSys()

    - #### setSkipOfflineSys

          public void setSkipOfflineSys​(boolean skipOfflineSys)

    - #### isSkipOffline

          public boolean isSkipOffline()

    - #### setSkipOffline

          public void setSkipOffline​(boolean skipOffline)

    - #### getProbeFullJID

          public boolean getProbeFullJID()

    - #### setProbeFullJID

          public void setProbeFullJID​(boolean probeFullJID)

    - #### broadcastProbe

          public void broadcastProbe​(XMPPResourceConnection session,
                                     java.util.Queue<Packet> results,
                                     java.util.Map<java.lang.String,​java.lang.Object> settings)
                              throws NotAuthorizedException,
                                     TigaseDBException

      `sendPresenceBroadcast` method broadcasts given presence to all buddies from roster and to all users to which direct presence was sent. Before sending presence method calls `requiresPresenceSending()`, configured to only check local environment status (if enabled) to verify whether presence needs to be sent.
      Parameters:
        `session` - user session which keeps all the user session data and also gives an access to the user's repository data.
        `results` - this a collection with packets which have been generated as input packet processing results.
        `settings` - this map keeps plugin specific settings loaded from the Tigase server configuration.
      Throws:
        `NotAuthorizedException` - if an error occurs
        `TigaseDBException`

    - #### concurrentQueuesNo

          public int concurrentQueuesNo()

      Description copied from interface: `XMPPImplIfc`
      Methods returns a preferable number of threads/packets queues for the plugin. This number can be overwritten through configuration settings, however, a default value should be reasonably good for most standard installations. It is recommended to assign at least as much as twice a number of CPUs cores for I/O bound processing and number a number equal to CPUs cores for fast processing not slowed down by any I/O.
      Specified by:
        `concurrentQueuesNo` in interface `XMPPImplIfc`
      Overrides:
        `concurrentQueuesNo` in class `XMPPProcessor`
      Returns:
        an integer preferred number of processing threads for the plugin.