examples.refer

Class Referee

java.lang.Object

examples.refer.Referee

All Implemented Interfaces:

EventListener, SipListener

public class Referee
extends Object
implements SipListener

This example shows an out-of-dialog REFER scenario: referer sends REFER to referee, with Refer-To set to Shootme referee sends INVITE to Shootme, and NOTIFYs to referer about call progress This is the referee

Author:

Jeroen van Bemmel

See Also:

http://www.ietf.org/rfc/rfc3515.txt

Field Summary

Fields

Modifier and Type	Field and Description
protected Dialog	dialog
protected SipProvider	udpProvider
protected static String	usageString

Constructor Summary

Constructors

Constructor and Description
Referee(int port)

Method Summary

Methods

Modifier and Type	Method and Description
void	createProvider()
static void	main(String[] args)
void	processDialogTerminated(DialogTerminatedEvent dialogTerminatedEvent) Process an asynchronously reported DialogTerminatedEvent.
void	processIOException(IOExceptionEvent exceptionEvent) Process an asynchronously reported IO Exception.
void	processRefer(RequestEvent requestEvent, ServerTransaction serverTransaction) Process the REFER request.
void	processRequest(RequestEvent requestEvent) Processes a Request received on a SipProvider upon which this SipListener is registered.
void	processResponse(ResponseEvent responseReceivedEvent) Processes a Response received on a SipProvider upon which this SipListener is registered.
void	processTimeout(TimeoutEvent timeoutEvent) Processes a retransmit or expiration Timeout of an underlying Transactionhandled by this SipListener.
void	processTransactionTerminated(TransactionTerminatedEvent tte) Process an asynchronously reported TransactionTerminatedEvent.
void	sendInvite(ReferToHeader to)

Methods inherited from class java.lang.Object

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

Field Detail

udpProvider

protected SipProvider udpProvider

dialog

protected Dialog dialog

usageString

protected static final String usageString

See Also:

Constant Field Values

Constructor Detail

Referee

public Referee(int port)

Method Detail

processRequest

public void processRequest(RequestEvent requestEvent)

Description copied from interface: SipListener

Processes a Request received on a SipProvider upon which this SipListener is registered.

Handling Requests:
When the application receives a RequestEvent from the SipProvider the RequestEvent may or may not belong to an existing dialog of the application. The application can be determine if the RequestEvent belongs to an existing dialog by checking the server transaction of the RequestEvent.

• If the server transaction equals null the RequestEvent does not belong to an existing dialog and the application must determine how to handle the RequestEvent. If the application decides to forward the Request statelessly no transactional support is required and it can simply pass the Request of the RequestEvent as an argument to the SipProvider.sendRequest(Request)method. However if the application determines to respond to a Request statefully it must request a new server transaction from the SipProvider.getNewServerTransaction(Request)method and use this server transaction to send the Response based on the content of the Request. If the SipProvider throws TransactionAlreadyExistsException when the application requests a new server transaction to handle a Request the current RequestEvent is a retransmission of the initial request from which the application hadn't requested a server transaction to handle it, i.e. this exception handles the race condition of an application informing the SipProvider that it will handle a Request and the receipt of a retransmission of the Request from the network to the SipProvider.
• If the server transaction does NOT equal null the application determines its action to the RequestEvent based on the content of the Request information.

User Agent Server (UAS) Behaviour:
A UAS application decides whether to accept the an invitation from a UAC. The UAS application can accept the invitation by sending a 2xx response to the UAC, a 2xx response to an INVITE transaction establishes a session. For 2xx responses, the processing is done by the UAS application, to guarantee the three way handshake of an INVITE transaction. This specification defines a utility thats enables the SipProvider to handle the 2xx processing for an INVITE transaction, see the SipStack.isRetransmissionFilterActive()method. If the invitation is not accepted, a 3xx, 4xx, 5xx or 6xx response is sent by the application, depending on the reason for the rejection. Alternatively before sending a final response, the UAS can also send provisional responses (1xx) to advise the UAC of progress in contacting the called user. A UAS that receives a CANCEL request for an INVITE, but has not yet sent a final response, would "stop ringing" and then respond to the INVITE with a specific 487 Error response.

