NIST-SIP: The Reference Implementation for JAIN-SIP 1.2

gov.nist.javax.sip.message
Class SIPRequest

java.lang.Object
  extended by gov.nist.core.GenericObject
      extended by gov.nist.javax.sip.message.MessageObject
          extended by gov.nist.javax.sip.message.SIPMessage
              extended by gov.nist.javax.sip.message.SIPRequest
All Implemented Interfaces:
MessageExt, Serializable, Cloneable, Message, Request

public final class SIPRequest
extends SIPMessage
implements Request

The SIP Request structure.

Since:
1.1
Version:
1.2 $Revision: 1.43 $ $Date: 2009/05/30 04:22:00 $
Author:
M. Ranganathan
See Also:
Serialized Form

Field Summary
 
Fields inherited from interface javax.sip.message.Request
ACK, BYE, CANCEL, INFO, INVITE, MESSAGE, NOTIFY, OPTIONS, PRACK, PUBLISH, REFER, REGISTER, SUBSCRIBE, UPDATE
 
Constructor Summary
SIPRequest()
          Constructor.
 
Method Summary
 void checkHeaders()
          Check header for constraints. (1) Invite options and bye requests can only have SIP URIs in the contact headers. (2) Request must have cseq, to and from and via headers. (3) Method in request URI must match that in CSEQ.
 Object clone()
          Make a clone (deep copy) of this object.
 SIPRequest createACKRequest()
          Create an ACK request from this request.
 SIPRequest createAckRequest(To responseToHeader)
          Creates a default ACK SIPRequest message for this original request.
 SIPRequest createBYERequest(boolean switchHeaders)
          Create a BYE request from this request.
 SIPRequest createCancelRequest()
          Creates a default SIPResquest message that would cancel this request.
 SIPRequest createErrorAck(To responseToHeader)
          Creates an ACK for non-2xx responses according to RFC3261 17.1.1.3
 SIPResponse createResponse(int statusCode)
          Creates a default SIPResponse message for this request.
 SIPResponse createResponse(int statusCode, String reasonPhrase)
          Creates a default SIPResponse message for this request.
 SIPRequest createSIPRequest(RequestLine requestLine, boolean switchHeaders)
          Create a new default SIPRequest from the original request.
 String debugDump()
          Convert to a formatted string for pretty printing.
 String encode()
          Encode the SIP Request as a string.
 byte[] encodeAsBytes(String transport)
          Encode this into a byte array.
 String encodeMessage()
          Encode only the headers and not the content.
 boolean equals(Object other)
          Compare for equality.
static String getCannonicalName(String method)
          Set to standard constants to speed up processing. this makes equals comparisons run much faster in the stack because then it is just identity comparision.
 String getDialogId(boolean isServer)
          Get a dialog identifier.
 String getDialogId(boolean isServer, String toTag)
          Get a dialog id given the remote tag.
 String getFirstLine()
          Get the first line encoded.
 Object getInviteTransaction()
           
 String getMergeId()
          Generates an Id for checking potentially merged requests.
 LinkedList getMessageAsEncodedStrings()
          Get the message as a linked list of strings.
 Object getMessageChannel()
          Book keeping method to get the messasge channel for the request.
 String getMethod()
          Get the method from the request line.
 RequestLine getRequestLine()
          Get the Request Line of the SIPRequest.
 URI getRequestURI()
          A conveniance function to access the Request URI.
 String getSIPVersion()
          Get the SIP version.
 Object getTransaction()
          Book keeping method to return the current tx for the request if one exists.
 String getViaHost()
          Get the host from the topmost via header.
 int getViaPort()
          Get the port from the topmost via header.
 boolean isNullRequest()
          Return true if this is a null request (i.e. does not have a request line ).
static boolean isTargetRefresh(String ucaseMethod)
           
 boolean match(Object matchObj)
          Match with a template.
 void setInviteTransaction(Object inviteTransaction)
           
 void setMessageChannel(Object messageChannel)
          Set the message channel for the request ( bookkeeping field ).
 void setMethod(String method)
          Set the method.
 void setNullRequest()
          Set a flag to indiate this is a special message ( encoded with CRLFCRLF ).
 void setRequestLine(RequestLine requestLine)
          Set the request line of the SIP Request.
 void setRequestURI(URI uri)
          Sets the RequestURI of Request.
 void setSIPVersion(String sipVersion)
          Set the sip version.
 void setTransaction(Object transaction)
          Book keeping field to set the current tx for the request.
 String toString()
          ALias for encode above.
 
