Package tigase.xmpp.impl

## Class PresenceState

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

- All Implemented Interfaces:
    `java.lang.Comparable<XMPPImplIfc>`, `XMPPImplIfc`, `XMPPProcessorConcurrencyAwareIfc`, `XMPPProcessorIfc`, `XMPPStopListenerIfc`

      @Bean(name="presence-state",
            parent=SessionManager.class,
            active=true)
      public class PresenceState
      extends PresenceAbstract
      implements XMPPStopListenerIfc

  Author:
    andrzej

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static interface` | `PresenceState.ExtendedPresenceProcessorIfc` |

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static java.lang.String` | `DIRECT_PRESENCE` | `DIRECT_PRESENCE` is a key in temporary session data for the collection of JIDs where direct presence was sent.
    `static java.lang.String` | `ENABLE_ROSTER_LAZY_LOADING_KEY` |
    `static java.lang.String` | `EXTENDED_PRESENCE_PROCESSORS_KEY` |
    `protected static int` | `HIGH_PRIORITY_PRESENCES_NO` |
    `protected static java.lang.String` | `ID` |
    `static java.lang.String` | `OFFLINE_BUD_SENT` |
    `static java.lang.String` | `OFFLINE_RES_SENT` |
    `static java.lang.String` | `OFFLINE_ROSTER_LAST_SEEN_PROP_KEY` |
    `static java.lang.String` | `PRESENCE_GLOBAL_FORWARD` | key allowing setting global forwarding JID address.

    - ### Fields inherited from class tigase.xmpp.impl.PresenceAbstract

      `PRESENCE_ELEMENT_NAME, PRESENCE_PROBE_FULL_JID_KEY, probeFullJID, roster_util, SKIP_OFFLINE_PROP_KEY, SKIP_OFFLINE_SYS_PROP_KEY, skipOffline, USERS_STATUS_CHANGES, 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
    --- | ---
    `PresenceState()` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static void` | `addDirectPresenceJID​(JID jid, XMPPResourceConnection session)` | Add JID to collection of JIDs to which direct presence was sent.
    `protected static void` | `broadcastDirectPresences​(StanzaType t, XMPPResourceConnection session, java.util.Queue<Packet> results, Element pres)` | `broadcastDirectPresences` broadcast a direct Presence from provided `pres` `Element` object to the collection of JIDs stored in temporary session data under key `DIRECT_PRESENCE`.
    `static void` | `broadcastOffline​(XMPPResourceConnection session, java.util.Queue<Packet> results, java.util.Map<java.lang.String,​java.lang.Object> settings, RosterAbstract roster_util)` | `sendPresenceBroadcast` method broadcasts given presence to all buddies from roster and to all users to which direct presence was sent.
    `protected void` | `buddyOnline​(XMPPResourceConnection session, JID buddy, java.util.Queue<Packet> results, boolean online)` | Method sends back presence to contact while it becomes online (i.e. during processing of incoming initial presence of the contact/buddy)
    `void` | `getStatistics​(StatisticsList list)` | The method allows to retrieve plugin own statistics if it generates any.
    `void` | `process​(Packet packet, XMPPResourceConnection session, NonAuthUserRepository repo, java.util.Queue<Packet> results, java.util.Map<java.lang.String,​java.lang.Object> settings)` | Performs processing of presence packets and calls different methods for particular `RosterAbstract.PresenceType`
    `protected void` | `processError​(Packet packet, XMPPResourceConnection session, java.util.Queue<Packet> results, java.util.Map<java.lang.String,​java.lang.Object> settings, RosterAbstract.PresenceType presenceType)` | Process presence stanza of type Error.
    `protected void` | `processInInitial​(Packet packet, XMPPResourceConnection session, java.util.Queue<Packet> results, java.util.Map<java.lang.String,​java.lang.Object> settings, RosterAbstract.PresenceType presenceType)` | Method is responsible for processing incoming initial presence (i.e. in the receivers session manager).
    `protected void` | `processInProbe​(Packet packet, XMPPResourceConnection session, java.util.Queue<Packet> results, java.util.Map<java.lang.String,​java.lang.Object> settings, RosterAbstract.PresenceType presenceType)` | Method is responsible for processing incoming presence probe (i.e. in the receivers session manager).
    `protected void` | `processOutInitial​(Packet packet, XMPPResourceConnection session, java.util.Queue<Packet> results, java.util.Map<java.lang.String,​java.lang.Object> settings, RosterAbstract.PresenceType type)` | Method is responsible for processing outgoing initial presence (i.e. in the sender session manager).
    `void` | `rebroadcastPresence​(XMPPResourceConnection session, java.util.Queue<Packet> results)` |
    `static void` | `removeDirectPresenceJID​(JID jid, XMPPResourceConnection session)` | Remove JID from collection of JIDs to which direct presence was sent.
    `void` | `resendPendingInRequests​(XMPPResourceConnection session, java.util.Queue<Packet> results)` | Sends out all pending subscription request during user log-in.
    `static void` | `sendPresenceBroadcast​(StanzaType t, XMPPResourceConnection session, java.util.EnumSet<RosterAbstract.SubscriptionType> subscrs, java.util.Queue<Packet> results, Element pres, java.util.Map<java.lang.String,​java.lang.Object> settings, RosterAbstract roster_util)` | `sendPresenceBroadcast` method broadcasts given presence to all buddies from roster and to all users to which direct presence was sent.
    `protected void` | `sendRosterOfflinePresence​(XMPPResourceConnection session, java.util.Queue<Packet> results)` | Method sends server generated presence unavailable for all buddies from the roster with a custom status message.
    `void` | `stopped​(XMPPResourceConnection session, java.util.Queue<Packet> results, java.util.Map<java.lang.String,​java.lang.Object> settings)` | Performs additional processing upon closing user session (user either disconnects or logs-out).
    `java.util.Set<StanzaType>` | `supTypes()` | Method returns an array of all stanza types which the plugin is able to handle.
    `protected static void` | `updateOfflineChange​(XMPPResourceConnection session, java.util.Queue<Packet> results)` | `updateOfflineChange` method broadcast off-line presence to all other user active resources.

    - ### Methods inherited from class tigase.xmpp.impl.PresenceAbstract

      `broadcastProbe, concurrentQueuesNo, forwardPresence, getProbeFullJID, getRosterUtil, isSkipOffline, isSkipOfflineSys, prepareProbe, requiresPresenceSending, sendPresence, sendPresence, setProbeFullJID, setSkipOffline, setSkipOfflineSys, updatePresenceChange, updateUserResources`

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

      `id, supDiscoFeatures, supElementNamePaths, supNamespaces, supStreamFeatures`

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

      `canHandle, compareTo, getComponentInfo, getInstance, getQueueSize, 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, concurrentQueuesNo, getComponentInfo, id, init, supDiscoFeatures, supElementNamePaths, supNamespaces, supStreamFeatures`

