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
{@link SipProvider#sendRequest(Request)} method. However if the
application determines to respond to a Request statefully it must request
a new server transaction from the
{@link 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 {@link 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 {@link 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
{@link ClientTransaction#sendRequest()} method.
- Process all responses recieved on the
{@link 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
{@link SipProvider#sendRequest(Request)} method.
- NOT perform special processing for CANCEL requests.