Methods inherited from class gov.nist.javax.sip.message.SIPMessage
addFirst, addHeader, addHeader, addLast, addUnparsed, attachHeader, attachHeader, getApplicationData, getAuthorization, getCallId, getContactHeader, getContactHeaders, getContent, getContentDisposition, getContentEncoding, getContentLanguage, getContentLength, getContentTypeHeader, getCSeq, getErrorInfoHeaders, getExpires, getFrom, getFromTag, getHeader, getHeaderAsFormattedString, getHeaderNames, getHeaders, getHeaders, getMaxForwards, getMessageContent, getMultipartMimeContent, getRawContent, getRecordRouteHeaders, getRouteHeaders, getSize, getTo, getTopmostVia, getToTag, getTransactionId, getUnrecognizedHeaders, getViaHeaders, hasContent, hasFromTag, hashCode, hasHeader, hasToTag, isRequestHeader, isResponseHeader, merge, removeContent, removeFirst, removeHeader, removeHeader, removeLast, setApplicationData, setCallId, setCallId, setContent, setContentDisposition, setContentEncoding, setContentLanguage, setContentLength, setCSeq, setExpires, setFrom, setFromTag, setHeader, setHeader, setHeaders, setMaxForwards, setMessageContent, setMessageContent, setMessageContent, setMessageContent, setMessageContent, setSize, setTo, setToTag, setVia
 
Methods inherited from class gov.nist.javax.sip.message.MessageObject
dbgPrint, dbgPrint
 
Methods inherited from class gov.nist.core.GenericObject
debugDump, encode, getClassFromName, getMatcher, isMySubclass, makeClone, setMatcher
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface javax.sip.message.Message
addFirst, addHeader, addLast, getContent, getContentDisposition, getContentEncoding, getContentLanguage, getContentLength, getExpires, getHeader, getHeaderNames, getHeaders, getRawContent, getUnrecognizedHeaders, hashCode, removeContent, removeFirst, removeHeader, removeLast, setContent, setContentDisposition, setContentEncoding, setContentLanguage, setContentLength, setExpires, setHeader
 

Constructor Detail

SIPRequest

public SIPRequest()
Constructor.

Method Detail

isTargetRefresh

public static boolean isTargetRefresh(String ucaseMethod)
Returns:
true iff the method is a target refresh

getCannonicalName

public static String getCannonicalName(String method)
Set to standard constants to speed up processing. this makes equals comparisons run much faster in the stack because then it is just identity comparision. Character by char comparison is not required. The method returns the String CONSTANT corresponding to the String name.


getRequestLine

public RequestLine getRequestLine()
Get the Request Line of the SIPRequest.

Returns:
the request line of the SIP Request.

setRequestLine

public void setRequestLine(RequestLine requestLine)
Set the request line of the SIP Request.

Parameters:
requestLine - is the request line to set in the SIP Request.

debugDump

public String debugDump()
Convert to a formatted string for pretty printing. Note that the encode method converts this into a sip message that is suitable for transmission. Note hack here if you want to convert the nice curly brackets into some grotesque XML tag.

Overrides:
debugDump in class SIPMessage
Returns:
a string which can be used to examine the message contents.

checkHeaders

public void checkHeaders()
                  throws ParseException
Check header for constraints. (1) Invite options and bye requests can only have SIP URIs in the contact headers. (2) Request must have cseq, to and from and via headers. (3) Method in request URI must match that in CSEQ.

Throws:
ParseException

getRequestURI

public URI getRequestURI()
A conveniance function to access the Request URI.

Specified by:
getRequestURI in interface Request
Returns:
the requestURI if it exists.

setRequestURI

public void setRequestURI(URI uri)
Sets the RequestURI of Request. The Request-URI is a SIP or SIPS URI or a general URI. It indicates the user or service to which this request is being addressed. SIP elements MAY support Request-URIs with schemes other than "sip" and "sips", for example the "tel" URI scheme. SIP elements MAY translate non-SIP URIs using any mechanism at their disposal, resulting in SIP URI, SIPS URI, or some other scheme.

Specified by:
setRequestURI in interface Request
Parameters:
uri - the new Request URI of this request message

