org.cafesip.sipunit
Class PresenceSubscriber

java.lang.Object
  org.cafesip.sipunit.EventSubscriber
      org.cafesip.sipunit.PresenceSubscriber

All Implemented Interfaces:

MessageListener, RequestListener, SipActionObject

public class PresenceSubscriber
extends EventSubscriber

The PresenceSubscriber class represents a buddy from a SipPhone buddy list or a single-shot presence fetch performed by a SipPhone. This object is used by a test program to proceed through the SUBSCRIBE-NOTIFY sequence(s) and to find out details at any given time about the subscription such as the subscription state, amount of time left on the subscription if still active, termination reason if terminated, errors encountered during received SUBSCRIBE response and incoming NOTIFY message validation, details of any received responses and requests if needed by the test program, and the current or last known presence status/information (tuples/devices, notes, etc.) for this subscription.

Please read the SipUnit User Guide, Event Subscription section for the NOTIFY-receiving side (at least the operation overview part) for information on how to use the methods of this class and its superclass.

As in the case of other objects like SipPhone, SipCall, etc., operation-invoking methods of this class return an object or true if successful. In case of an error or caller-specified timeout, a null object or a false is returned. The getErrorMessage(), getReturnCode() and getException() methods may be used for further diagnostics. See SipPhone or SipActionObject javadoc for more details on using these methods.

Constructor Summary

PresenceSubscriber(java.lang.String uri, SipPhone parent)
A constructor for this class.

Method Summary

javax.sip.message.Request	createSubscribeMessage(int duration, java.lang.String eventId) This method is the same as EventSubscriber.createSubscribeMessage() except there's no need for the caller to supply the eventType parameter.
java.util.HashMap<java.lang.String,PresenceDeviceInfo>	getPresenceDevices() Gets the list of known devices for this Subscription (buddy, watchee).
java.util.ArrayList<java.lang.Object>	getPresenceExtensions() Gets the list of extensions pertaining to this Subscription as received in the last NOTIFY message (at the top 'presence' element level).
java.util.ArrayList<PresenceNote>	getPresenceNotes() Gets the list of notes pertaining to this Subscription as received in the last NOTIFY message (at the top 'presence' element level).
boolean	refreshBuddy(int duration, long timeout) This method is the same as refreshBuddy(duration, eventId, timeout) except that the eventId remains unchanged from whatever it already was.
boolean	refreshBuddy(int duration, java.lang.String eventId, long timeout) This method initiates a SUBSCRIBE/NOTIFY sequence for the purpose of updating the presence information for this buddy.
boolean	refreshBuddy(long timeout) This method is the same as refreshBuddy(duration, eventId, timeout) except that the eventId remains unchanged from whatever it already was and the SUBSCRIBE duration sent will be however much time is left on the current subscription.
boolean	refreshBuddy(javax.sip.message.Request req, long timeout) This method is the same as refreshBuddy(duration, eventId, timeout) except that instead of creating the SUBSCRIBE request from parameters passed in, the given request message parameter is used for sending out the SUBSCRIBE message.
boolean	refreshBuddy(java.lang.String eventId, long timeout) This method is the same as refreshBuddy(duration, eventId, timeout) except that the SUBSCRIBE duration sent will be however much time is left on the current subscription.
boolean	removeBuddy(long timeout) This method is the same as removeBuddy(eventId, timeout) except that no event "id" parameter will be included in the unSUBSCRIBE message.
boolean	removeBuddy(javax.sip.message.Request req, long timeout) This method is the same as removeBuddy(eventId, timeout) except that instead of creating the SUBSCRIBE request from parameters passed in, the given request message parameter is used for sending out the SUBSCRIBE message if the subscription is active.
boolean	removeBuddy(java.lang.String eventId, long timeout) This method removes this buddy from the SipPhone buddy list and initiates a SUBSCRIBE/NOTIFY sequence to terminate the subscription unless the subscription is already terminated.

Methods inherited from class org.cafesip.sipunit.EventSubscriber

clearEventErrors, createSubscribeMessage, format, getAllReceivedRequests, getAllReceivedResponses, getCurrentResponse, getDialog, getDialogId, getErrorMessage, getEventErrors, getException, getLastReceivedRequest, getLastReceivedResponse, getLastSentRequest, getReturnCode, getTargetUri, getTerminationReason, getTimeLeft, isRemovalComplete, isSubscriptionActive, isSubscriptionPending, isSubscriptionTerminated, processEvent, processNotify, processResponse, replyToNotify, waitNotify

