Tutorial:Working as Proxy II
From Wesip
From Wesip
A proxy servlet can generate any number of 1xx responses of its own before proxying transaction completes. This can be done following the standard UAS procedure of request.createResponse(1xx).send(). Final responses are not tipically generated by the servlet itself. Yet allowed, is not a common behaviour and as such will not be covered here. Instead we will focus on the process of responses that come from the downstream.
The first thing to keep in mind is that proxy servlets that have been configured to work in non supervised mode will never receive a response message for processing. In these cases the container itself will chose the "best response" and forward it to the upstream as required.
But typically we'll want to process responses to our proxied requests since they can contain valuable information for our application. The responses can be divided in three types with different processing rules
1xx Responses
Information responses other than 100 are passed to the application which may modify them before letting the container forward them upstream.
2xx Responses
Upon reception of a success response the container cancels all outstanding proxy branches and passes the response to the application which can modify their contents before letting the it be forwarded upstream.
Retransmissions of 2xx responses to INVITEs are passed to the application as well since per protocol those 2xx retransmissions are supposed to bypass the transaction layer. For sake of integrity the application must ensure that the process of a 2xx retransmission will modify the response exactly in the same way it did with the original 2xx.
3xx-6xx Responses
Error responses are automatically ACK'ed by the container and passed to the application only when they are the best final response of the proxying transaction. In case of 6xx errors all pending branches are cancelled inmediately as well. The procedures to identify a response as a best response are defined in the RFC 3261, Section 16.7.
When the application processes a 3xx,4xx or 5xx final response it can choose to dynamically add new branches to the proxy transaction by invoking proxy.proxyTo() with the list of new URIs. This call will add new branches to the transaction and process them just like if they were had been there since the initial call to proxyTo. When process of the new branches is completed a new best response will be chosen among all the branches responses and passed to the application again. If the application doesn't proxy again (or is not allowed to do so because the new best response happens to be of the 2xx or 6xx types) this last best response is then forwarded upstream.
Subsequent Requests
When an application has proxied a request with RecordRoute enabled it will receive subsequent requests, that is, requests inside the established dialog like ACK, BYE or reINVITE. The servlet can modify these request before they are sent downstream but shouldn't try to explicitly proxy them since it is up to the container to forward subsequent requests downstream. The developer can check wether a request is subsequent by calling to its isInitial method.