The HTTP Servlet API provides access to message content through a stream metaphor. Applications have access to posted data through an InputStream or a Reader and can generate content through either an OutputStream or a Writer.
SIP is more like email than HTTP with regard to message content. Messages are generally smaller and using a chunked encoding for generated content is not practical due to the SIP requirement that a Content-Length header be included in all messages. Also, SIP applications will often need access to parsed representations of message content.
For these reasons there are no stream based content accessors defined for SIP messages, and the ServletRequest methods getInputStream and getReader as well as ServletResponse methods getOutputStream and getWriter must return null.
The SipServletMessage interface defines the following setters and getters for message content (exceptions omitted for clarity):
int getContentLength();
void setContentLength(int len);
String getContentType();
void setContentType(String type);
Object getContent(); byte[] getRawContent();
void setContent(Object obj, String type);
The interface parallels how the JavaMail API defines access to message content in the
javax.mail.Part interface [JavaMail]. The getRawContent method is not present in JavaMail but is useful when writing back-to-back user agents (B2BUA) as these may wish to copy content from one message to another without incurring the overhead of parsing it (as they may not actually care what is in the body). Which type of Object is returned by getContent depends on the message’s Content-Type. It is required to return a String object for MIME type text/plain as well as for other text MIME media types for which the container does not have specific knowledge. It is encouraged that the object returned for multipart MIME content is a
javax.mail.Multipart object. For unknown content types other than text, the container must return a byte[]. Likewise, setContent is required to accept byte[] content with any MIME type, and String content when used with a text content type. When invoked with non-String objects and a text content type, containers should invoke toString() on the content Object in
order to obtain the body's character data. Again, it is recommended that implementations know how to handle javax.mail.Multipart content when used together with multipart MIME types.
6.3.1 Character Encoding
Several of the message content accessors discussed above need to be able to convert between raw eight-bit bytes and sixteen-bit Unicode characters. The character encoding attribute of
SipServletMessage specifies which mapping to use:
String getCharacterEncoding();
void setCharacterEncoding(String enc)
throws UnsupportedEncodingException;
Character encodings are identified by strings and generally follow the conventions documented in [RFC 2278]. The character encoding may affect the behavior of methods getContent and setContent. A message’s character encoding may be changed by calls to
setCharacterEncoding and setContentType. For incoming messages, the character encoding is specified by the charset parameter of the Content-Type header field, if such a parameter is present.
Note: Because of evolution of servlet spec 2.4,
SipServletResponse.setCharacterEncoding() which extends both SipServletMessage and ServletResponse now does not throw the
UnsupportedEncodingException because it inherits a more generic method from ServletResponse. This is a binary compatibile change, meaning that the compiled applications shall run on the v1.1 containers without change but it is not a source compatibile change if the application is explicitly catching the
UnsupportedEncodingException on
SipServletResponse.setCharacterEncoding().
6.4 Headers
A servlet can access the headers of a SIP message through the following methods of the SipServletMessage interface (see also [Servlet API, sections 4.3 and 5.2]):
String getHeader(String name);
ListIterator getHeaders(String name); Iterator getHeaderNames();
void setHeader(String name, String value); void addHeader(String name, String value);
H e a d e r s
The getHeader method allows access to the value of a named header field. Some header fields, for example Warning, may have multiple values in a SIP message. In this case getHeader returns the first value of the header field. The getHeaders method allow access to all values of a specified header field by returning an iterator over String objects representing those values.
The setHeader method sets a header with a given name and value. If a previous header exists, it is replaced by the new header. In the case where a set of header values exist for the given name, all values are cleared and replaced with the new value.
The addHeader method adds a header with the specified name and value to the message. If one or more headers with the given name already exists, the new value is appended to the existing list.
6.4.1 Parameterable and Address Header Fields
The methods listed above treat SIP header field values as Strings. As discussed in 5.1 The Address Interface many SIP header fields carry Parameterables (and hence Addresses) and having the ability to access such Parameterables (and hence Addresses) in a parsed form is both more convenient and allows for better performance than accessing those header field values as Strings. The following methods on the SipServletMessage interface are defined in terms of the Parameterable and Address interfaces:Parameterable getParameterableHeader(java.lang.String name);
java.util.ListIterator getParameterableHeaders(java.lang.String name) void setParameterableHeader(java.lang.String name, Parameterable param) void addParameterableHeader(java.lang.String name, Parameterable param, boolean first)
Address getAddressHeader(String name); ListIterator getAddressHeaders(String name); void setAddressHeader(String name, Address addr);
void addAddressHeader(String name, Address addr, boolean first);
If a header field has multiple Parameterable values in a message, the
getParameterableHeader method returns the first value. The getParameterableHeaders method allows access to all values of the specified header field returning an iterator over Parameterable objects. The same explanation applies to the getAddressHeader and getAddressHeaders methods if a header field has multiple Address values.
Parameterable and Address objects obtained from, or added to messages are live in the sense that modifications made to them cause the corresponding header field value of the underlying message or messages to be modified accordingly.
Parameterable and Address objects may belong to more than one SipServletMessage at a time. In this case modification of any Parameterable or Address object will result in modification of the value of the underlying header field for both messages. This sort of aliasing can result in bugs when not intended. Application writers may practice defensive programming by deep cloning the Parameterable and Address objects to avoid sharing.
6.4.2 System Headers
The term system header is used to refer to those headers that are managed by the servlet container and which servlets must not attempt to modify directly via calls to setHeader or addHeader. This includes the headers Call-ID, From, To, CSeq, Via, Record-Route, Route, Path as well as Contact when used to confer a session signaling address, that is, in messages other than REGISTER requests and responses, 200 response to OPTIONS as described by section 11.2 [RFC3261], and 3xx and 485 responses. For the contact header only the parameters and user part can be modified/added by the application as described in 5.1.3 The Contact Header Field . For the From and To headers all parts of the headers except the tags (tag parameter) can be modified as described in 5.1.2 The From and To Header Fields. There is no need for services to set the system headers directly and disallowing it makes it easier for containers to ensure correct protocol behavior. SIP servlet containers throw an IllegalArgumentException on attempts to modify system headers.
Containers are required to enforce this immutability requirement also when system headers are accessed through Address objects or through the ListIterator returned by the
getAddressHeaders method.
6.4.3 TLS Attributes
If an incoming request or response has been transmitted over a secure protocol, such as TLS, this information must be exposed via the isSecure method of the SipServletMessage interface.
Note: The isSecure method indicates whether a message was received over a secure transport. However, since secure protocols are frequently used in a hop-by-hop manner in SIP, it does not follow that the message was sent over a secure transport in all hops before reaching the container. It may well have passed over an insecure link at some point. If there is a TLS certificate associated with the message, it MUST be exposed to the servlet programmer as an array of objects of type java.security.cert.X509Certificate and accessible via a SipServletRequest or SipServletResponse attribute of javax.servlet.request.X509Certificate for requests and
T r a n s p o r t L e v e l I n f o r m a t i o n
connection is hop-by-hop this TLS certificate is not available beyond the first application in case of application composition chain as described in 17.7 Transport Information.