Methods inherited from class java.lang.Object

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

Constructor Detail

PresenceSubscriber

public PresenceSubscriber(java.lang.String uri,
                          SipPhone parent)
                   throws java.text.ParseException

A constructor for this class. Used internally by SipUnit. Test programs should call the SipPhone.addBuddy() or fetchPresenceInfo() method to create a subscription.

Parameters:

uri -

parent -

Throws:

java.text.ParseException

Method Detail

createSubscribeMessage

public javax.sip.message.Request createSubscribeMessage(int duration,
                                                        java.lang.String eventId)

This method is the same as EventSubscriber.createSubscribeMessage() except there's no need for the caller to supply the eventType parameter.

Parameters:

duration - the duration in seconds to put in the SUBSCRIBE message.

eventId - the event "id" to use in the SUBSCRIBE message, or null for no event "id" parameter. Whatever is indicated here will be used subsequently (for error checking SUBSCRIBE responses and NOTIFYs from the server as well as for sending subsequent SUBSCRIBEs) unless changed by the caller later on another SipPhone buddy method call (refreshBuddy(), removeBuddy(), fetch, etc.).

Returns:

a SUBSCRIBE request

getPresenceDevices

public java.util.HashMap<java.lang.String,PresenceDeviceInfo> getPresenceDevices()

Gets the list of known devices for this Subscription (buddy, watchee). This list represents the list of 'tuple's received in the last NOTIFY message.

Returns:

A HashMap containing zero or more PresenceDeviceInfo objects, indexed/keyed by the unique IDs received for each in the NOTIFY messages (tuple elements).

getPresenceNotes

public java.util.ArrayList<PresenceNote> getPresenceNotes()

Gets the list of notes pertaining to this Subscription as received in the last NOTIFY message (at the top 'presence' element level).

Returns:

An ArrayList containing zero or more PresenceNote objects.

getPresenceExtensions

public java.util.ArrayList<java.lang.Object> getPresenceExtensions()

Gets the list of extensions pertaining to this Subscription as received in the last NOTIFY message (at the top 'presence' element level).

Returns:

An ArrayList containing zero or more Object.

refreshBuddy

public boolean refreshBuddy(int duration,
                            java.lang.String eventId,
                            long timeout)

This method initiates a SUBSCRIBE/NOTIFY sequence for the purpose of updating the presence information for this buddy. This method creates a SUBSCRIBE request message based on the parameters passed in, sends out the request, and waits for a response to be received. It saves the received response and checks for a "proceedable" (positive) status code value. Positive response status codes include any of the following: provisional (status / 100 == 1), UNAUTHORIZED, PROXY_AUTHENTICATION_REQUIRED, OK and ACCEPTED. Any other status code, or a response timeout or any other error, is considered fatal to this refresh operation.

This method blocks until one of the above outcomes is reached.

If this method returns true, it means a positive response was received. You can find out about the response by calling this object's getReturnCode() and/or getCurrentResponse() or getLastReceivedResponse() methods. Your next step will be to call the processResponse() method to proceed with the refresh sequence. See the processResponse() javadoc for more details.

If this method returns false, it means this refresh operation has failed. Call the usual SipUnit failed-operation methods to find out what happened (ie, getErrorMessage(), getReturnCode(), and/or getException() methods). The getReturnCode() method will tell you the response status code that was received from the network (unless it is an internal SipUnit error code, see the SipSession javadoc for more on that).

Parameters:

duration - the duration in seconds to put in the SUBSCRIBE message and reset the subscription time left to. If it is 0, this is an unsubscribe (note, the buddy stays in the SipPhone's buddy list even though the subscription won't be active).

eventId - the event "id" to use in the SUBSCRIBE message, or null for no event "id" parameter. Whatever is indicated here will be used subsequently (for error checking SUBSCRIBE responses and NOTIFYs from the server as well as for sending subsequent SUBSCRIBEs) unless changed by the caller later on another buddy method call.

timeout - The maximum amount of time to wait for a SUBSCRIBE response, in milliseconds. Use a value of 0 to wait indefinitely.

Returns:

true if the refresh operation is successful so far, false otherwise. False just means this SUBSCRIBE sequence failed - this buddy remains in the SipPhone's buddy list. See more details above.

refreshBuddy

public boolean refreshBuddy(java.lang.String eventId,
                            long timeout)

This method is the same as refreshBuddy(duration, eventId, timeout) except that the SUBSCRIBE duration sent will be however much time is left on the current subscription. If time left on the subscription <= 0, unsubscribe occurs (note, the buddy stays in the list).

