Package org.jainslee.resources.sip

Interface IncomingSipRequest

  • All Superinterfaces:
    SipMessage, SipRequest
    public interface IncomingSipRequest
extends SipRequest
    Represents an incoming SIP request and it's underlying server transaction. Requests are defined to be initial requests if they are the first request on a new SipSession. Only initial requests may be proxied. Subsequent requests (in-dialog requests) do not need to be proxied, they will automatically follow the route established by the initial request.

    • Method Detail

      • createResponse

        OutgoingSipResponse createResponse​(int statusCode)
        Create a response for this request, with the specified status code.
        Parameters:
        statusCode - status code for the response
        Returns:
        a new OutgoingSipResponse object with the specified status code.

      • createResponse

        OutgoingSipResponse createResponse​(int statusCode,
                                   String reasonPhrase)
        Create a response for this request, with the specified status code and reason phrase.
        Parameters:
        statusCode - status code for the response
        reasonPhrase - reason phrase for the response
        Returns:
        a new OutgoingSipResponse object with the specified status code and reason phrase.

      • createStatelessResponse

        StatelessSipResponse createStatelessResponse​(int statusCode,
                                             String reasonPhrase)
        Create a provisional stateless response for this request, with the specified status code and reason phrase. Sending this stateless response will not affect session state.
        Parameters:
        statusCode - status code for the response, must be between 100 and 199
        reasonPhrase - reason phrase for the response, may be null
        Returns:
        a new StatelessSipResponse object with the specified status code and reason phrase, and a to-tag that will not match the local tag of this session.
        Throws:
        IllegalArgumentException - if statusCode is less than 100 or greater than 199

      • createResponse

        OutgoingSipResponse createResponse​(IncomingSipResponse incoming)
        Create a response for this request, copying any additional headers and content from an IncomingSipResponse received on another session. This is a convenience method for B2BUAs to forward responses easily.
        Parameters:
        incoming - the incoming response to base the new response on.
        Returns:
        a new OutgoingSipResponse with the status code, content and additional headers from the original incoming response
        Since:
        EasySIP 1.0 - no equivalent in SIP Servlet API

      • createResponse

        OutgoingSipResponse createResponse​(IncomingSipResponse incoming,
                                   SipSession session)
        Create a response for this request on the given session, copying any additional headers and content from an IncomingSipResponse received on another session. This is a convenience method for B2BUAs to forward responses easily.
        Parameters:
        incoming - the incoming response to base the new response on.
        session - the session to create the response on.
        Returns:
        a new OutgoingSipResponse with the status code, content and additional headers from the original incoming response
        Since:
        EasySIP 1.0 - no equivalent in SIP Servlet API

      • createForkedResponse

        OutgoingSipResponse createForkedResponse​(IncomingSipResponse incoming)
        Creates a new outgoing response and a new SipSession, for forwarding forked responses upstream. This is a convenience method so that B2BUAs handling several UAC SipSessions created by a downstream element forking can easily create the corresponding UAS SipSessions, and handle early dialog interactions on those SipSessions. The new forked UAS session can be obtained by calling SipMessage.getSession() on the returned OutgoingSipResponse. The caller should then send the response upstream by calling its send() method.
        Parameters:
        incoming - a forked IncomingSipResponse received on a UAC SipSession
        Returns:
        a new OutgoingSipResponse with the status code, content and additional headers from the original incoming response. The Call-Id and from-tag will match the original UAS SipSession created by the initial request, and the to-tag will be copied from the incoming response.
        Throws:
        IllegalStateException - if the request was not an initial request
        IllegalArgumentException - if the response was not a forked response, see IncomingSipResponse.isForked()
        Since:
        EasySIP RA Type 1.3

      • createForkedResponse

        OutgoingSipResponse createForkedResponse​(int statusCode)
        Create a response for this request, with the specified status code, and a new SipSession, for sending responses upstream. The new forked UAS session can be obtained by calling SipMessage.getSession() on the returned OutgoingSipResponse. The caller should then send the response upstream by calling its send() method.
        Parameters:
        statusCode - status code for the response
        Returns:
        a new OutgoingSipResponse object with the specified status code. The Call-Id and from-tag will match the original UAS SipSession created by the initial request, and the to-tag will be new.
        Throws:
        IllegalStateException - if the request was not an initial request
        IllegalArgumentException - if the response is not a dialog creating response IncomingSipResponse.isForked()
        Since:
        EasySIP RA Type 1.4

      • createForkedResponse

        OutgoingSipResponse createForkedResponse​(int statusCode,
                                         String reasonPhrase)
        Create a response for this request, with the specified status code and reason phrase, and a new SipSession, for sending responses upstream. The new forked UAS session can be obtained by calling SipMessage.getSession() on the returned OutgoingSipResponse. The caller should then send the response upstream by calling its send() method.
        Parameters:
        statusCode - status code for the response
        reasonPhrase - reason phrase for the response
        Returns:
        a new OutgoingSipResponse object with the specified status code and reason phrase. The Call-Id and from-tag will match the original UAS SipSession created by the initial request, and the to-tag will be new.
        Throws:
        IllegalStateException - if the request was not an initial request
        IllegalArgumentException - if the response is not a dialog creating response IncomingSipResponse.isForked()
        Since:
        EasySIP RA Type 1.4

      • getProxy

        Proxy getProxy()
        throws TooManyHopsException,
               IllegalStateException
        Returns the Proxy activity for this request, creating one if it did not already exist. This behaves like getProxy(true).
        Returns:
        the Proxy activity associated with this request
        Throws:
        TooManyHopsException - if this request's Max-Forwards header is zero.
        IllegalStateException - if a final response has already been sent for this request; or if the application has already sent a dialog-creating response (indicating it wants to be the UAS for this session); or if this request is not an initial request.

      • getProxy

        Proxy getProxy​(boolean create)
        throws TooManyHopsException,
               IllegalStateException
        Returns the Proxy activity for this request. If no proxy has yet been created for this request, the create argument specifies whether a new one should be created or not.
        Parameters:
        create - specifies whether or not to create a proxy activity one is not already associated with this request.
        Returns:
        the Proxy activity associated with this request, or null if no such activity exists and create is false.
        Throws:
        TooManyHopsException - if this request's Max-Forwards header is zero.
        IllegalStateException - if a final response has already been sent for this request; or if the application has already sent a dialog-creating response (indicating it wants to be the UAS for this session); or if this request is not an initial request.

      • getFinalResponse

        OutgoingSipResponse getFinalResponse()
        Gets the final response that was sent in response to this request.
        Specified by:
        getFinalResponse in interface SipRequest
        Returns:
        the final response, or null if no response has been sent yet.
        Since:
        EasySIP 1.2

      • isForked

        boolean isForked()
        Determines whether this request was the result of a downstream element forking the initial request.

        Currently this may only be a NOTIFY, resulting from a forked initial SUBSCRIBE request.

        Each forked NOTIFY creates a new SipSession activity representing the new dialog that was created by the fork.

        Forked request events are fired on the ACI of the original SipSession; this is because the service will already be attached to this ACI, and doesn't know about the forked sessions until requests arrive. The SipMessage.getSession() method on forked requests returns the SipSession that resulted from the fork, so services can retrieve and attach to these activities if necessary.

        Forked NOTIFYs may be received when proxying (with record-route) or acting as a UAC/B2BUA. When proxying, if a forked NOTIFY is received, the application just needs to attach to the new SipSession of the forked NOTIFY request. A B2BUA must forward the NOTIFY upstream using SipSession.createForkedNotify(IncomingSipRequest), which creates the new SipSession on the upstream side.

        Subsequent messages may arrive on sessions that were created by an earlier forked NOTIFY. These subsequent messages are not forked, and will be delivered on their respective SipSessions. Therefore a service that wants to see all subsequent messages on all forked sessions must attach to forked sessions when they are detected.

        Returns:
        true if this request is the result of a downstream element forking; otherwise false.
        Since:
        EasySIP RA Type 1.4