Package com.opencloud.javax.sip.sessiontimer

Class SessionTimerOptions

  • All Implemented Interfaces:
    Serializable
    public class SessionTimerOptions
extends Object
implements Serializable
    SessionTimerOptions values are used to specify what, if any, session timer options are to be applied to a SIP dialog.

    To create a dialog activity that uses a session timer, the dialog must be created using OCSleeSipProvider.newDialogBuilder() and DialogBuilder.withSessionTimer(SessionTimerOptions). For example: 

     OCSleeSipProvider provider = getProvider();
 SessionTimerOptions timerOptions = SessionTimerOptions.builder(300).build();

 DialogActivity dialog = provider.newDialogBuilder()
                                 .outgoing(fromAddress, toAddress)
                                 .withSessionTimer(timerOptions)
                                 .newDialog();

    SessionTimerOptions values

    SessionTimerOptions values are immutable and are created using the builder pattern to make it simpler to specify optional parameters.
    New values must have a session interval parameter. This parameter is passed to builder(int) when creating a builder so that clients must always specify the session interval. The session interval cannot be less than 90s.
    Once the builder instance is created, clients may specify the optional Min-SE and refresher values using SessionTimerOptions.Builder.minSE(int) and SessionTimerOptions.Builder.refresher(Refresher). Finally SessionTimerOptions.Builder.build() is called to create the SessionTimerOptions instance: 
     SessionTimerOptions myOptions =
         SessionTimerOptions.builder(1800)              // 1800s or 30mins session interval
                            .minSE(300)                 // Min-SE is 300s or 5mins
                            .refresher(Refresher.LOCAL) // I want to be the refresher
                            .build();
    Two special SessionTimerOptions constant values are also defined:
    • NONE indicates that no session timer is requested, this is the default behaviour when creating a dialog.
    • PROXY requests a session timer in proxy mode, see below.

    Proxy Mode

    If an application does not want to take part in session timer negotiation and refreshes, it can instead use a session timer in "proxy mode", where the dialog observes the session interval negotiated by the endpoints on the dialog, and watches for session refreshes from either endpoint. If no session refreshes are observed within the session interval, then a SessionExpiredEvent will be fired on the dialog activity.
    Proxy mode is intended for applications like B2BUAs that may want to just pass through whatever session timer options are negotiated by the endpoints, but still be notified when a session has expired so that dialog state can be cleaned up in the event of a failure.
    See Also:
    Serialized Form

    • Field Detail

      • PROXY

        public static final SessionTimerOptions PROXY
        A special SessionTimerOptions value indicating that a dialog should use session timers in "proxy mode".

        In this mode, the dialog activity doesn't request its own session expiry interval or act as a refresher, but will observe any session expiry negotiated by the endpoints of the dialog, and inform the application that a session has expired if neither endpoint refreshes the dialog within the session expiry interval.

      • LOWEST_MIN_SE

        public static final int LOWEST_MIN_SE
        The lowest permitted session expires value, 90s.
        See Also:
        Constant Field Values

    • Method Detail

      • hasSessionTimer

        public boolean hasSessionTimer()
        Determine if these SessionTimerOptions are requesting a session timer. All values except NONE and PROXY request a session timer.
        Returns:
        false if this value is NONE or PROXY, otherwise true

      • hasRefresher

        public boolean hasRefresher()
        Determine if this SessionTimerOptions value specified a refresher.
        Returns:
        false if the configured refresher is Refresher.NONE, otherwise true

      • hasMinSE

        public boolean hasMinSE()
        Determine if this SessionTimerOptions value specified a minimum session expiry interval (Min-SE).
        Returns:
        true if a Min-SE value was configured, otherwise {@link false}

      • getSessionInterval

        public int getSessionInterval()
        Get the configured session expiry interval

      • getMinSE

        public int getMinSE()
        Get the configured minimum session expiry interval, or 0 if not specified

      • isNone

        public boolean isNone()
        Return true if this value is NONE

      • isProxy

        public boolean isProxy()
        Return true if this value is PROXY

      • getMinSEOrDefault

        public int getMinSEOrDefault​(int defaultMinSE)
        Get the configured minimum session expiry interval, or a default value if not specified
        Parameters:
        defaultMinSE - the default Min-SE value in seconds, must be at least LOWEST_MIN_SE (90s)

      • getRefresherOrDefault

        public Refresher getRefresherOrDefault​(Refresher defaultRefresher)
        Get the configured refresher, or a default value if not specified
        Parameters:
        defaultRefresher - the default refresher, must not be Refresher.NONE

      • fromMessage

        public static SessionTimerOptions fromMessage​(javax.sip.message.Message message,
                                              boolean incoming)
        Utility method to extract session timer options from headers in a SIP message
        Parameters:
        message - the message to be examined
        incoming - true if the message was an incoming message from the network; otherwise false. This is necessary to determine which party the refresher parameter is referring to.
        Returns:
        a SessionTimerOptions value. This will be NONE if the message did not contain any session timer headers.

      • toBytes

        public byte[] toBytes()
               throws IOException
        Efficiently write this value to a byte array
        Throws:
        IOException

      • updateFrom422

        public SessionTimerOptions updateFrom422​(javax.sip.message.Response response)
        Update the Min-SE and Session Interval values using the Min-SE received in a 422 response. If this SessionTimerOptions's Min-SE value is unspecified, or lower that the Min-SE in the response, then return a new SessionTimerOptions with its Min-SE and Session Interval values increased to match the response's Min-SE. If the response did not contain a Min-SE header then there is no change.
        Parameters:
        response - a 422 (Session Interval Too Small) response containing a Min-SE header.
        Returns:
        a SessionTimerOptions instance

      • validateMinSE

        public static int validateMinSE​(int minSE)

      • validateSessionInterval

        public static int validateSessionInterval​(int se)

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object