Creating a new TCAP Leg

Two methods of creating TCAP legs are available:

  1. Create a new leg that has no associated Dialog

  2. Create a new leg based on an existing Dialog

Create a new leg that has no associated Dialog

A feature establishes a new relation with an external network element by creating a new TCAP leg and calling issueOpenRequest() on the newly created leg.

create leg
Figure 1. TCAPLegManager.createLeg()

  1. MyFeature calls createLeg() on the TCAP Leg Manager. A new TCAP leg is immediately created (MyLeg). Newly created legs don’t have a Dialog or ACI associated with them yet.

  2. MyFeature creates a new DialogOpenRequest object and calls issueOpenRequest(openRequest) on the newly created TCAP leg. The TCAP Leg manager registers an instruction sendTcapMessage and the open request is set as the pending message on the newly created leg. Features that execute after MyFeature can make any changes to the pending message before the sendTcapMessage instruction is processed.

  3. Once the currently executing feature script execution point is finished, the TCAP Leg Manager processes any instructions for all legs. In this case the TCAP Leg Manager will process sendTcapMessage for the open request by:

    1. creating a new Dialog and sending the open request

    2. getting the associated ActivityContextInterface (ACI) for the newly created Dialog

    3. attaching to the ACI so all responses from the external network element will be receiv qed by the IPSMGW

Tip

The TCAP Leg Manager also provides a second, overloaded, variant of createLeg with an extra parameter with the name of a feature that should directly receive any events on the new leg.

TcapLeg createLeg(TcapApplicationContext appContext,
                  String legName,
                  String targetFeature)
                  throws DuplicateLegException, ProtocolException;

The TCAP Leg Manager will set the TargetFeature field of the SentinelActivityContextInterface for the newly created leg. The IPSMGW delivers events as extension events directly to a named feature if the TargetFeature field is set.

See: Feature Extension Events to learn more about Extension events.
Tip

See Operating on a TCAP Leg for more information about sending messages on TCAP legs.

Create a new leg based on an existing Dialog

A feature may create a TCAP leg from an ActivityContextInterface that corresponds to an existing relation with an external network element.

import as new leg
Figure 2. TCAPLegManager.importAsNewLeg()

Feature MyFeature calls importAsNewLeg(aci, "MyLeg") on the TCAP Leg Manager to create a new TCAP leg called MyLeg that is associated with the ACI aci.

Linking and unlinking TCAP Legs

In some cases it is convenient to be able to navigate from one TCAP leg to a related TCAP leg. A concrete example is the MAP proxy feature, which proxies messages between two related TCAP legs. You create a relation between two TCAP legs by linking them with the linkLeg(TcapLeg) operation.

link legs
Figure 3. TCAPLeg.linkLeg()

A link between two legs is bi-directional. Calling getLinkedLeg() on MyLeg will return OtherLeg and calling getLinkedLeg() on OtherLeg will return MyLeg. You can break the link between two legs by calling unlinkLeg() on either TCAP leg involved in a link.

Detaching from a TCAP Leg

Features detach from a TCAP leg when the leg is not needed anymore and the IPSMGW should not take any responsibility for further actions on the associated Dialog.

Detaching a TCAP leg removes the association between the TCAP leg manager and the TCAP leg. It is an action that takes place immediately. This means the leg cannot be used by any features that subsequently execute. The TCAP leg manager takes no action on the associated Dialog or ACI (if they exist).

Two methods for detaching a TCAP leg are available:

  1. Detach from a particular leg

  2. Detach from all known legs

Detach from a particular leg

detach from leg
Figure 4. TCAPLegManager.detachLeg()

MyFeature calls detachFromLeg(myLeg) on the TCAP Leg Manager. The TCAP leg MyLeg is immediately removed. The IPSMGW detaches from the associated ActivityContextInterface (if there is one). No pending instructions will be processed for the detached leg. The detached Leg cannot be accessed by any subsequent features that execute.

No actions are taken on the associated Dialog so it is important that either the feature ensures the dialog ends properly before detaching, or that an alternate service with the Rhino TAS will take responsibility for any further actions on the Dialog.

Detach from all known legs

detach from all legs
Figure 5. TCAPLegManager.detachAllLegs()

MyFeature calls detachAllLegs() on the TCAP Leg Manager. Each leg known by the leg manager is detached as described in section: Detach from a particular leg.

Releasing a TCAP Leg

Features release a TCAP leg when the leg is not needed anymore and the IPSMGW should also make sure the associated Dialog is ended correctly.

release leg
Figure 6. TCAPLegManager.releaseLeg()

  1. MyFeature calls releaseLeg(myLeg) on the TCAP Leg Manager.

  2. The leg MyLeg is immediately unlinked (if it is linked). Any pending instructions are removed and a new instruction (releaseLeg) is created. In this example a sendTcapMessage instruction is replaced with a releaseLeg instruction. Any pending message on the leg is preserved and may be used while processing the releaseLeg instruction. The leg can still be accessed by other features before the releaseLeg instruction is processed.

  3. Once the current feature script execution point finishes, the TCAP Leg Manager processes all pending instructions for all known legs. In this example the associated Dialog is ended, and then the TCAP leg MyLeg is removed.

The method used to end the Dialog depends on the Dialog State.

Dialog State Action …​

INIT_SENT_PENDING, INIT_SENT
An Open Request been sent, but no response has been received yet

Send a UserAbort to end the Dialog. If there is an existing pending UserAbort message then use it

INIT_RECEIVED
An Open Request has been received, but it has not been accepted or rejected yet

If there is no pending message on the leg, then send a DialogRefuse. If the pending message is an OpenAccept in a TC-End or an OpenRefuse then use it. Otherwise ignore any pending message and send a DialogRefuse.

ACTIVE_PENDING, ACTIVE
An Open Request has been received, and it has been accepted or the Dialog is fully established.

If there is a pending message that is a TC-End then use it. Otherwise send a Close(preArranged=false).

Features which need a more fine-grained control over the release process should use a combination of TcapLeg.sendClose(boolean), TcapLeg.sendUserAbort(DialogUserAbortTcapMessage) and TcapLegManager#detachFromLeg(TcapLeg).

Ending the Session

Feature end a session (endSession) when all existing TCAP legs are not needed anymore and the IPSMGW should also make sure all Dialogs associated with the existing legs are ended correctly.

end session
Figure 7. TCAPLegManager.endSession()

  1. MyFeature calls endSession() on the TCAP Leg Manager.

  2. All existing legs are released by unlinking them, removing any pending instructions and creating a releaseLeg instruction for each leg.

  3. Once the current feature script execution point finishes, the TCAP Leg Manager processes all pending instructions for all known legs. In this example the Dialogs associated with MyLeg and OtherLeg are ended (as described in Releasing a TCAP Leg) and both TCAP legs are removed.

Previous page Next page