General Proxy behaviour:
In some circumstances, a proxy application MAY forward requests using stateful transports without being transaction stateful, i.e. using the SipProvider.sendRequest(Request)method, but using TCP as a transport. For example, a proxy application MAY forward a request from one TCP connection to another transaction statelessly as long as it places enough information in the message to be able to forward the response down the same connection the request arrived on. This is the responsibility of the application and not the SipProvider. Requests forwarded between different types of transports where the proxy application takes an active role in ensuring reliable delivery on one of the transports must be forwarded using the stateful send methods on the SipProvider.

Stateful Proxies:
A stateful proxy MUST create a new server transaction for each new request received, either automatically generated by the SipProvider, if the request matches an existing dialog or by the an application call on the SipProvider if it decides to respond to the request statefully. The proxy application determines where to route the request, choosing one or more next-hop locations. An outgoing request for each next-hop location is processed by its own associated client transaction. The proxy application collects the responses from the client transactions and uses them to send responses to the server transaction. When an application receives a CANCEL request that matches a server transaction, a stateful proxy cancels any pending client transactions associated with a response context. A stateful proxy responds to the CANCEL rather than simply forwarding a response it would receive from a downstream element.

For all new Requests, including any with unknown methods, an element intending to stateful proxy the Request determines the target(s) of the request. A stateful proxy MAY process the targets in any order. A stateful proxy must have a mechanism to maintain the target set as responses are received and associate the responses to each forwarded request with the original request. For each target, the proxy forwards the request following these steps:

• Make a copy of the received request.
• Update the Request-URI.
• Update the Max-Forwards header.
• Optionally add a Record-route header.
• Optionally add additional headers.
• Postprocess routing information.
• Determine the next-hop address, port, and transport.
• Add a Via header.
• Add a Content-Length header if necessary.
• Forward the new request using the ClientTransaction.sendRequest()method.
• Process all responses recieved on the SipListener.processResponse(ResponseEvent)method.
• NOT generate 100 (Trying) responses to non-INVITE requests.

A stateful proxy MAY transition to stateless operation at any time during the processing of a request, as long as it did nothing that would prevent it from being stateless initially i.e. forking or generation of a 100 response. When performing such a transition, any state already stored is simply discarded.

Forking Requests:
A stateful proxy application MAY choose to "fork" a request, routing it to multiple destinations. Any request that is forwarded to more than one location MUST be forwarded using the stateful send methods on the SipProvider.

Stateless Proxies:
As a stateless proxy does not have any notion of a transaction, or of the response context used to describe stateful proxy behavior, requestEvent.getServerTransaction() == null; always return true . The transaction layer of the SipProvider implementation is by-passed. For all requests including any with unknown methods, an application intending to stateless proxy the request MUST:

• Validate the request.
• Preprocess routing information.
• Determine a single target(s) for the request.
• Forward the request to the target using the SipProvider.sendRequest(Request)method.
• NOT perform special processing for CANCEL requests.

Specified by:

processRequest in interface SipListener

Parameters:

requestEvent - - requestEvent fired from the SipProvider to the SipListener representing a Request received from the network.

processRefer

public void processRefer(RequestEvent requestEvent,
                ServerTransaction serverTransaction)
                  throws ParseException,
                         SipException,
                         InvalidArgumentException

Process the REFER request.

Throws:

ParseException

SipException

InvalidArgumentException

processResponse

public void processResponse(ResponseEvent responseReceivedEvent)

Description copied from interface: SipListener

Processes a Response received on a SipProvider upon which this SipListener is registered.

Handling Responses:
When the application receives a ResponseEvent from the SipProvider the ResponseEvent may or may not correlate to an existing Request of the application. The application can be determine if the ResponseEvent belongs to an existing Request by checking the client transaction of the ResponseEvent.

• If the the client transaction equals null the ResponseEvent does not belong to an existing Request and the Response is considered stray, i.e. stray response can be identitied, if responseEvent.getClientTransaction() == null;. Handling of these "stray" responses is dependent on the application i.e. a proxy will forward them statelessly using the SipProvider.sendResponse(Response)method, while a User Agent will discard them.
• If the client transaction does NOT equal null the application determines it action to the ResponseEvent based on the content of the Response information.

