This interface represents the messaging entity of a SIP stack and as
such is the interface that defines the messaging and transactional
component view of the SIP stack. It must be implemented by any object
representing a SIP stack compliant to this specification that interacts
directly with a proprietary implementation of a SIP stack.
This interface defines the methods that enable any registered
application implementing the
javax.sip.SipListener interface to:
- Register a
javax.sip.SipListener to the SipProvider. Once
the SipListener is registered with the SipProvider it will get notified
of Events representing either Request, Response, Timeout messages, Network
errors and Transaction termination.
- De-register a
javax.sip.SipListener from the SipProvider.
Once a SipListener is de-registered, it will no longer receive any Events
from that SipProvider.
- Send
javax.sip.message.Request 's statelessly.
- Send
javax.sip.message.Response 's statelessly.
- Client and Server Transaction creation methods.
- Listening Point manipulation methods.
- New CallIdHeader accessor method.
- SipStack object accessor method.
Architecture:
This specification defines a many-to-one relationship between a SipProvider
and a SipStack, a one-to-many relationship between a SipProvider and a
ListeningPoint and a many-to-one relationship between a SipProvider
and a SipListener.
Each SipProvider can be related to zero or more ListeningPoints. However,
the SipProvider can have only one ListeningPoint for each transport type.
For example, a single SipProvider can have one TCP ListeningPoint and one UDP
ListeningPoint but cannot have two UDP ListeningPoints. Applications that wish
to have multiple ListeningPoints with the same transport must use a separate
SipProvider for each such ListeningPoint.
The ListeningPoints of the SipProvider specify the local address from where request
messages will be sent.
When the application sends a request directly from a SipProvider or from an object
that the SipProvider created (Dialog or Transaction) the application might not know
in advance the transport that this request will use. The transport is often
resolved using a DNS server. In the process of sending the request, the remote
transport will be resolved. The provider will then be able to send the request
from a suitable ListeningPoint according to the resolved transport. If the resolved
transport is UDP, the Provider's UDP ListeningPoint will be used. If the resolved address is
TCP, the Providers's TCP ListeningPoint will be used.
If the application creates a SipProvider with a single ListeningPoint, let's say
UDP, it means that UDP requests will be sent from the specific UDP ListeningPoint,
and that the application does not care from where TCP requests will be sent.
This is left for the SipStack decision.
Since the transport might not be known in advance, the application might find it
difficult to specify the transport in the Via header. The
SipProvider is responsible for fixing the Via header transport if needed. If the
application set a sent-by identifier to the ListeningPoint that is different then
the sent-by parameter in the message, the sent-by parameter of the message will be
updated.
If the application created a provider with zero ListeningPoint, it must have only
a single SipProvider per SipStack.
A SipProvider has the capability to behave transaction statefully, dialog
statefully and statelessly. The transaction stateful methods are defined
on the ClientTransaction and ServerTransaction respectfully. The transaction
stateful method defined specifically for UAC and stateful proxy
applications is:
The stateful (transactional) convenience method defined specifically for
UAS and stateful proxy applications is:
The dialog stateful methods defined specifically for UAC and stateful
proxy applications are:
The stateless methods (non-transactional) defined on the SipProvider
are:
Transaction Model:
This specification supports stateful and stateless applications on a per
message basis, hence transactional semantics are not mandated for all
messages. This specification defines two types of transactions, server
transactions and client transactions. A stateless proxy does not contain a
client or server transaction, stateless proxies are effectively transparent
with respect to transactions.
Client Transaction:
A client transaction exists between a UAC and a UAS specific to Request
messages and a server transaction exists between a UAS and a UAC specific
to Response messages. A transaction either server or client identifies
messages sent between two SIP entities. The purpose of a client transaction
is to identify a Request sent by an application that will reliably deliver
the Request to a server transaction on
the responding SIP entity. The purpose of a server transaction is to
identify a Response sent by an application that will reliably deliver the
Response to the request initiator.
Server Transaction:
A new server transaction is required for each response that an application
decides to respond to statefully, as follows:
- Dialog-Creating Requests: A server transaction is not automatically
generated by a SipProvider implementation upon receipt of every
Dialog-Creating Request i.e. INVITE. Instead the
server transaction is set to
null in the RequestEvent and
the RequestEvent also containing the Request is passed to the application.
It is then the responsibility of the application to decide to handle the
Dialog-Creating Request statefully or statelessly, using the appropriate
send methods on the SipProvider and the ServerTransaction. If a
retransmission of the initial Request request is recieved by the SipProvider
the following procedures should be adhered to:
- Determine if an exisiting transaction is already handling this Request.
- If a transaction exists do not pass the Request to the application via a
RequestEvent.
- If a transaction doesn't exist pass the retransmitted request to the
application as a RequestEvent.
- Non-Dialog-Creating Requests - When the SipProvider receives a
Non-Dialog-Creating Request upon which this application has already
responded to the Dialog-Creating Request of the same dialogue the server
transaction is automatically placed to the RequestEvent and passed up to
the application upon which it can respond. Note that the server transaction
may be null in a stateful implementation if the incoming request does not
match any dialog but must be part of one. That is for requests that must
have state but for which the stack cannot find that state, the application
can still handle these requests statelessly. The application cannot create
a new server transaction for such requests.
Sending Requests:
The client side of the transport layer is responsible for sending the
request. The application passes the the Request to the ClientTransaction
Dialog or the SipProvider that will send the Request over one of the SipProvider's
ListeningPoints. The SipProvider will choose a ListeningPoint
that has the same transport as the destination. For example, a Request that is going
to be sent over TCP will use a TCP ListeningPoint. See section 18.1.1 of
RFC3261.
Sending Responses:
The server side of the transport layer is responsible for sending the
responses. The application passes the Response to the ServerTransaction
or the SipProvider that will send the Response over one of its ListeningPoints.
RFC3261. The response
must be sent from the same ListeningPoint on which the request was received.
Receiving Requests:
A SipProvider should be prepared to receive requests on any IP address,
port and transport encapsulated in one of its ListeningPoints.
When the SipProvider receives a request over any transport, it
must examine the value of the "sent-by" parameter in the top Via
header. If the host portion of the "sent-by" parameter contains a
domain name, or if it contains an IP address that differs
from the packet source address, the server must add a "received"
parameter to that Via header field value. This parameter must
contain the source address from which the packet was received. This
is to assist the SipProvider in sending the response, since it must
be sent to the source IP address from which the request came.
Next, the SipProvider attempts to match the request to a server
transaction. If there are any server transactions in existence, the server
transport uses the matching procedures of Chapter 17 of
RFC3261 to attempt to
match the response to an existing transaction. If a matching server
transaction is found, the request is passed to that transaction, encapsulated
into a RequestEvent and fired to the application for processing. If no match
is found, the request is passed to the application, which may decide to
construct a new server transaction for that request.
Receiving Responses
Responses are first processed by the transport layer and then passed
up to the transaction layer. The transaction layer performs its
processing and then passes the response up to the application.
When a response is received, the SipProvider examines the top
Via header. If the value of the "sent-by" parameter in that header field
value does not correspond to a value that the client transport is configured
to insert into requests, the response MUST be silently discarded. If there
are any client transactions in existence, the client transport uses the
matching procedures of Chapter 17 of
RFC3261 to attempt to
match the response to an existing transaction. If there is a
match, the response must be passed to that transaction, encapsulated into a
ResponseEvent and fired to the application. Otherwise, the response is stray
and must be passed to the application to determine its outcome i.e. a proxy
will forward them, while a User Agent will discard.
See Also: SipListener
See Also: SipStack
author:
BEA Systems, NIST
version:
1.2 |