org.cafesip.sipunit
Class ReferSubscriber

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

All Implemented Interfaces:

MessageListener, RequestListener, SipActionObject

public class ReferSubscriber
extends EventSubscriber

The ReferSubscriber class represents the implicit subscription created by sending a REFER request via the SipPhone.refer() method. This object is used by a test program to proceed through the initial REFER-NOTIFY and any subsequent 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 REFER/SUBSCRIBE responses and incoming NOTIFY message validation, and details of any received responses and requests if needed by the test program.

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

ReferSubscriber(java.lang.String refereeUri, javax.sip.address.SipURI referToUri, SipPhone parent)
A constructor for this class.

ReferSubscriber(java.lang.String refereeUri, javax.sip.address.SipURI referToUri, SipPhone parent, javax.sip.Dialog dialog)
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.
void	dispose() Removes this object from the SipPhone referrer list.
javax.sip.address.SipURI	getReferToUri() Get the referTo URI for this subscription.
boolean	refresh(int duration, long timeout) This method is the same as refresh(duration, eventId, timeout) except that the eventId remains unchanged from whatever it already was.
boolean	refresh(int duration, java.lang.String eventId, long timeout) This method initiates a SUBSCRIBE/NOTIFY sequence for the purpose of refreshing this subscription.
boolean	refresh(long timeout) This method is the same as refresh(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	refresh(javax.sip.message.Request req, long timeout) This method is the same as refresh(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	refresh(java.lang.String eventId, long timeout) This method is the same as refresh(duration, eventId, timeout) except that the SUBSCRIBE duration sent will be however much time is left on the current subscription.
boolean	unsubscribe(long timeout) This method is the same as unsubscribe(eventId, timeout) except that no event "id" parameter will be included in the unSUBSCRIBE message.
boolean	unsubscribe(javax.sip.message.Request req, long timeout) This method is the same as unsubscribe(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	unsubscribe(java.lang.String eventId, long timeout) This method 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

ReferSubscriber

public ReferSubscriber(java.lang.String refereeUri,
                       javax.sip.address.SipURI referToUri,
                       SipPhone parent)
                throws java.text.ParseException

A constructor for this class. Used internally by SipUnit. Test programs should call one of the SipPhone.refer() methods to create a refer subscription.

Throws:

java.text.ParseException

ReferSubscriber

public ReferSubscriber(java.lang.String refereeUri,
                       javax.sip.address.SipURI referToUri,
                       SipPhone parent,
                       javax.sip.Dialog dialog)
                throws java.text.ParseException

A constructor for this class. Used internally by SipUnit. Test programs should call one of the SipPhone.refer() methods to create a refer subscription.

Throws:

java.text.ParseException

Method Detail

dispose

public void dispose()

Removes this object from the SipPhone referrer list. No check is done. You should unsubscribe() before calling this method.

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 when calling refresh() or unsubscribe().

Returns:

a SUBSCRIBE request

refresh

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

This method initiates a SUBSCRIBE/NOTIFY sequence for the purpose of refreshing this subscription. This method creates a SUBSCRIBE request message based on the parameters passed in, sends out the request, and waits for a first 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.

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 refresh method call or on calling unsubscribe().

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. See details above.

refresh

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

This method is the same as refresh(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.

refresh

public boolean refresh(int duration,
                       long timeout)

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

refresh

public boolean refresh(long timeout)

This method is the same as refresh(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.

refresh

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

This method is the same as refresh(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. 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).

unsubscribe

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

This method initiates a SUBSCRIBE/NOTIFY sequence to terminate the subscription unless the subscription is already terminated.

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 first 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.

unsubscribe

public boolean unsubscribe(long timeout)

This method is the same as unsubscribe(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.

unsubscribe

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

This method is the same as unsubscribe(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.

getReferToUri

public javax.sip.address.SipURI getReferToUri()

Get the referTo URI for this subscription.

Returns:

Returns the referToUri.