User Agent Client (UAC) behaviour:
After possibly receiving one or more provisional responses (1xx) to a Request, the UAC will get one or more 2xx responses or one non-2xx final response. Because of the protracted amount of time it can take to receive final responses to an INVITE, the reliability mechanisms for INVITE transactions differ from those of other requests. A UAC needs to send an ACK for every final Response it receives, however the procedure for sending the ACK depends on the type of Response. For final responses between 300 and 699, the ACK processing is done by the transaction layer i.e. handled by the implementation. For 2xx responses, the ACK processing is done by the UAC application, to guarantee the three way handshake of an INVITE transaction. This specification defines a utility thats enables the SipProvider to handle the ACK processing for an INVITE transaction, see the SipStack.isRetransmissionFilterActive()method.
A 2xx response to an INVITE establishes a session, and it also creates a dialog between the UAC that issued the INVITE and the UAS that generated the 2xx response. Therefore, when multiple 2xx responses are received from different remote User Agents, i.e. the INVITE forked, each 2xx establishes a different dialog and all these dialogs are part of the same call. If an INVITE client transaction returns a TimeoutEvent rather than a response the UAC acts as if a 408 (Request Timeout) response had been received from the UAS.

Stateful Proxies:
A proxy application that handles a response statefully must do the following processing:

• Find the appropriate response context.
• Remove the topmost Via header.
• Add the response to the response context.
• Check to determine if this response should be forwarded immediately.
• When necessary, choose the best final response from the response context. If no final response has been forwarded after every client transaction associated with the response context has been terminated, the proxy must choose and forward the "best" response from those it has seen so far.

Additionally the following processing MUST be performed on each response that is forwarded.

• Aggregate authorization header values if necessary.
• Optionally rewrite Record-Route header values.
• Forward the response using the ServerTransaction.sendResponse(Response)method.
• Generate any necessary CANCEL requests.

Stateless Proxies:
As a stateless proxy does not have any notion of transactions, or of the response context used to describe stateful proxy behavior, responseEvent.getClientTransaction == null; always return true . Response processing does not apply, the transaction layer of the SipProvider implementation is by-passed. An application intending to stateless proxy the Response MUST:

• Inspect the sent-by value in the first Via header.
• If that address matches the proxy, the proxy MUST remove that header from the response.
• Forward the resulting response to the location indicated in the next Via header using the SipProvider.sendResponse(Response)method.

Specified by:

processResponse in interface SipListener

Parameters:

responseReceivedEvent - - the responseEvent fired from the SipProvider to the SipListener representing a Response received from the network.

processTimeout

public void processTimeout(TimeoutEvent timeoutEvent)

Description copied from interface: SipListener

Processes a retransmit or expiration Timeout of an underlying Transactionhandled by this SipListener. This Event notifies the application that a retransmission or transaction Timer expired in the SipProvider's transaction state machine. The TimeoutEvent encapsulates the specific timeout type and the transaction identifier either client or server upon which the timeout occured. The type of Timeout can by determined by: timeoutType = timeoutEvent.getTimeout().getValue();

Specified by:

processTimeout in interface SipListener

Parameters:

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

sendInvite

public void sendInvite(ReferToHeader to)

createProvider

public void createProvider()

main

public static void main(String[] args)
                 throws Exception

Throws:

Exception

processIOException

public void processIOException(IOExceptionEvent exceptionEvent)

Description copied from interface: SipListener

Process an asynchronously reported IO Exception. Asynchronous IO Exceptions may occur as a result of errors during retransmission of requests. The transaction state machine requires to report IO Exceptions to the application immediately (according to RFC 3261). This method enables an implementation to propagate the asynchronous handling of IO Exceptions to the application.

Specified by:

processIOException in interface SipListener

Parameters:

exceptionEvent - -- The Exception event that is reported to the application.

processTransactionTerminated

public void processTransactionTerminated(TransactionTerminatedEvent tte)

Description copied from interface: SipListener

Process an asynchronously reported TransactionTerminatedEvent. When a transaction transitions to the Terminated state, the stack keeps no further records of the transaction. This notification can be used by applications to clean up any auxiliary data that is being maintained for the given transaction.

Specified by:

processTransactionTerminated in interface SipListener

Parameters:

tte - -- an event that indicates that the transaction has transitioned into the terminated state.

processDialogTerminated

public void processDialogTerminated(DialogTerminatedEvent dialogTerminatedEvent)

Description copied from interface: SipListener

Process an asynchronously reported DialogTerminatedEvent. When a dialog transitions to the Terminated state, the stack keeps no further records of the dialog. This notification can be used by applications to clean up any auxiliary data that is being maintained for the given dialog.

Specified by:

processDialogTerminated in interface SipListener

Parameters:

dialogTerminatedEvent - -- an event that indicates that the dialog has transitioned into the terminated state.