setMethod

public void setMethod(String method)
Set the method.

Specified by:
setMethod in interface Request
Parameters:
method - is the method to set.
Throws:
IllegalArgumentException - if the method is null

getMethod

public String getMethod()
Get the method from the request line.

Specified by:
getMethod in interface Request
Returns:
the method from the request line if the method exits and null if the request line or the method does not exist.

encode

public String encode()
Encode the SIP Request as a string.

Overrides:
encode in class SIPMessage
Returns:
an encoded String containing the encoded SIP Message.

encodeMessage

public String encodeMessage()
Encode only the headers and not the content.

Specified by:
encodeMessage in class SIPMessage

toString

public String toString()
ALias for encode above.

Specified by:
toString in interface Message
Specified by:
toString in class SIPMessage
Returns:
string representation of Message

clone

public Object clone()
Make a clone (deep copy) of this object. You can use this if you want to modify a request while preserving the original

Specified by:
clone in interface Message
Overrides:
clone in class SIPMessage
Returns:
a deep copy of this object.

equals

public boolean equals(Object other)
Compare for equality.

Specified by:
equals in interface Message
Overrides:
equals in class SIPMessage
Parameters:
other - object to compare ourselves with.
Returns:
true if the objects are euqal and false otherwise

getMessageAsEncodedStrings

public LinkedList getMessageAsEncodedStrings()
Get the message as a linked list of strings. Use this if you want to iterate through the message.

Overrides:
getMessageAsEncodedStrings in class SIPMessage
Returns:
a linked list containing the request line and headers encoded as strings.

match

public boolean match(Object matchObj)
Match with a template. You can use this if you want to match incoming messages with a pattern and do something when you find a match. This is useful for building filters/pattern matching responders etc.

Overrides:
match in class SIPMessage
Parameters:
matchObj - object to match ourselves with (null matches wildcard)
Returns:
true if a match occured and false otherwise.

getDialogId

public String getDialogId(boolean isServer)
Get a dialog identifier. Generates a string that can be used as a dialog identifier.

Specified by:
getDialogId in class SIPMessage
Parameters:
isServer - is set to true if this is the UAS and set to false if this is the UAC

getDialogId

public String getDialogId(boolean isServer,
                          String toTag)
Get a dialog id given the remote tag.


encodeAsBytes

public byte[] encodeAsBytes(String transport)
Encode this into a byte array. This is used when the body has been set as a binary array and you want to encode the body as a byte array for transmission.

Overrides:
encodeAsBytes in class SIPMessage
Returns:
a byte array containing the SIPRequest encoded as a byte array.

createResponse

public SIPResponse createResponse(int statusCode)
Creates a default SIPResponse message for this request. Note You must add the necessary tags to outgoing responses if need be. For efficiency, this method does not clone the incoming request. If you want to modify the outgoing response, be sure to clone the incoming request as the headers are shared and any modification to the headers of the outgoing response will result in a modification of the incoming request. Tag fields are just copied from the incoming request. Contact headers are removed from the incoming request. Added by Jeff Keyser.

Parameters:
statusCode - Status code for the response. Reason phrase is generated.
Returns:
A SIPResponse with the status and reason supplied, and a copy of all the original headers from this request.

createResponse

public SIPResponse createResponse(int statusCode,
                                  String reasonPhrase)
Creates a default SIPResponse message for this request. Note You must add the necessary tags to outgoing responses if need be. For efficiency, this method does not clone the incoming request. If you want to modify the outgoing response, be sure to clone the incoming request as the headers are shared and any modification to the headers of the outgoing response will result in a modification of the incoming request. Tag fields are just copied from the incoming request. Contact headers are removed from the incoming request. Added by Jeff Keyser. Route headers are not added to the response.

Parameters:
statusCode - Status code for the response.
reasonPhrase - Reason phrase for this response.
Returns:
A SIPResponse with the status and reason supplied, and a copy of all the original headers from this request except the ones that are not supposed to be part of the response .

createCancelRequest

public SIPRequest createCancelRequest()
                               throws SipException
Creates a default SIPResquest message that would cancel this request. Note that tag assignment and removal of is left to the caller (we use whatever tags are present in the original request).

Returns:
A CANCEL SIPRequest constructed according to RFC3261 section 9.1
Throws:
SipException
ParseException

createAckRequest

