This page presents the CGIN family of APIs.

CGIN family of APIs

CGIN provides a suite of APIs for INAP, CAP, and MAP. The diagram below shows the set of APIs provided in the CGIN Connectivity Pack.

Call control protocol APIs are defined as a hierarchy where each protocol API is defined as an extension of another protocol API. For example CAP v4 extends CAP v3, which extends CAP v2, which extends CAP v1.

At the root of the hierarchy is the CGIN Call Control (CGIN CC) API. CGIN CC is a synthetic call control protocol that is the intersection of ETSI INAP CS1 and CAP v4. Call control applications can be written in terms of the CGIN CC API and may be largely independent of the actual signaling protocols used.

Note The CGIN Call Control API is also generated by the CGIN toolchain. CGIN CC has its own ASN.1 description, which is why we refer to it as a synthetic protocol.
cgin apis

  • Call Control API — API for the synthetic protocol that is the intersection of INAP and CAP.

  • INAP APIs — A family of INAP APIs that are based on a common definition of ETSI INAP CS1

    • ETSI INAP CS1 (ETS 300 374-1: September 1994)

    • Please contact Metaswitch for information pertaining to INAP variants supported

  • CAP APIs — A family of CAP APIs that are based on the definition of CAP v1

    • CAP v.1 (ETSI TS 101 046 / GSM 09.78 V5.7.0 Release 1996)

    • CAP v.2 (ETSI TS 101 046 / GSM 09.78 V7.1.0 Release 1998)

    • CAP v.3 (3GPP TS 29.078 V4.8.0 Release 4)

    • CAP v.4 (3GPP TS 29.078 v9.1.1 Release 9)

  • MAP API — An API for GSM MAP.

    • Mobile Application Part (MAP) (3GPP TS 29.002 v10.0.0 Release 10)

  • IN Datatypes API — A library of classes to represent types for which their ASN.1 specification is OCTET STRING, and for which standards define the layout of bit-fields within the octet string (for example CalledPartyNumber and ISDNSubaddress).

  • X.S0004 API — An API for X.S0004-E/CDMA. Please contact Metaswitch for X.S0004/CDMA support.

Note
Learn more…​

See: CGIN APIs for javadoc of all APIs in the CGIN family.

CGIN APIs

The CGIN APIs represent an SS7 message as a POJO (Plain Old Java Object). This SS7 message POJO is only responsible for encapsulating the fields of the SS7 message it represents. Applications can therefore safely store messages in CMP fields.

The CGIN CC InitialDP, for example, is represented by the CCInitialDPArg class.

// A POJO that represents an InitialDP
public class CCInitialDPArg extends AbstractFieldsObject {

    public CalledPartyNumber getCalledPartyNumber()   { ... }
    public CallingPartyNumber getCallingPartyNumber() { ... }

    // + other methods for accessing fields of the InitialDP
}

SLEE events are represented as a separate class with an associated message POJO.

The CGIN CC InitialDP request, for example, is shown below. The CCInitialDPRequestEvent extends from the OperationInvokeEvent generic class, with a type parameter value of CCInitialDPArg. CCInitialDPArg is the POJO class that represents the InitialDP message itself.

/**
* Base class for all operation-specific invoke event classes.
* Individual protocols subclass this event for each operation they support.
* Each operation defines its own event type.
*/
public class OperationInvokeEvent<ArgType> extends OperationEvent {

    public ArgType getArgument() { return argument; }

    // ...
}

// ...

public class CCInitialDPRequestEvent extends OperationInvokeEvent<CCInitialDPArg> {

    // ...

}
Note
Restrictions imposed by the SLEE programming model

The SLEE programming model imposes some restrictions on what a SLEE application can do with an event. An important one that programmers often misunderstand (or simply forget!) is that event objects should not be stored by the service in CMPs (or by using any other method) for use in future transactions. This is simply because the event is owned by the resource adaptor and the SLEE has no knowledge of how the event object has been implemented (and therefore cannot make any assumptions in terms of persistence and so on).

Event Models

CGIN 2.0.x supports two service event models:

  • A message oriented event model, introduced in CGIN 2.0.0.

  • A component oriented event model, the sole model prior to CGIN 2.0.0.

Under the component oriented event model a received TC-BEGIN would look like the following (numbered flows are events received by the service):

  (1) --> OpenRequest components=[Invoke]
  (2) --> OperationInvoke (subclass)
  (3) --> Delimiter

Under the message oriented event model the same flow would look like:

  (1) --> DialogMessage.BEGIN components=[Invoke]

Similarly, a received TC-END in direct response to a TC-BEGIN sent would look like this under the component oriented model:

  (4) --> OpenAccept
  (5) --> OperationResult
  (6) --> Close
  (7) --> ActivityEndEvent

Under the message oriented event model the same flow looks like:

  (2) --> DialogMessage.END components=[Result]
  (3) --> ActivityEndEvent

The benefits of the new model are two-fold:

  • Less events.

  • The whole network message may be inspected easily (for example, determine if it’s a TC-CONTINUE or TC-END without having to wait for the Delimiter or Close event), which can simplify service logic in some cases.

Using the Message Oriented Event Model

In order to use the message oriented event model, services should:

  • Have event handlers for BEGIN/CONTINUE/END as required.

  • Additional handlers may be needed for OperationInvokeTimeout, UserAbort, ProviderAbort and OpenRefuse as with the component oriented event model.

  • Any initial event selector should expect a DialogMessageEvent instead of OpenRequestEvent.

See DialogMessageEvent in the CGIN APIs for further information.

Converting Existing Services to the Message Oriented Event Model

Existing services may be adapted to use the message oriented API without needing a complete rewrite. This is a quick overview of that process:

  • Create new event handlers for BEGIN/CONTINUE/END and OperationInvokeTimeout.

  • Remove the declarations for the old event handlers (sbb-jar or annotations).

  • Convert the initial event selector for OpenRequestEvent to expect a DialogMessageEvent instead.

  • In the new event handlers, iterate over the components of the DialogMessageEvent and delegate to the old event handlers as appropriate.

  • If the service cares about Delimiter or Close, synthesize calls to those event handlers after processing components, based on DialogMessageEvent.getMessageType().isLastMessage()

  • User abort, provider abort and open refuse handlers are unchanged.

  • OperationInvokeTimeout should be delegated to the provider error handler. If necessary, synthesize a Delimiter event handler call afterwards.

Previous page Next page