Package com.opencloud.sentinel.multileg

Interface LegManager

  • public interface LegManager

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      Leg createLeg​(org.jainslee.resources.sip.OutgoingSipRequest initialRequest, java.lang.String legName)
      Immediately create a leg and queue the initialRequest request in the MessagesToSend queue of the leg.
      void detachFromAllLegs()
      Immediately detach from all legs.
      void detachFromLeg​(Leg leg)
      Immediately remove the Leg from the leg manager.
      void disableSessionReplication()
      Permanently disables replication for the current session.
      void enableSessionReplication()
      Enables replication for the current session.
      void endSession()
      Immediately clear all pending requests on all legs.
      void endSession​(int endSessionCause)
      Behaves the same as endSession() except that it uses the endSessionCause when ending all leg sessions.
      java.lang.String getCallingParty()
      Return the leg name associated with 'CallingParty' for this Sentinel SIP service instance.
      Leg getCallingPartyLeg()
      Return the calling party leg for this Sentinel SIP service instance.
      Leg getLeg​(java.lang.String legName)
      Return the leg with name legName
      Leg getLeg​(javax.slee.ActivityContextInterface aci)
      Determine the leg associated with the specified aci.
      Leg getLeg​(org.jainslee.resources.sip.SipSession session)
      Determine the leg associated with the specified session.
      int getLegCount()
      Get the number of legs for the Sentinel SIP service instance.
      java.util.Collection<Leg> getLegs()
      Return a Collection of legs for the Sentinel SIP service instance.
      Leg importAsNewLeg​(javax.slee.ActivityContextInterface aci, java.lang.String legName, InitialLegPhase legPhase)
      Immediately create a new leg in the indicated phase (InitialLegPhase.CallSetup or InitialLegPhase.MidSession).
      Leg importAsNewLeg​(org.jainslee.resources.sip.SipSession session, java.lang.String legName, InitialLegPhase legPhase)
      Immediately create a new leg in the indicated phase (InitialLegPhase.CallSetup or InitialLegPhase.MidSession).
      Leg importHandoverLeg​(org.jainslee.resources.sip.IncomingSipRequest handoverRequest, java.lang.String legName)
      Imports a SIP session for a handover request into a new leg in the call-setup phase with the given leg name.
      boolean isLegEnding​(Leg leg)
      Determines whether the given leg is ending, i.e. it has been detached or released, or the session is ending.
      boolean isLegInviteSessionEnding​(Leg leg)
      Determines whether the given leg has an INVITE session which is ending, i.e. the leg has been detached or released, or the session is ending.
      boolean isSessionEnding()
      Get whether end session has been invoked
      boolean isSessionReplicationDisabled()
      Get whether replication has been permanently disabled for this session.
      boolean isSessionReplicationEnabled()
      Get whether replication has been enabled for this session.
      void proxySessionAndDoNotRecordRoute​(Leg leg)
      Proxy the initial request received on the leg using the URI received in the initial request.
      void proxySessionAndDoNotRecordRoute​(Leg leg, org.jainslee.resources.sip.URI newRequestUri)
      Proxy the initial request received on the leg using a different request URI.
      void proxySessionAndDoNotRecordRoute​(Leg leg, org.jainslee.resources.sip.URI[] newRequestUris)
      Proxy the session to continue using different request URIs and remove Sentinel from the route.
      ProxyResult proxySessionInternal​(Leg leg, org.jainslee.resources.sip.URI newRequestUri)
      Proxy the initial request received on the leg using a different request URI.
      void releaseLeg​(Leg leg)
      Immediately unlinks the leg if it is linked, clears any pending instructions and adds the releaseLeg instruction.
      void setCallingParty​(java.lang.String legName)
      Set the leg name associated with 'CallingParty' for this Sentinel SIP service instance.

    • Field Detail

      • CALLINGPARTY_NAME

        static final java.lang.String CALLINGPARTY_NAME
        Leg name used for the original Calling Party for this Sentinel SIP service instance.
        See Also:
        Constant Field Values

    • Method Detail

      • createLeg

        Leg createLeg​(org.jainslee.resources.sip.OutgoingSipRequest initialRequest,
              java.lang.String legName)
       throws DuplicateLegException
        Immediately create a leg and queue the initialRequest request in the MessagesToSend queue of the leg. The initialRequest will be sent if it is not subsequently removed or altered when session management processes instructions.
        Parameters:
        initialRequest - OutgoingSipRequest to be sent.
        legName - the legName must be unique for this Sentinel SIP service instance. The recommended format for the name is - e.g. conferenceFeature-conferenceModerator. Leg names are case sensitive.
        Returns:
        created new Leg.
        Throws:
        DuplicateLegException - If leg already exists with the supplied name.

      • importAsNewLeg

        Leg importAsNewLeg​(javax.slee.ActivityContextInterface aci,
                   java.lang.String legName,
                   InitialLegPhase legPhase)
            throws DuplicateLegException
        Immediately create a new leg in the indicated phase (InitialLegPhase.CallSetup or InitialLegPhase.MidSession). Associate the new leg with the provided ACI. Attach the Sentinel SIP Service SBB to the ACI.
        Parameters:
        aci - ACI of new Leg. The ACI must have an activity of type SipSession. The created Leg is accessed in the next feature invocation using the legName.
        legName - the legName must be unique for this Sentinel SIP service instance. The recommended format for the legName is - e.g. conferenceFeature-conferenceModerator. Leg names are case sensitive.
        legPhase - InitialLegPhase of Leg.
        Returns:
        Imported Leg.
        Throws:
        DuplicateLegException - If leg already exists with the supplied name.

      • importAsNewLeg

        Leg importAsNewLeg​(org.jainslee.resources.sip.SipSession session,
                   java.lang.String legName,
                   InitialLegPhase legPhase)
            throws DuplicateLegException
        Immediately create a new leg in the indicated phase (InitialLegPhase.CallSetup or InitialLegPhase.MidSession). Associate the new leg with the provided SipSession activity. Attach the SBB to the ACI associated with the SipSession activity.
        Parameters:
        session - SipSession activity to be associated with the new Leg.
        legName - the legName must be unique for this Sentinel SIP service instance. The recommended format for the legName is - e.g. conferenceFeature-conferenceModerator. Leg names are case sensitive.
        legPhase - InitialLegPhase of Leg.
        Returns:
        Imported Leg.
        Throws:
        DuplicateLegException - If a leg already exists with the supplied legName.

      • importHandoverLeg

        Leg importHandoverLeg​(org.jainslee.resources.sip.IncomingSipRequest handoverRequest,
                      java.lang.String legName)
               throws DuplicateLegException
        Imports a SIP session for a handover request into a new leg in the call-setup phase with the given leg name. If the handover request contains SDP, then the new leg's latest received SDP will be set to match it.
        Parameters:
        handoverRequest - The handover request from the session to import.
        legName - the legName must be unique for this Sentinel SIP service instance. The recommended format for the legName is - e.g. conferenceFeature-conferenceModerator. Leg names are case sensitive.
        Returns:
        The newly imported leg.
        Throws:
        DuplicateLegException - If a leg already exists with the supplied legName.

      • releaseLeg

        void releaseLeg​(Leg leg)
        Immediately unlinks the leg if it is linked, clears any pending instructions and adds the releaseLeg instruction.

        The action taken when processing the releaseLeg instruction can be:

        1. sending a BYE (not waiting for subsequent 200 Ok response)
        2. sending a final error response
        3. sending a CANCEL (waiting for the 487 ReqTerm response, or crossover with 200 OK response)
        4. sending a final SUBSCRIBE
        5. sending a terminating NOTIFY

        The appropriate action will depend on the current state of the leg. If there is a terminating message in the MessagesToSend queue of the leg, this will be used where possible.

        In the CANCEL-200 OK crossover case, the core will send ACK + BYE.

        When the LegManager has sent the Error, BYE, CANCEL or NOTIFY on processing the releaseLeg instruction it will immediately remove the leg from the LegManager registry, although it may still be attached to the corresponding activity in the SLEE sense. I.e. using 'releaseLeg' features will get the impression that the leg has already gone, although the core might still wait for response events on it. Only when the core is certain that the leg release has been managed to completion will it actually detach from the activity in the SLEE sense.

        Features which need a more fine-grained control over the release process should use a combination of Leg.sendMessage(org.jainslee.resources.sip.SipMessage), Leg#sendCancel(), detachFromLeg(Leg leg).

        Parameters:
        leg - Leg to release.

      • detachFromLeg

        void detachFromLeg​(Leg leg)
        Immediately remove the Leg from the leg manager. Detach the SBB from the ACI associated with the leg. As this method takes effect immediately, it is necessary to ensure that the SipSession/Activity has been handled and will end appropriately or that another Service will take control of it. Any pending instructions will not be processed on this leg. The detached Leg cannot be accessed via any subsequent features.
        Parameters:
        leg - Leg to detach.

      • detachFromAllLegs

        void detachFromAllLegs()
        Immediately detach from all legs. Each leg is processed as described in detachFromLeg(Leg). Formerly known as terminateProcessing.

      • isLegEnding

        boolean isLegEnding​(Leg leg)
        Determines whether the given leg is ending, i.e. it has been detached or released, or the session is ending.
        Parameters:
        leg - The leg to check.
        Returns:
        true if the leg is ending.

      • isLegInviteSessionEnding

        boolean isLegInviteSessionEnding​(Leg leg)
        Determines whether the given leg has an INVITE session which is ending, i.e. the leg has been detached or released, or the session is ending.
        Parameters:
        leg - The leg to check.
        Returns:
        true if the leg has an INVITE session and it is ending, false otherwise

      • proxySessionAndDoNotRecordRoute

        void proxySessionAndDoNotRecordRoute​(Leg leg)
        Proxy the initial request received on the leg using the URI received in the initial request. Remove Sentinel from the route.

        Note: If the leg is linked, the linked leg will be unlinked and detached.

        Parameters:
        leg - the leg that received the initial request.

      • proxySessionAndDoNotRecordRoute

        void proxySessionAndDoNotRecordRoute​(Leg leg,
                                     org.jainslee.resources.sip.URI newRequestUri)
        Proxy the initial request received on the leg using a different request URI. Remove Sentinel from the route.

        Note: If the leg is linked, the linked leg will be unlinked and detached.

        Parameters:
        leg - the leg that received the initial request.
        newRequestUri - the initial request will be proxied to this address

      • proxySessionAndDoNotRecordRoute

        void proxySessionAndDoNotRecordRoute​(Leg leg,
                                     org.jainslee.resources.sip.URI[] newRequestUris)
        Proxy the session to continue using different request URIs and remove Sentinel from the route.

        Note: If the leg is linked (B2BUA feature) calling this method unlink the linked leg and detach it.

        Parameters:
        leg - the leg that received the initial request.
        newRequestUris - the initial request will be proxied to these destinations

      • proxySessionInternal

        ProxyResult proxySessionInternal​(Leg leg,
                                 org.jainslee.resources.sip.URI newRequestUri)
        Proxy the initial request received on the leg using a different request URI. This URI should point to another node within this cluster. The node will be checked for liveness before attempting to proxy. If the proxy attempt is successful, Sentinel is removed from the Route and detaches from the given leg, and unlinks and detaches from the linked leg if one is present. If the proxy attempt is not successful, there will be no change to the legs.
        Parameters:
        leg - the leg that received the initial request.
        newRequestUri - the initial request will be proxied to this address
        Returns:
        PROXYING if the proxy was successful, or TARGET_NODE_UNAVAILABLE or NOT_PROXIABLE if not successful.

      • getLeg

        Leg getLeg​(java.lang.String legName)
        Return the leg with name legName

        The following well known leg names are used:

        • callingParty
        Parameters:
        legName - Unique name of the Leg.
        Returns:
        Leg associated with the legName.

      • getLeg

        Leg getLeg​(javax.slee.ActivityContextInterface aci)
        Determine the leg associated with the specified aci.
        Parameters:
        aci - ACI
        Returns:
        Leg associated with the aci or null if no leg associated with the aci

      • getLeg

        Leg getLeg​(org.jainslee.resources.sip.SipSession session)
        Determine the leg associated with the specified session.
        Parameters:
        session - SipSession
        Returns:
        Leg associated with the session or null if no leg associated with the session

      • getLegs

        java.util.Collection<Leg> getLegs()
        Return a Collection of legs for the Sentinel SIP service instance.
        Returns:
        Collection of legs.

      • getLegCount

        int getLegCount()
        Get the number of legs for the Sentinel SIP service instance.
        Returns:
        number of legs managed.

      • setCallingParty

        void setCallingParty​(java.lang.String legName)
        Set the leg name associated with 'CallingParty' for this Sentinel SIP service instance. Upstream forking may result in a different Leg being the 'CallingParty' than that which was received as the original incoming initial request.
        Parameters:
        legName - LegName of Calling party.

      • getCallingParty

        java.lang.String getCallingParty()
        Return the leg name associated with 'CallingParty' for this Sentinel SIP service instance. Upstream forking may result in a different Leg being the 'CallingParty' than that which was received as the original incoming initial request.
        Returns:
        Calling party leg name.

      • getCallingPartyLeg

        Leg getCallingPartyLeg()
        Return the calling party leg for this Sentinel SIP service instance.
        Returns:
        calling party leg

      • endSession

        void endSession()
        Immediately clear all pending requests on all legs. Queue an endSession instruction on all legs. If there are terminating message in the MessagesToSend queue of the legs, these will be used where possible.

        During instruction processing end session will be performed on each leg.

      • endSession

        void endSession​(int endSessionCause)
        Behaves the same as endSession() except that it uses the endSessionCause when ending all leg sessions.
        Parameters:
        endSessionCause - The reason (response code) to use for session termination.

      • isSessionEnding

        boolean isSessionEnding()
        Get whether end session has been invoked
        Returns:
        True if end session has been invoked.

      • isSessionReplicationEnabled

        boolean isSessionReplicationEnabled()
        Get whether replication has been enabled for this session. If true, all current and new legs are tracked by default. A false value does not guarantee that no legs are tracked, as other features may be tracking legs for their own purposes.
        Returns:
        True iff sessions replication has been enabled.

      • isSessionReplicationDisabled

        boolean isSessionReplicationDisabled()
        Get whether replication has been permanently disabled for this session. If true, no state is replicated. Legs may however be tracked in session ownership without replication.
        Returns:
        True iff session replication has been permanently disabled.

      • enableSessionReplication

        void enableSessionReplication()
        Enables replication for the current session. Will enable tracking on all legs currently handled by this leg manager, and cause all future legs created by this manager to have tracking enabled by default. Session replication can only be set once, if replication has already been set for this session (enabled or disabled), it cannot be changed and will result in a noop. Note that only legs initiated with an INVITE, REFER, or SUBSCRIBE request are affected. Legs initiated by other SIP requests are never tracked for session replication purposes.

      • disableSessionReplication

        void disableSessionReplication()
        Permanently disables replication for the current session. Will not enable tracking on any legs. Session replication can only be set once, if replication has already been set for this session (enabled or disabled), it cannot be changed and will result in a noop.