net.java.sip.communicator.impl.protocol.sip
Class EventPackageSubscriber

java.lang.Object
  net.java.sip.communicator.impl.protocol.sip.MethodProcessorAdapter
      net.java.sip.communicator.impl.protocol.sip.EventPackageSupport
          net.java.sip.communicator.impl.protocol.sip.EventPackageSubscriber

All Implemented Interfaces:

MethodProcessor

public class EventPackageSubscriber
extends EventPackageSupport

Implements the subscriber part of RFC 3265 "Session Initiation Protocol (SIP)-Specific Event Notification" and thus eases the creation of event package-specific implementations.

Author:

Lubomir Marinov, Benoit Pradelle, Emil Ivov

Nested Class Summary

static class

EventPackageSubscriber.Subscription Represents a general event package subscription in the sense of RFC 3265 "Session Initiation Protocol (SIP)-Specific Event Notification" from the point of view of the subscriber and its signaling characteristics such as Request URI, id tag value of its Event header, the Dialog which has been created by the associated SUBSCRIBE request or through which it was sent.

Field Summary

Fields inherited from class net.java.sip.communicator.impl.protocol.sip.EventPackageSupport

contentSubType, eventPackage, protocolProvider, subscriptionDuration, timer

Constructor Summary

EventPackageSubscriber(ProtocolProviderServiceSipImpl protocolProvider, String eventPackage, int subscriptionDuration, String contentSubType, TimerScheduler timer, int refreshMargin)
Initializes a new EventPackageSubscriber instance which is to provide subscriber support according to RFC 3265 to a specific SIP ProtocolProviderService implementation for a specific event package.

Method Summary

protected EventPackageSubscriber.Subscription	getSubscription(javax.sip.address.Address toAddress, String eventId) Gets the Subscription from the list of subscriptions managed by this instance which is associated with a specific subscription Address/Request URI and has a specific id tag in its Event header.
protected EventPackageSubscriber.Subscription	getSubscription(String callId) Gets the Subscription from the list of subscriptions managed by this instance which is associated with a specific CallId.
void	poll(EventPackageSubscriber.Subscription subscription) Adds a specific Subscription to the list of subscriptions managed by this instance only if another Subscription with the same subscription Address/Request URI and id tag of its associated Event header does not exist in the list.
boolean	processRequest(javax.sip.RequestEvent requestEvent) Implements MethodProcessor.processRequest(RequestEvent).
boolean	processResponse(javax.sip.ResponseEvent responseEvent) Implements MethodProcessor.processResponse(ResponseEvent).
boolean	processTimeout(javax.sip.TimeoutEvent timeoutEvent) If we got timeout we there is a problem with the connection, lets inform the provider.
void	subscribe(EventPackageSubscriber.Subscription subscription) Creates and sends a SUBSCRIBE request to the subscription Address/Request URI of a specific Subscription in order to request receiving event notifications and adds the specified Subscription to the list of subscriptions managed by this instance.
void	unsubscribe(javax.sip.address.Address toAddress, boolean assertSubscribed) Creates and sends a SUBSCRIBE request to a specific subscription Address/Request URI if it matches a Subscription with an id tag of its Event header of null in the list of subscriptions managed by this instance with an Expires header value of zero in order to terminate receiving event notifications and removes the specified Subscription from the list of subscriptions managed by this instance.
void	unsubscribe(javax.sip.address.Address toAddress, String eventId, boolean assertSubscribed) Creates and sends a SUBSCRIBE request to a specific subscription Address/Request URI if it matches a Subscription with an id tag of its Event header of a specific value in the list of subscriptions managed by this instance with an Expires header value of zero in order to terminate receiving event notifications and removes the specified Subscription from the list of subscriptions managed by this instance.

Methods inherited from class net.java.sip.communicator.impl.protocol.sip.EventPackageSupport

addSubscription, getEventPackage, getOrCreateServerTransaction, getSubscriptions, processAuthenticationChallenge, processAuthenticationChallenge, removeSubscription, removeSubscription, removeSubscription, sendNotImplementedResponse

Methods inherited from class net.java.sip.communicator.impl.protocol.sip.MethodProcessorAdapter

processDialogTerminated, processIOException, processTransactionTerminated

Methods inherited from class java.lang.Object

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