- - ### Field Detail

    - #### DIRECT_PRESENCE

          public static final java.lang.String DIRECT_PRESENCE

      `DIRECT_PRESENCE` is a key in temporary session data for the collection of JIDs where direct presence was sent. To all these addresses unavailable presence must be sent when user disconnects.
      See Also:
        Constant Field Values

    - #### ENABLE_ROSTER_LAZY_LOADING_KEY

          public static final java.lang.String ENABLE_ROSTER_LAZY_LOADING_KEY

      See Also:
        Constant Field Values

    - #### EXTENDED_PRESENCE_PROCESSORS_KEY

          public static final java.lang.String EXTENDED_PRESENCE_PROCESSORS_KEY

      See Also:
        Constant Field Values

    - #### OFFLINE_BUD_SENT

          public static final java.lang.String OFFLINE_BUD_SENT

      See Also:
        Constant Field Values

    - #### OFFLINE_RES_SENT

          public static final java.lang.String OFFLINE_RES_SENT

      See Also:
        Constant Field Values

    - #### OFFLINE_ROSTER_LAST_SEEN_PROP_KEY

          public static final java.lang.String OFFLINE_ROSTER_LAST_SEEN_PROP_KEY

      See Also:
        Constant Field Values

    - #### PRESENCE_GLOBAL_FORWARD

          public static final java.lang.String PRESENCE_GLOBAL_FORWARD

      key allowing setting global forwarding JID address.
      See Also:
        Constant Field Values

    - #### ID

          protected static final java.lang.String ID

      See Also:
        Constant Field Values

    - #### HIGH_PRIORITY_PRESENCES_NO

          protected static int HIGH_PRIORITY_PRESENCES_NO

  - ### Constructor Detail

    - #### PresenceState

          public PresenceState()

  - ### Method Detail

    - #### addDirectPresenceJID

          public static void addDirectPresenceJID​(JID jid,
                                                  XMPPResourceConnection session)

      Add JID to collection of JIDs to which direct presence was sent. To all these addresses unavailable presence must be sent when user disconnects.
      Parameters:
        `jid` - to which direct presence was sent.
        `session` - user session which keeps all the user session data and also gives an access to the user's repository data.

    - #### broadcastDirectPresences

          protected static void broadcastDirectPresences​(StanzaType t,
                                                         XMPPResourceConnection session,
                                                         java.util.Queue<Packet> results,
                                                         Element pres)
                                                  throws NotAuthorizedException,
                                                         TigaseDBException

      `broadcastDirectPresences` broadcast a direct Presence from provided `pres` `Element` object to the collection of JIDs stored in temporary session data under key `DIRECT_PRESENCE`.
      Parameters:
        `t` - specifies type of the presence to be send.
        `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.
        `pres` - an Object of type `Element` holding Presence stanza to be sent.
      Throws:
        `NotAuthorizedException`
        `TigaseDBException`

    - #### broadcastOffline

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

      `sendPresenceBroadcast` method broadcasts given presence to all buddies from roster and to all users to which direct presence was 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.
        `roster_util` - instance of class implementing `RosterAbstract`.
      Throws:
        `NotAuthorizedException` - if an error occurs
        `TigaseDBException`

    - #### removeDirectPresenceJID

          public static void removeDirectPresenceJID​(JID jid,
                                                     XMPPResourceConnection session)

      Remove JID from collection of JIDs to which direct presence was sent.
      Parameters:
        `jid` - to which direct presence was sent.
        `session` - user session which keeps all the user session data and also gives an access to the user's repository data.

    - #### sendPresenceBroadcast

          public static void sendPresenceBroadcast​(StanzaType t,
                                                   XMPPResourceConnection session,
                                                   java.util.EnumSet<RosterAbstract.SubscriptionType> subscrs,
                                                   java.util.Queue<Packet> results,
                                                   Element pres,
                                                   java.util.Map<java.lang.String,​java.lang.Object> settings,
                                                   RosterAbstract roster_util)
                                            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()` performing, if configured, both system and roster check to verify whether presence needs to be sent.
      Parameters:
        `t` - specifies type of the presence to be send.
        `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.
        `subscrs` - an `EnumSet<SubscriptionType>` holding all `RosterAbstract.SubscriptionType` to which a Presence should be broadcast.
        `pres` - an Object of type `Element` holding Presence stanza to be sent.
        `settings` - this map keeps plugin specific settings loaded from the Tigase server configuration.
        `roster_util` - instance of class implementing `RosterAbstract`.
      Throws:
        `NotAuthorizedException` - if an error occurs
        `TigaseDBException`

    - #### updateOfflineChange

          protected static void updateOfflineChange​(XMPPResourceConnection session,
                                                    java.util.Queue<Packet> results)
                                             throws NotAuthorizedException

      `updateOfflineChange` method broadcast off-line presence to all other user active resources.
      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.
      Throws:
        `NotAuthorizedException` - if an error occurs

    - #### supTypes

          public java.util.Set<StanzaType> supTypes()

      Description copied from interface: `XMPPImplIfc`
      Method returns an array of all stanza types which the plugin is able to handle. If the method returns NULL, then all stanzas of all types will be passed to the plugin for processing. Otherwise only stanzas with selected types, assuming that element names and name-spaces match as well.
      Specified by:
        `supTypes` in interface `XMPPImplIfc`
      Overrides:
        `supTypes` in class `AnnotatedXMPPProcessor`
      Returns:
        a `StanzaType[]` array of supported stanza types.

    - #### process

          public void process​(Packet packet,
                              XMPPResourceConnection session,
                              NonAuthUserRepository repo,
                              java.util.Queue<Packet> results,
                              java.util.Map<java.lang.String,​java.lang.Object> settings)
                       throws XMPPException

      Performs processing of presence packets and calls different methods for particular `RosterAbstract.PresenceType`
      Specified by:
        `process` in interface `XMPPProcessorIfc`
      Parameters:
        `packet` - packet is which being processed. This parameter may never be null. Even though this is not immutable object it mustn't be altered. None of it's fields or attributes can be changed during processing.
        `session` - user session which keeps all the user session data and also gives an access to the user's repository data. It allows for storing information in a permanent storage or in memory only during the live of the online session. This parameter can be null if there is no online user session at the time of the packet processing.
        `repo` - this is a user data storage which is normally used when the user session (parameter above) is null. This is repository allows for a very restricted access only. It allows for storing some user private data (doesn't allow overwriting existing data) like messages for offline users and it also allows for reading user public data like VCard.
        `results` - this a collection with packets which have been generated as input packet processing results. Regardless a response to a user request is sent or the packet is forwarded to it's destination it is always required that a copy of the input packet is created and stored in the results queue.
        `settings` - this map keeps plugin specific settings loaded from the Tigase server configuration. In most cases it is unused, however if the plugin needs to access an external database that this is a way to pass database connection string to the plugin.
      Throws:
        `XMPPException`

    - #### stopped

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

      Description copied from interface: `XMPPStopListenerIfc`
      Performs additional processing upon closing user session (user either disconnects or logs-out).
      Specified by:
        `stopped` in interface `XMPPStopListenerIfc`
      Parameters:
        `session` - user session which keeps all the user session data and also gives an access to the user's repository data. It allows for storing information in a permanent storage or in memory only during the live of the online session. This parameter can be null if there is no online user session at the time of the packet processing.
        `results` - this a collection with packets which have been generated as input packet processing results. Regardless a response to a user request is sent or the packet is forwarded to it's destination it is always required that a copy of the input packet is created and stored in the results queue.
        `settings` - this map keeps plugin specific settings loaded from the Tigase server configuration. In most cases it is unused, however if the plugin needs to access an external database that this is a way to pass database connection string to the plugin.

    - #### getStatistics

          public void getStatistics​(StatisticsList list)

      Description copied from interface: `XMPPImplIfc`
      The method allows to retrieve plugin own statistics if it generates any.
      Specified by:
        `getStatistics` in interface `XMPPImplIfc`
      Overrides:
        `getStatistics` in class `XMPPProcessor`
      Parameters:
        `list` - is a statistics collection to which plugins own metrics can be added.

    - #### rebroadcastPresence

          public void rebroadcastPresence​(XMPPResourceConnection session,
                                          java.util.Queue<Packet> results)
                                   throws NotAuthorizedException,
                                          TigaseDBException

      Throws:
        `NotAuthorizedException`
        `TigaseDBException`

    - #### resendPendingInRequests

          public void resendPendingInRequests​(XMPPResourceConnection session,
                                              java.util.Queue<Packet> results)
                                       throws NotAuthorizedException,
                                              TigaseDBException

      Sends out all pending subscription request during user log-in.
      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.
      Throws:
        `NotAuthorizedException`
        `TigaseDBException`

    - #### processError

          protected void processError​(Packet packet,
                                      XMPPResourceConnection session,
                                      java.util.Queue<Packet> results,
                                      java.util.Map<java.lang.String,​java.lang.Object> settings,
                                      RosterAbstract.PresenceType presenceType)
                               throws NotAuthorizedException,
                                      TigaseDBException,
                                      NoConnectionIdException

      Process presence stanza of type Error. Allows errors sent from server to user and ignore presence errors sent from the user.
      Parameters:
        `packet` - packet is which being processed.
        `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.
        `presenceType` - specifies type of the presence
      Throws:
        `NotAuthorizedException`
        `TigaseDBException`
        `NoConnectionIdException`

    - #### processInInitial

          protected void processInInitial​(Packet packet,
                                          XMPPResourceConnection session,
                                          java.util.Queue<Packet> results,
                                          java.util.Map<java.lang.String,​java.lang.Object> settings,
                                          RosterAbstract.PresenceType presenceType)
                                   throws NoConnectionIdException,
                                          NotAuthorizedException,
                                          TigaseDBException

      Method is responsible for processing incoming initial presence (i.e. in the receivers session manager).
      It validates the packet (whether from is present or if it's a direct presence to existing resource) and subsequently set received presence for the contact that sent it.
      Parameters:
        `packet` - packet is which being processed.
        `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.
        `presenceType` - specifies type of the presence.
      Throws:
        `NoConnectionIdException`
        `NotAuthorizedException`
        `TigaseDBException`

    - #### processInProbe

          protected void processInProbe​(Packet packet,
                                        XMPPResourceConnection session,
                                        java.util.Queue<Packet> results,
                                        java.util.Map<java.lang.String,​java.lang.Object> settings,
                                        RosterAbstract.PresenceType presenceType)
                                 throws NotAuthorizedException,
                                        TigaseDBException,
                                        PacketErrorTypeException

      Method is responsible for processing incoming presence probe (i.e. in the receivers session manager).
      It validates whether the packet comes from a contact that has correct subscription and responds with presence of all user's resources presences.
      Parameters:
        `packet` - packet is which being processed.
        `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.
        `presenceType` - specifies type of the presence.
      Throws:
        `NotAuthorizedException`
        `TigaseDBException`
        `PacketErrorTypeException`

    - #### processOutInitial

          protected void processOutInitial​(Packet packet,
                                           XMPPResourceConnection session,
                                           java.util.Queue<Packet> results,
                                           java.util.Map<java.lang.String,​java.lang.Object> settings,
                                           RosterAbstract.PresenceType type)
                                    throws NotAuthorizedException,
                                           TigaseDBException

      Method is responsible for processing outgoing initial presence (i.e. in the sender session manager).
      Process packet accordingly whether it's a direct presence (forward it, add to proper collection of JIDs to which a direct presence has been sent) or regular presence. THe latter causes properly address the packet, store presence within session data for subsequent use, and for the first availability presence (in case there is no prior presence stored in user session data) server sends probes to all contacts and pushes out all pending subscription request or (if there i already presence stored in session data) broadcast presence update to contacts.
      If there is a JID forwarding set up, presence is also forwarded to configured JID.
      Parameters:
        `packet` - packet is which being processed.
        `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.
        `type` - specifies type of the presence.
      Throws:
        `NotAuthorizedException`
        `TigaseDBException`

    - #### buddyOnline

          protected void buddyOnline​(XMPPResourceConnection session,
                                     JID buddy,
                                     java.util.Queue<Packet> results,
                                     boolean online)
                              throws NotAuthorizedException,
                                     TigaseDBException

      Method sends back presence to contact while it becomes online (i.e. during processing of incoming initial presence of the contact/buddy)
      Parameters:
        `session` - user session which keeps all the user session data and also gives an access to the user's repository data.
        `buddy` - `JID` of a roster element for which an online state will be set
        `results` - this a collection with packets which have been generated as input packet processing results.
        `online` - set whether given contact is online or offline
      Throws:
        `NotAuthorizedException`
        `TigaseDBException`

    - #### sendRosterOfflinePresence

          protected void sendRosterOfflinePresence​(XMPPResourceConnection session,
                                                   java.util.Queue<Packet> results)
                                            throws NotAuthorizedException,
                                                   TigaseDBException,
                                                   NoConnectionIdException

      Method sends server generated presence unavailable for all buddies from the roster with a custom status message.
      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.
      Throws:
        `NotAuthorizedException`
        `TigaseDBException`
        `NoConnectionIdException`