Package com.opencloud.sip.biggroup

Interface SubscriptionActivity

  • public interface SubscriptionActivity
    Represents the group of dialogs that are subscribed to a resource. Used by a notifier application to efficiently notify large groups of subscribers (Big Notify).

    NB: Dialogs may be associated with any number of subscription activities. Apart from the Big Notify operation, it is the application's responsibility to send the appropriate messages on each dialog during subscription initiation, refreshes and termination. For example, the application must respond to the initial SUBSCRIBE request and send the initial NOTIFY request on a new dialog, and it must send the final "Subscription-State: terminated" NOTIFY request on the dialog.

    Activity Creation

    The SubscriptionActivity for a resource is created on demand by calling BigGroupProvider.getSubscriptionActivity(String, boolean). This method takes an application-defined string key, which uniquely identifies the subscribed resource.

    Activity Ending

    The activity is explicitly ended when terminate() is called, or may be ended implicitly when all subscription dialog activities have ended, and no SLEE facilities (timer, AC naming etc) have references to the activity.

    Initial Subscription Requests

    When an initial (out of dialog) SUBSCRIBE request arrives, the request event will be fired on the ServerTransaction activity, as normal. It is the application's responsibility to create the dialog activity for the subscription. The application may then call addSubscriptionDialog() to add the dialog to the set of subscription dialogs associated with the SubscriptionActivity. The dialog will then take part in any Big Notify operations. The application should set a timer based on the subscription's expiry time.

    Subscription Refresh Requests

    Subscription refresh requests (re-SUBSCRIBEs on the subscription dialog) will be fired as normal on their respective dialog activities, as mid-dialog request events. The SubscriptionActivity does not directly take part in subscription refreshes, it is up to the application to process them. If the refresh is accepted, the application should reset the subscription's expiry timer, if it set one. If the application does not accept the refresh, it can end the dialog, or remove it from the SubscriptionActivity using removeSubscriptionDialog(net.java.slee.resource.sip.DialogActivity).

    Big Notify

    The     sendNotify() method initiates a Big Notify operation. This is where a NOTIFY is sent on all dialogs associated with a SubscriptionActivity. This is more efficient and convenient than the application generating all the NOTIFY requests itself. This creates a NotifyActivity, and the results of the notification are collected in a NotifyResultEvent.

    Subscription Expiry

    It is up to the application to determine whether a subscription has expired. When the application determines that a subscription has expired, it should remove that dialog from the SubscriptionActivity using removeSubscriptionDialog(net.java.slee.resource.sip.DialogActivity). This will ensure the dialog no longer takes part in Big Notify operations.

    Removing subscription dialogs

    The application can explicitly disassociate a subscription dialog from a SubscriptionActivity by calling removeSubscriptionDialog(net.java.slee.resource.sip.DialogActivity). This does not happen automatically when the dialog activity ends for any reason. When a subscription dialog is removed it no longer takes part in Big Notify operations.

    • Method Detail

      • addSubscriptionDialog

        void addSubscriptionDialog​(net.java.slee.resource.sip.DialogActivity dialog)
        Adds the given dialog to this SubscriptionActivity. The dialog will now take part in subsequent Big Notify operations on this activity.
        Parameters:
        dialog - a dialog activity that was created by an initial SUBSCRIBE request.

      • removeSubscriptionDialog

        void removeSubscriptionDialog​(net.java.slee.resource.sip.DialogActivity subscriberDialog)
        Removes the given dialog from this SubscriptionActivity. The dialog will no longer take part in subsequent Big Notify operations on this activity. No messages are sent on the dialog. If there are no more subscribed dialogs, and no SLEE facilities have references to this SubscriptionActivity, it will be ended automatically.
        Parameters:
        subscriberDialog - the subscription dialog representing a subscribed user agent

      • sendNotify

        NotifyActivity sendNotify​(long timeout,
                          UpdateRequest notifyUpdater)
        Generates and sends a NOTIFY out on all subscription dialogs, and gathers the responses in a single NotifyResultEvent, a.k.a. Big Notify.
        Parameters:
        timeout - the maximum time (in milliseconds) to wait for all responses, before firing the NotifyResultEvent.
        notifyUpdater - a function to update the NOTIFY request before it is sent. This must be used to populate the NOTIFY request with the application's current view of resource state.
        Returns:
        a new NotifyActivity, on which the NotifyResultEvent will be fired
        Throws:
        IllegalArgumentException - if timeout is negative or notifyUpdater is null

      • terminate

        void terminate()
        Terminates this subscription activity immediately. No messages are sent on the subscription dialogs.