Interface SipFactory


  • public interface SipFactory
    • Method Detail

      • getLocalSipURI

        SipURI getLocalSipURI​(String transport)
        Convenience method for obtaining a SIP URI addressed to the calling service on this host. For example, an SBB might want to forward a request to an external application server, then route it back to this service. This can be achieved by pushing a route to the app server followed by a Route containing this local SIP URI.
        Parameters:
        transport - a case-insensitive transport name, such as "udp", "tcp" or "tls". This will be used as the transport parameter in the resulting SipURI, unless transport is "tls", in which case the RA Entity shall return a secure sips: URI. If transport is null, no transport parameter will be used in the URI.
        Returns:
        a SipURI addressed to the calling service on this SIP RA Entity.
        Since:
        EasySIP 1.2
      • getLocalSipURI

        SipURI getLocalSipURI​(String transport,
                              boolean secure)
        Convenience method for obtaining a SIP URI addressed to the calling service on this host. For example, an SBB might want to forward a request to an external application server, then route it back to this service. This can be achieved by pushing a route to the app server followed by a Route containing this local SIP URI.
        Parameters:
        transport - a case-insensitive transport name, such as "udp", "tcp" or "tls". This will be used as the transport parameter in the resulting SipURI. If transport is null, no transport parameter will be used in the URI.
        secure - if true, the URI returned will be a SIPS URI. If transport was "tls" then the transport parameter in the SIPS URI will be omitted.
        Returns:
        a SipURI addressed to the calling service on this SIP RA Entity.
        Since:
        EasySIP 3.0
      • isLocalSipURI

        boolean isLocalSipURI​(SipURI uri)
        Determine if a URI is local to this SIS instance, .
        Returns:
        true if the host and port in the URI match an endpoint that this SIS instance is listening on (or a configured virtual address), otherwise false.
      • createAddress

        Address createAddress​(String sipAddress)
                       throws SipParseException
        Returns an Address corresponding to the specified string. The resulting object can be used, for example, as the value of From or To headers of locally initiated SIP requests.

        The special argument "*" results in a wildcard Address being returned, that is, an Address for which isWildcard returns true. Such addresses are for use in Contact headers only.

        Parameters:
        sipAddress - a valid SIP address from a From or To header.
        Returns:
        a parsed Address
        Throws:
        SipParseException - if parsing fails
      • createAddress

        Address createAddress​(URI uri)
      • createRequest

        OutgoingSipRequest createRequest​(String method,
                                         Address from,
                                         Address to)
                                  throws SipException
        Returns a new request object with the specified request method, From, and To headers. The returned request belongs a new SipSession activity, accessible using SipMessage.getSession(). SBBs must attach to the session in order to receive responses.

        This method is used by SBBs acting as SIP clients in order to send a request in a new call leg. The RA is responsible for assigning the request appropriate Call-ID and CSeq headers, as well as Contact header if the method is not REGISTER.

        This method makes a copy of the from and to arguments and associates them with the new SipSession. Any component of the from and to URIs not allowed in the context of SIP From and To headers are removed from the copies. This includes, headers and various parameters. Also, a "tag" parameter in either of the copied from or to is also removed, as it is illegal in an initial To header and the RA will choose it's own tag for the From header. The copied from and to addresses can be obtained from the SipSession but must not be modified by applications.

        Parameters:
        method - the method of the new request, e.g. "INVITE"
        from - value of the From header
        to - value of the To header
        Returns:
        a new request object with method, request-URI, and From, To, Call-ID, CSeq, Route headers filled in
        Throws:
        IllegalArgumentException - if the method is "ACK" or "CANCEL"
        SipException - if unable to create the request or session activity
      • createRequest

        OutgoingSipRequest createRequest​(String method,
                                         URI from,
                                         URI to)
                                  throws SipException
        Returns a new request object with the specified request method, From, and To headers. The returned request belongs a new SipSession activity, accessible using SipMessage.getSession(). SBBs must attach to the session in order to receive responses.

        This method is used by SBBs acting as SIP clients in order to send a request in a new call leg. The RA is responsible for assigning the request appropriate Call-ID and CSeq headers, as well as Contact header if the method is not REGISTER.

        This method makes a copy of the from and to arguments and associates them with the new SipSession. Any component of the from and to URIs not allowed in the context of SIP From and To headers are removed from the copies. This includes, headers and various parameters. Also, a "tag" parameter in either of the copied from or to is also removed, as it is illegal in an initial To header and the RA will choose it's own tag for the From header. The copied from and to addresses can be obtained from the SipSession but must not be modified by applications.

        Parameters:
        method - the method of the new request, e.g. "INVITE"
        from - value of the From header
        to - value of the To header
        Returns:
        a new request object with method, request-URI, and From, To, Call-ID, CSeq, Route headers filled in
        Throws:
        IllegalArgumentException - if the method is "ACK" or "CANCEL"
        SipException - if unable to create the request or session activity
      • createRequest

        OutgoingSipRequest createRequest​(String method,
                                         String from,
                                         String to)
                                  throws SipException,
                                         SipParseException
        Returns a new request object with the specified request method, From, and To headers. The returned request belongs a new SipSession activity, accessible using SipMessage.getSession(). SBBs must attach to the session in order to receive responses.

        This method is used by SBBs acting as SIP clients in order to send a request in a new call leg. The RA is responsible for assigning the request appropriate Call-ID and CSeq headers, as well as Contact header if the method is not REGISTER.

        This method makes a copy of the from and to arguments and associates them with the new SipSession. Any component of the from and to URIs not allowed in the context of SIP From and To headers are removed from the copies. This includes, headers and various parameters. Also, a "tag" parameter in either of the copied from or to is also removed, as it is illegal in an initial To header and the RA will choose it's own tag for the From header. The copied from and to addresses can be obtained from the SipSession but must not be modified by applications.

        Parameters:
        method - the method of the new request, e.g. "INVITE"
        from - value of the From header, this must be a valid Address
        to - value of the To header, this must be a valid Address
        Returns:
        a new request object with method, request-URI, and From, To, Call-ID, CSeq, Route headers filled in
        Throws:
        IllegalArgumentException - if the method is "ACK" or "CANCEL"
        SipParseException - if the URI scheme of the from or to argument is unknown or if parsing failed
        SipException - if unable to create the request or session activity
      • createRequest

        OutgoingSipRequest createRequest​(IncomingSipRequest origRequest,
                                         boolean sameCallId)
                                  throws SipException
        Creates a new request object belonging to a new SipSession. The new request is similar to the specified origRequest in that the method and the majority of header fields are copied from origRequest to the new request.

        This method satisfies the following rules:

        • The From header field of the new request has a new tag chosen by the RA.
        • The To header field of the new request has no tag.
        • If the sameCallId argument is false, the new request (and the corresponding SipSession) is assigned a new Call-ID.
        • Record-Route and Via header fields are not copied. The RA will add its own Via header field to the request.
        • For non-REGISTER requests, the Contact header field is not copied but is populated by the RA.
        This method provides a convenient and efficient way of constructing the second "leg" of a B2BUA application. It is used only for the initial request. Subsequent requests in either leg must be created using SipSession.createRequest(java.lang.String) as usual.
        Parameters:
        origRequest - request to be "copied".
        sameCallId - whether or not to use the same Call-ID for the new dialog.
        Returns:
        the "copied" request object.
        Throws:
        SipException - if unable to create the request or session activity
      • encodeMessage

        void encodeMessage​(SipMessage message,
                           DataOutput out)
                    throws IOException
        Encode a SipMessage to an output stream, for storage in CMP. The encoding format is internal to the SIS and is only suitable for decoding via decodeMessage(DataInput).
        Parameters:
        message - the message to encode
        out - the data output stream
        Throws:
        IOException - if unable to encode the message
      • getInternalASURI

        SipURI getInternalASURI()
        Get a URI that uniquely identifies this AS including it node and cluster IDs, for use when directing inter-node traffic.
        Returns:
        a URI that uniquely identifies this node.
      • isInternalASURI

        boolean isInternalASURI​(URI uri)
        Check if a URI matches this node's internal AS URI.
        Parameters:
        uri - The URI to check
        Returns:
        true if the given URI matches the internal AS URI for this node.
      • isInternalASURI

        boolean isInternalASURI​(String uri)
        Check if a URI matches this node's internal AS URI.
        Parameters:
        uri - The URI to check
        Returns:
        true if the given URI matches the internal AS URI for this node.
      • registerLimiterFilter

        void registerLimiterFilter​(SipLimiterFilter filter)
        Register a rate limiter filter. Filters return if the incoming initial request should be considered for limiting. Filters are linked to individual services for lifetime management but apply to all requests, regardless of which composition and services are invoked. Should be called during service activation to ensure that no events are missed by the filter.
        Parameters:
        filter - The filter registered by the service
      • registerOverloadControlPlugin

        void registerOverloadControlPlugin​(SipOverloadControlPlugin overloadControlPlugin)
        Register an overload control plugin. If a plugin is registered, SIS will invoke it for every received request prior to regular Rhino platform overload control.

        At most one overload control plugin can be registered with each SIS instance in a given JVM instance at any one time. Registering a plugin atomically deregisters any previously registered plugin.

        Parameters:
        overloadControlPlugin - the plugin to register. May be null, which deregisters any previously registered plugin.
      • getRegisteredOverloadControlPlugin

        SipOverloadControlPlugin getRegisteredOverloadControlPlugin()
        Retrieves the currently registered overload control plugin.
        Returns:
        the currently registered plugin, or null if there is no registered plugin.