Class Presence


  • public class Presence
    extends java.lang.Object
    Presence information for a user.

    This class is used to create and set up a desired presence state for a local user (outgoing presence) or get presence states for other users (incoming presence). Presence information is divided into 2 parts: an automatic part and an application part.

    The automatic part consists of so-called presence channels and their availability. A channel is a way to communicate to a user including communication address and availability of the channel. The channels include a phone channel, a video channel, an IM channel and a calendar channel. For instance, phone channel represents a phone number of a user and current PresenceState of the channel. If the state of the phone channel is available, the user is able to receive calls. If the state is "on a call", the user is unlikely to accept a new call. The automatic part of presence information is controlled by the library and used for incoming presence only.

    The application part of presence information consists of manually published PresenceState, PresenceLocationMode and a note. These are used for both incoming and outgoing presence, and controlled by the application. Application PresenceState is a presence state that a user wants to set their client to. Application PresenceLocationMode is also controlled by the user specifying their current location. Application note is just a short string representing some user comment regarding their current status.

    Although there are many aspects to presence information, there is also an overall presence state populated automatically. The overall state should be used to represent the state of the user.

    See Also:
    PresenceService
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int OPTION_LOCATION_MODE
      Indicates support for presence location modes.
      static int OPTION_MANUAL_STATE
      Indicates support for a manual (user-assigned) presence state.
      static int OPTION_NONE
      Indicates that no options are available.
      static int OPTION_NOTE
      Indicates support for presence notes.
    • Constructor Summary

      Constructors 
      Constructor Description
      Presence()
      A default constructor.
      Presence​(int supportedOptions)
      A constructor initializing the object with the given supported presence options.
    • Field Detail

      • OPTION_NONE

        public static final int OPTION_NONE
        Indicates that no options are available.
        See Also:
        Constant Field Values
      • OPTION_MANUAL_STATE

        public static final int OPTION_MANUAL_STATE
        Indicates support for a manual (user-assigned) presence state.
        See Also:
        Constant Field Values
      • OPTION_LOCATION_MODE

        public static final int OPTION_LOCATION_MODE
        Indicates support for presence location modes.
        See Also:
        Constant Field Values
      • OPTION_NOTE

        public static final int OPTION_NOTE
        Indicates support for presence notes.
        See Also:
        Constant Field Values
    • Constructor Detail

      • Presence

        public Presence()
        A default constructor.
      • Presence

        public Presence​(int supportedOptions)
        A constructor initializing the object with the given supported presence options.
        Parameters:
        supportedOptions - supported presence options to initialize the object with.
        See Also:
        OPTION_MANUAL_STATE, OPTION_LOCATION_MODE, OPTION_NOTE
    • Method Detail

      • getSupportedOptions

        public int getSupportedOptions()
        Returns the set of supported options for this presence object.
        Returns:
        Supported options of this presence information object.
        See Also:
        setSupportedOptions(int)
      • setSupportedOptions

        public void setSupportedOptions​(int supportedOptions)
        Specifies the set of supported options for this presence object.

        Some aspects of the presence object are optional and these options control how the presence publication will manage the tuples associated with the optional elements. For example, if the OPTION_NOTE option is set and the note string is empty, any existing note on the server will be removed. If the option is not set the note will not be changed.

        Parameters:
        supportedOptions - The set of supported options.
        See Also:
        OPTION_MANUAL_STATE, OPTION_LOCATION_MODE, OPTION_NOTE
      • getPresentity

        public java.lang.String getPresentity()
        Presentity is the address of the user that this presence information is associated with.
        Returns:
        The presentity associated with this presence information object.
      • getOverallState

        public PresenceState getOverallState()
        For incoming presence, returns the overall presence state as determined by the availability calculation.
        Returns:
        Overall PresenceState of this presence information object.
      • getManualState

        public PresenceState getManualState()
        Returns the manual presence state set by the user, if any.
        Returns:
        Manual PresenceState of this presence information object.

        If the value of the manual state is PresenceState.UNSPECIFIED, no manual state is set and the overall presence state is determined automatically.

      • setManualState

        public void setManualState​(PresenceState manualState)
        Sets the manual presence state.

        This state will override any automatic state until removed.

        Parameters:
        manualState - Manual PresenceState to set.
        See Also:
        getManualState()
      • getPhoneState

        public PresenceState getPhoneState()
        Returns the presence state of the phone channel, if any.
        Returns:
        Phone channel PresenceState of this presence information object.
      • setPhoneState

        public void setPhoneState​(PresenceState phoneState)
        Sets the presence state of the phone channel.
        Parameters:
        phoneState - Phone channel PresenceState to set.
      • getPhoneContact

        public java.lang.String getPhoneContact()
        Returns the contact address associated with the phone channel, if any.
        Returns:
        Phone contact address of this presence information object.
      • getVideoState

        public PresenceState getVideoState()
        Returns the presence state of the video channel, if any.
        Returns:
        Video channel PresenceState of this presence information object.
      • setVideoState

        public void setVideoState​(PresenceState videoState)
        Sets the presence state of the video channel.
        Parameters:
        videoState - Video channel PresenceState to set.
      • getVideoContact

        public java.lang.String getVideoContact()
        Returns the contact address associated with the video channel, if any.
        Returns:
        Video contact address of this presence information object.
      • getEnterpriseIMState

        public PresenceState getEnterpriseIMState()
        Returns the presence state of the enterprise instant messaging channel, if any.
        Returns:
        Enterprise IM channel PresenceState of this presence information object.
      • setEnterpriseIMState

        public void setEnterpriseIMState​(PresenceState enterpriseIMState)
        Sets the presence state of the enterprise instant messaging channel.
        Parameters:
        enterpriseIMState - Enterprise IM channel PresenceState to set.
      • getEnterpriseIMContact

        public java.lang.String getEnterpriseIMContact()
        Returns the contact address associated with the enterprise instant messaging channel, if any.
        Returns:
        Enterprise IM contact address of this presence information object.
      • getCalendarState

        public PresenceState getCalendarState()
        Returns the presence state of the calendar channel, if any.
        Returns:
        Calendar channel PresenceState of this presence information object.
      • getCalendarStartDate

        public java.util.Date getCalendarStartDate()
        Returns the user's appointment or meeting start date associated with the calendar state, if any.
        Returns:
        User's appointment or meeting start date, if any. Null otherwise.
      • getCalendarEndDate

        public java.util.Date getCalendarEndDate()
        Returns the user's appointment or meeting end date associated with the calendar state, if any.
        Returns:
        User's appointment or meeting end date, if any. Null otherwise.
      • setLocationMode

        public void setLocationMode​(PresenceLocationMode locationMode)
        Sets the location-based "mode" of the user to provide the local user's desired location mode.
        Parameters:
        locationMode - PresenceLocationMode to set.
      • getNote

        public java.lang.String getNote()
        Returns the presence note, if any.
        Returns:
        Presence note of this presence information object.
      • setNote

        public void setNote​(java.lang.String note)
        Sets the presence note to provide the local user's desired presence note.
        Parameters:
        note - Note string to set.