Constructor Detail

EventPackageSubscriber

public EventPackageSubscriber(ProtocolProviderServiceSipImpl protocolProvider,
                              String eventPackage,
                              int subscriptionDuration,
                              String contentSubType,
                              TimerScheduler timer,
                              int refreshMargin)

Initializes a new EventPackageSubscriber instance which is to provide subscriber support according to RFC 3265 to a specific SIP ProtocolProviderService implementation for a specific event package.

Parameters:

protocolProvider - the SIP ProtocolProviderService implementation for which the new instance is to provide subscriber support for a specific event package

eventPackage - the name of the event package the new instance is to implement and carry in the Event and Allow-Events headers

subscriptionDuration - the duration of each subscription to be managed by the new instance and to be carried in the Expires headers

contentSubType - the sub-type of the content type of the NOTIFY bodies to be announced, expected and supported by the subscriptions to be managed by the new instance

timer - the Timer support which is to refresh the subscriptions to be managed by the new instance

refreshMargin - the number of seconds before a subscription to be managed by the new instance expires that the new instance should attempt to refresh it

Method Detail

getSubscription

protected EventPackageSubscriber.Subscription getSubscription(javax.sip.address.Address toAddress,
                                                              String eventId)

Gets the Subscription from the list of subscriptions managed by this instance which is associated with a specific subscription Address/Request URI and has a specific id tag in its Event header.

Overrides:

getSubscription in class EventPackageSupport

Parameters:

toAddress - the subscription Address/Request URI of the Subscription to be retrieved

eventId - the id tag placed in the Event header of the Subscription to be retrieved if there is one or null if the Subscription should have no id tag in its Event header

Returns:

an existing Subscription from the list of subscriptions managed by this instance with the specified subscription Address/Request URI and the specified id tag in its Event header; null if no such Subscription exists in the list of subscriptions managed by this instance

getSubscription

protected EventPackageSubscriber.Subscription getSubscription(String callId)

Gets the Subscription from the list of subscriptions managed by this instance which is associated with a specific CallId.

Overrides:

getSubscription in class EventPackageSupport

Parameters:

callId - the CallId associated with the Subscription to be retrieved

Returns:

an existing Subscription from the list of subscriptions managed by this instance which is associated with the specified CallId; null if no such Subscription exists in the list of subscriptions managed by this instance

poll

public void poll(EventPackageSubscriber.Subscription subscription)
          throws OperationFailedException

Adds a specific Subscription to the list of subscriptions managed by this instance only if another Subscription with the same subscription Address/Request URI and id tag of its associated Event header does not exist in the list.

Parameters:

subscription - the new Subscription to be added to the list of subscriptions managed by this instance if there is no other Subscription in the list which has the same subscription Address/Request URI and id tag of its Event header

Throws:

OperationFailedException - if we fail constructing or sending the subscription request

processRequest

public boolean processRequest(javax.sip.RequestEvent requestEvent)

Implements MethodProcessor.processRequest(RequestEvent). Handles only NOTIFY requests because they are the only requests concerning event package subscribers and if the processing of a given request requires event package-specific handling, delivers the request to the matching Subscription instance. Examples of such event package-specific handling include handling the termination of an existing Subscription and processing the bodies of the NOTIFY requests for active Subscriptions.

Specified by:

processRequest in interface MethodProcessor

Overrides:

processRequest in class MethodProcessorAdapter

Parameters:

requestEvent - a RequestEvent specifying the SIP Request to be processed

Returns:

true if the SIP Request specified by requestEvent was processed; otherwise, false

processResponse

public boolean processResponse(javax.sip.ResponseEvent responseEvent)

Implements MethodProcessor.processResponse(ResponseEvent). Handles only responses to SUBSCRIBE requests because they are the only requests concerning event package subscribers (and the only requests sent by them, for that matter) and if the processing of a given response requires event package-specific handling, delivers the response to the matching Subscription instance. Examples of such event package-specific handling include letting the respective Subscription handle the success or failure in the establishment of a subscription.

Specified by:

processResponse in interface MethodProcessor

Overrides:

processResponse in class MethodProcessorAdapter

Parameters:

responseEvent - a ResponseEvent specifying the SIP Response to be processed

Returns:

true if the SIP Response specified by responseEvent was processed; otherwise, false

processTimeout

public boolean processTimeout(javax.sip.TimeoutEvent timeoutEvent)

If we got timeout we there is a problem with the connection, lets inform the provider. Implements MethodProcessor#processTimeout(TimeoutEvent).

Specified by:

processTimeout in interface MethodProcessor

Overrides:

processTimeout in class MethodProcessorAdapter

Parameters:

timeoutEvent - the timeoutEvent received indicating either the message retransmit or transaction timed out

Returns:

true if the specified event has been handled by this processor and shouldn't be offered to other processors registered for the same method; false, otherwise

subscribe

public void subscribe(EventPackageSubscriber.Subscription subscription)
               throws OperationFailedException

Creates and sends a SUBSCRIBE request to the subscription Address/Request URI of a specific Subscription in order to request receiving event notifications and adds the specified Subscription to the list of subscriptions managed by this instance. The added Subscription may later receive notifications to process the Requests and/or Responses which constitute the signaling session associated with it. If the attempt to create and send the SUBSCRIBE request fails, the specified Subscription is not added to the list of subscriptions managed by this instance.

Parameters:

subscription - a Subscription which specifies the properties of the SUBSCRIBE request to be created and sent, to be added to the list of subscriptions managed by this instance

Throws:

OperationFailedException - if we fail constructing or sending the subscription request.

unsubscribe

public void unsubscribe(javax.sip.address.Address toAddress,
                        boolean assertSubscribed)
                 throws IllegalArgumentException,
                        OperationFailedException

Creates and sends a SUBSCRIBE request to a specific subscription Address/Request URI if it matches a Subscription with an id tag of its Event header of null in the list of subscriptions managed by this instance with an Expires header value of zero in order to terminate receiving event notifications and removes the specified Subscription from the list of subscriptions managed by this instance. The removed Subscription may receive notifications to process the Requests and/or Responses which constitute the signaling session associated with it. If the attempt to create the SUBSCRIBE request fails, the associated Subscription is not removed from the list of subscriptions managed by this instance. If the specified Address does not identify an existing Subscription in the list of subscriptions managed by this instance, an assertion may optionally be performed or no reaction can be taken.

Parameters:

toAddress - a subscription Address/Request URI which identifies a Subscription to be removed from the list of subscriptions managed by this instance

assertSubscribed - true to assert if the specified subscription Address/Request URI does not identify an existing Subscription in the list of subscriptions managed by this instance; false to not assert if the mentioned condition is met

Throws:

IllegalArgumentException - if assertSubscribed is true and toAddress does not identify an existing Subscription in the list of subscriptions managed by this instance

OperationFailedException - if we fail constructing or sending the unSUBSCRIBE request.

unsubscribe

public void unsubscribe(javax.sip.address.Address toAddress,
                        String eventId,
                        boolean assertSubscribed)
                 throws IllegalArgumentException,
                        OperationFailedException

Creates and sends a SUBSCRIBE request to a specific subscription Address/Request URI if it matches a Subscription with an id tag of its Event header of a specific value in the list of subscriptions managed by this instance with an Expires header value of zero in order to terminate receiving event notifications and removes the specified Subscription from the list of subscriptions managed by this instance. The removed Subscription may receive notifications to process the Requests and/or Responses which constitute the signaling session associated with it. If the attempt to create the SUBSCRIBE request fails, the associated Subscription is not removed from the list of subscriptions managed by this instance. If the specified Address does not identify an existing Subscription in the list of subscriptions managed by this instance, an assertion may optionally be performed or no reaction can be taken.

Parameters:

toAddress - a subscription Address/Request URI which identifies a Subscription to be removed from the list of subscriptions managed by this instance

eventId - the id tag placed in the Event header of the Subscription to be matched if there is one or null if the Subscription should have no id tag in its Event header

assertSubscribed - true to assert if the specified subscription Address/Request URI does not identify an existing Subscription in the list of subscriptions managed by this instance; false to not assert if the mentioned condition is met

Throws:

IllegalArgumentException - if assertSubscribed is true and toAddress and eventId do not identify an existing Subscription in the list of subscriptions managed by this instance

OperationFailedException - if we fail constructing or sending the unSUBSCRIBE request.