public SIPRequest createAckRequest(To responseToHeader)
Creates a default ACK SIPRequest message for this original request. Note that the defaultACK SIPRequest does not include the content of the original SIPRequest. If responseToHeader is null then the toHeader of this request is used to construct the ACK. Note that tag fields are just copied from the original SIP Request. Added by Jeff Keyser.

Parameters:
responseToHeader - To header to use for this request.
Returns:
A SIPRequest with an ACK method.

createErrorAck

public final SIPRequest createErrorAck(To responseToHeader)
                                throws SipException,
                                       ParseException
Creates an ACK for non-2xx responses according to RFC3261 17.1.1.3

Returns:
A SIPRequest with an ACK method.
Throws:
SipException
NullPointerException
ParseException

createSIPRequest

public SIPRequest createSIPRequest(RequestLine requestLine,
                                   boolean switchHeaders)
Create a new default SIPRequest from the original request. Warning: the newly created SIPRequest, shares the headers of this request but we generate any new headers that we need to modify so the original request is umodified. However, if you modify the shared headers after this request is created, then the newly created request will also be modified. If you want to modify the original request without affecting the returned Request make sure you clone it before calling this method. Only required headers are copied.

Parameters:
requestLine - is the new request line.
switchHeaders - is a boolean flag that causes to and from headers to switch (set this to true if you are the server of the transaction and are generating a BYE request). If the headers are switched, we generate new From and To headers otherwise we just use the incoming headers.
Returns:
a new Default SIP Request which has the requestLine specified.

createBYERequest

public SIPRequest createBYERequest(boolean switchHeaders)
Create a BYE request from this request.

Parameters:
switchHeaders - is a boolean flag that causes from and isServerTransaction to headers to be swapped. Set this to true if you are the server of the dialog and are generating a BYE request for the dialog.
Returns:
a new default BYE request.

createACKRequest

public SIPRequest createACKRequest()
Create an ACK request from this request. This is suitable for generating an ACK for an INVITE client transaction.

Returns:
an ACK request that is generated from this request.

getViaHost

public String getViaHost()
Get the host from the topmost via header.

Returns:
the string representation of the host from the topmost via header.

getViaPort

public int getViaPort()
Get the port from the topmost via header.

Returns:
the port from the topmost via header (5060 if there is no port indicated).

getFirstLine

public String getFirstLine()
Get the first line encoded.

Specified by:
getFirstLine in class SIPMessage
Returns:
a string containing the encoded request line.

setSIPVersion

public void setSIPVersion(String sipVersion)
                   throws ParseException
Set the sip version.

Specified by:
setSIPVersion in interface Message
Specified by:
setSIPVersion in class SIPMessage
Parameters:
sipVersion - the sip version to set.
Throws:
ParseException - which signals that an error has been reached unexpectedly while parsing the version argument.

getSIPVersion

public String getSIPVersion()
Get the SIP version.

Specified by:
getSIPVersion in interface Message
Specified by:
getSIPVersion in class SIPMessage
Returns:
the SIP version from the request line.

getTransaction

public Object getTransaction()
Book keeping method to return the current tx for the request if one exists.

Returns:
the assigned tx.

setTransaction

public void setTransaction(Object transaction)
Book keeping field to set the current tx for the request.

Parameters:
transaction -

getMessageChannel

public Object getMessageChannel()
Book keeping method to get the messasge channel for the request.

Returns:
the message channel for the request.

setMessageChannel

public void setMessageChannel(Object messageChannel)
Set the message channel for the request ( bookkeeping field ).

Parameters:
messageChannel -

getMergeId

public String getMergeId()
Generates an Id for checking potentially merged requests.

Returns:
String to check for merged requests

setInviteTransaction

public void setInviteTransaction(Object inviteTransaction)
Parameters:
inviteTransaction - the inviteTransaction to set

getInviteTransaction

public Object getInviteTransaction()
Returns:
the inviteTransaction

isNullRequest

public boolean isNullRequest()
Return true if this is a null request (i.e. does not have a request line ).

Returns:
true if null request.

setNullRequest

public void setNullRequest()
Set a flag to indiate this is a special message ( encoded with CRLFCRLF ).


NIST-SIP: The Reference Implementation for JAIN-SIP 1.2

A product of the NIST/ITL Advanced Networking Technologies Division.
See conditions of use.
Submit a bug report or feature request.