refreshBuddy

public boolean refreshBuddy(int duration,
                            long timeout)

This method is the same as refreshBuddy(duration, eventId, timeout) except that the eventId remains unchanged from whatever it already was.

refreshBuddy

public boolean refreshBuddy(long timeout)

This method is the same as refreshBuddy(duration, eventId, timeout) except that the eventId remains unchanged from whatever it already was and the SUBSCRIBE duration sent will be however much time is left on the current subscription. If time left on the subscription <= 0, unsubscribe occurs (note, the buddy stays in the list).

refreshBuddy

public boolean refreshBuddy(javax.sip.message.Request req,
                            long timeout)

This method is the same as refreshBuddy(duration, eventId, timeout) except that instead of creating the SUBSCRIBE request from parameters passed in, the given request message parameter is used for sending out the SUBSCRIBE message.

The Request parameter passed into this method should come from calling createSubscribeMessage() - see that javadoc. The subscription duration is reset to the passed in Request's expiry value. If it is 0, this is an unsubscribe. Note, the buddy stays in the buddy list even though the subscription won't be active. The event "id" in the given request will be used subsequently (for error checking SUBSCRIBE responses and NOTIFYs from the server as well as for sending subsequent SUBSCRIBEs).

removeBuddy

public boolean removeBuddy(java.lang.String eventId,
                           long timeout)

This method removes this buddy from the SipPhone buddy list and initiates a SUBSCRIBE/NOTIFY sequence to terminate the subscription unless the subscription is already terminated. Regardless, this buddy is taken out of the active buddy list and put into the retired buddy list (which is a list of PresenceSubscriber objects of buddies that have been removed from the buddy list and PresenceSubscriber objects for individual fetch operations that have been done). A retired buddy's PresenceSubscriber object continues to be valid and accessible via SipPhone.getBuddyInfo().

If the subscription is active when this method is called, this method creates a SUBSCRIBE request message based on the parameters passed in, sends out the request, and waits for a response to be received. It saves the received response and checks for a "proceedable" (positive) status code value. Positive response status codes include any of the following: provisional (status / 100 == 1), UNAUTHORIZED, PROXY_AUTHENTICATION_REQUIRED, OK and ACCEPTED. Any other status code, or a response timeout or any other error, is considered fatal to the unsubscribe operation.

This method blocks until one of the above outcomes is reached.

If this method returns true, it means a positive response was received or the unsubscribe sequence was not required. In order for you to know which is the case (and whether or not to proceed forward with the SUBSCRIBE/NOTIFY sequence processing), call isRemovalComplete(). It will tell you if an unsubscribe sequence was initiated or not. If not, you are done. Otherwise you can find out about the positive response by calling this object's getReturnCode() and/or getCurrentResponse() or getLastReceivedResponse() methods. Your next step will be to call the processResponse() method to proceed with the unsubscribe sequence. See the processResponse() javadoc for more details.

If this method returns false, it means the unsubscribe operation was required and it failed. Call the usual SipUnit failed-operation methods to find out what happened (ie, getErrorMessage(), getReturnCode(), and/or getException() methods). The getReturnCode() method will tell you the response status code that was received from the network (unless it is an internal SipUnit error code, see the SipSession javadoc for more on that).

Parameters:

eventId - the event "id" to use in the SUBSCRIBE message, or null for no event "id" parameter. Whatever is indicated here will be used subsequently, for error checking the unSUBSCRIBE response and NOTIFY from the server.

timeout - The maximum amount of time to wait for a SUBSCRIBE response, in milliseconds. Use a value of 0 to wait indefinitely.

Returns:

true if the unsubscribe operation is successful so far or wasn't needed, false otherwise. See more details above. In either case, the buddy is removed from the buddy list.

removeBuddy

public boolean removeBuddy(long timeout)

This method is the same as removeBuddy(eventId, timeout) except that no event "id" parameter will be included in the unSUBSCRIBE message. When error checking the SUBSCRIBE response and NOTIFY from the server, no event "id" parameter will be expected.

removeBuddy

public boolean removeBuddy(javax.sip.message.Request req,
                           long timeout)

This method is the same as removeBuddy(eventId, timeout) except that instead of creating the SUBSCRIBE request from parameters passed in, the given request message parameter is used for sending out the SUBSCRIBE message if the subscription is active.

The Request parameter passed into this method should come from calling createSubscribeMessage() - see that javadoc. The event "id" in the given request will be used subsequently for error checking the SUBSCRIBE response and NOTIFY request from the server.