JAIN™, a set of Integrated Network APIs for the Java™ platform: Framework
Media Gateway Control Protocol (MGCP)
Standard Java |
|
JAIN™, a set of Integrated Network APIs for the Java™ platform, brings Service Portability and Network Convergence into the Telephony Network. JAIN encompasses a standard set of interfaces for service creation and a number of standard interfaces for service execution. The service creation interfaces allow new services to be described as JavaBeans™, which can be connected using standard graphics tools to create new services. The service execution environment includes Java interfaces to a number of telephony protocols, such as the Signaling System No. 7 ISDN User Part (ISUP) and the Media Gateway Control Protocol (MGCP). How the development of JAIN MGCP fits into overall JAIN program management is specified in Figure 1:
Figure 1. JAIN Consortium Layout
The reason we need JAIN is the technological roadblock presented by interfaces to switches, computers, and services. The problem, which is deep inside the network, is that services cannot be transported from one system to another. The JAIN specification defines an interface into the specific domain of each vendor’s SS7 stack and IP protocols, and provides a programming interface (API) to any vendor’s stack for use by application developers.
The need to define a standard API specification has become paramount as users of the telephone and the Internet demand better, coherent services. Java provides a perfect environment for developing such a standard. The Java "write once, run anywhere" philosophy promotes interoperability between JAIN MGCP stack providers, enabling Network Equipment Providers and Call Processing Software Providers to choose between JAIN MGCP vendors and to provide services compatible with any system.
A Java approach to telephony offers telephone service providers interoperability between hardware and software network elements. As a consequence, Network Equipment Providers and Call Processing Software Providers will be able to bring their true value to the market unimpeded by issues of incompatibility and lack of interoperability.
The scope of JAIN MGCP is to define a Java Application Programming Interface (API) for the Media Gateway Control Protocol. The JAIN MGCP design concept provides a high-level common interface, which supplies the functionality of all the supported variants. A specific implementation of the API can then be mapped to a specific protocol variant.
The JAIN MGCP API specification is to provide a standard portable interface for the transfer of information between Gateways, which support Voice-over-Packet and data media streams, and call control elements. The purpose of this document is to define the requirements on for the JAIN MGCP API specification. This document contains a concise list of all the requirements that need to be satisfied for public release of the JAIN MGCP API specification. It is important to note the syntax of the requirements, in that:
The deliverables of the JAIN MGCP API specification will encompass:
The RI and the CTS do not have to be delivered until the public release of the JAIN MGCP API specification.
The Participant whose Expert is chosen as Specification Lead is typically responsible for obtaining the appropriate rights to the CTS and the RI to fulfill the Java Specification Participant Agreement (JSPA).
The JAIN MGCP API specification will follow the Java language naming convention and strictly follow the functionality of the MGCP specifications used. The Java specification definition and process can be found at
http://developer.java.sun.com/developer/jcp/index.html.The purpose of the Media Gateway Control Protocol is to provide the means for Media Gateway Controllers (e.g., Call Agents) to communicate with Media Gateways. A Media Gateway terminates switched circuit network facilities (e.g., trunks, access loops), packetizes the media stream, if it is not already packetized, and delivers packets to the packet network. It performs these functions in the reverse order for media streams flowing from the packet network to the switched circuit network. A Media Gateway hosts resources that can be broadly categorized as endpoints and media resources. A Media Gateway Controller handles the registration and management of resources at the Media Gateway. The Media Gateway Controller may have the ability to authorize resource usage based on local policy.
MGCP assumes a call control architecture where the call control "intelligence" is outside the gateways and is handled by external call control elements. The information passed through the MGCP layer must be transferred between call control elements and gateways, transparently through the network.
The objective of the JAIN MGCP API specification is to specify a Java API that will provide the interfaces and classes required for an application to instantiate objects that expose and implement the JAIN MGCP API and that allow the application to interact through the API with the MGCP stack encapsulated by such objects.
An architecture that depicts the role of MGCP relative to that of other packet-based protocols (e.g., H.323, SIP, etc.) is shown in Figure 2:
Figure 2. Packet Protocol Architecture
Note: Not all of the possible types of Gateways have been shown. Only control protocols have been shown; media streams between edge devices have been omitted for sake of clarity.
MGCP is used for controlling Gateways from external call control elements called media gateway controllers or call agents. A Gateway is a network element that provides conversion between the audio signals carried on telephone circuits and data packets carried over the Internet or over other packet networks. It can also provide for the transcoding of data signals, as in the case of a Network Access Server (see below). Examples of gateways are:
An example of an MGCP interaction between a Call Agent (CA) and two residential gateways (RGWs) for setting up a voice call is shown in Table 1.
Table 1. Call Agent/Residential Gateway Voice Call Example
Calling Party User |
Calling RGW |
Call Agent |
Called RGW |
Called Party User |
|
ß Notification Request |
Notification Request à |
||||
Ack à |
ß Ack |
||||
off-hook |
|||||
Notify à |
|||||
ß Ack |
|||||
(progress) |
ß Create Connection & Notification Request |
||||
Ack à |
|||||
Create Connection à |
|||||
ß Ack |
|||||
ß Modify Connection |
|||||
Ack à |
|||||
Notification Request à |
(ring) |
||||
ß Ack |
|||||
off hook |
|||||
ß Notify |
|||||
Ack à |
|||||
Notification Request à |
|||||
ß Ack |
|||||
ß Modify Connection |
|||||
Ack à |
|||||
(connected) |
Call in Progress |
(connected) |
|||
on hook |
|||||
ß Notify |
|||||
Ack à |
|||||
ß Delete Connection |
Delete Connection à |
||||
Performance Data à |
ß Performance Data |
||||
ß Notification Request |
Notification Request à |
||||
Ack à |
ß Ack |
In this example the first command is a Notification Request, sent by the CA to both RGWs to instruct them to look for an off-hook event, and, upon detection of this event, to provide a dial tone and to start listening for DTMF digits. The RGWs immediately acknowledge the command, repeating in the acknowledgment message the transaction identifier attached to the query by the CA.
When the off-hook event is detected (at the calling RGW, in this example), the calling RGW provides dial tone to the line (the delay between off-hook and dial tone is thus minimal.) The calling RGW will start accumulating DTMF digits according to a "digit map" supplied by the CA. The digit map defines the class of strings of DTMF digits and timeout values against which the RGW will compare the string it is currently accumulating. When the RGW detects a match, or determines that no further digit accumulation could possibly generate a match, the RGW will pass either the accumulated string or an appropriate error indication to the CA in a "Notify" message. The CA immediately acknowledges that Notification.
The CA will then seize the incoming circuit, creating a connection. The "Create Connection" commands to the calling RGW also carry a notification request in which the RGW is instructed to stop collecting digits, but to continue listening for an on-hook transition. The RGW immediately acknowledges the creation of the connection, sending back the identification of the newly created connection and the session description used to receive audio data.
The CA now reserves the outgoing circuit and does so by sending a connection command to the called RGW. The Create Connection command has the same parameters as the command sent to the ingress gateway, with two differences:
The two connections are individually identified using locally significant connection identifiers that might not be globally unique. The connections are, however, bound together as components of a single call, which is identified using a globally unique call identifier. The called RGW will acknowledge the connection command, sending in the session description its own parameters such as address, ports, and RTP profile. The Call Agent will relay the information to the calling RGW, using a Modify Connection command. The RGW immediately acknowledges the modification.
At this stage, the CA has established a half-duplex transmission path. The CA must now tell the called RGW to ring the called line. The CA will send a Notification Request instructing the called RGW to look for an off-hook event, and to report it. The RGW will acknowledge the command, repeating in the acknowledgment message the transaction identifier that the Call Agent attached to the query.
When the called RGW detects the off-hook event, it sends a Notify command to the CA. The CA immediately acknowledges that notification. The CA now asks the called RGW to send a Notify command on the occurrence of an on-hook event. It does so by sending a Notification Request to the called RGW. The called RGW acknowledges that command. In parallel, the CA will send a Modify Connection command to the calling RGW, to place the connection in full-duplex mode. The calling RGW will acknowledge that command.
After some time, the CA will have to tear down the call. In our example, the called party user, who hangs up, triggers this event. The Notify command is sent to the CA. The CA acknowledges the notification. It will then send a Delete Connection command to both RGWs.
The RGWs will respond with a message that should include a "call parameters" header field. The Call Agent should now issue a new Notification Request to both RGWs to detect the next off-hook event. The RGWs will acknowledge this command. Both RGWs, at this point, are ready for the next call
Although the interactions between the RGW and the Call Agent are complex, the interface to the Calling Party or Called Party User is quite simple. Similarly, this specification and the resultant API specification only deal with the simple interface to the functions of MGCP. While the MGCP layer and the IP Network are quite complex, the API specification hides these complexities so that applications can focus on services. The MGCP API is only concerned with the application interface, not the IP implementation.
JAIN is built upon standardized Java APIs and Object technology. In Object Technology, data and programming logic are treated as objects. Unlike traditional computer programs, objects can be readily integrated into a running environment, accessed and managed remotely, and debugged and maintained in live systems by standardized interfaces, etc.
A JAIN MGCP object, or, rather, the class from which it is instantiated, can be expressed as either a traditional Java program or as a JavaBean, where a JavaBean is a reusable software component/object. An application (e.g., a Media Gateway Controller) that needs to make use of the services of an MGCP stack that is encapsulated as a JAIN MGCP object can also be expressed in either of these ways, as well.
While JAIN does not mandate that all applications must be built as JavaBeans, the design of the API specification will not preclude any application from executing as a JavaBean [5]. The unifying features of a JavaBean are explained with examples at
http://java.sun.com/beans/doc/beans.101.pdf. The main points are:The three most important features of a JavaBean are:
REQ-OM-01-01: The API specification shall adhere to the JavaBeans Model.
If the JAIN MGCP API specification is implemented using JavaBeans, it offers the advantage of using reusable objects in a plug and play fashion.
REQ-OM-02-01: The API implementation shall not be restricted to JavaBeans.
This permits the JAIN MGCP API specification to be implemented in standard Java code.
JAIN MGCP objects must conform to a specific naming convention in order to support JavaBean implementation. For a JavaBean to expose a property, i.e. within a visual tool, it must supply an access method "get" to read the property value and/or a "set" method to write the property value. These "get" and "set" methods have the following signatures:
public <PropertyType> get<PropertyName>();
public void set<PropertyName>(<PropertyType> a);
If we discover a matching pair of get<PropertyName>
and set<PropertyName> methods that take and return the same type, then we regard these methods as defining a read-write property whose name will be <propertyName>. For a Boolean property the access method "get" signature changes to:
public boolean is<PropertyName>();
REQ-NC-01-01: The API specification shall follow the JavaBean naming convention.
REQ-NC-02-01: All access methods shall throw an exception when accessing a parameter that has not previously been set or is not supported by a specific implementation.
Adherence to this requirement will provide an efficient technique for determining whether a parameter has been set or is not supported by an implementation, and for initiating a corrective action. Adherence is also consistent with Java language programming style.
The JAIN MGCP API specification can be mapped onto the Call Agent/Residential Gateway example in Table 1. This is illustrated in Figure 3.
Figure 3. JAIN MGCP Architecture
The JAIN MGCP API specification provides a Java specification for the interface that is implemented by the MGCP Objects shown in Figure 3. It also defines the Event Objects that serve as the means of passing parameters associated with a given MGCP command. Note that the terms "Listener" and "Provider," as used in Figure 3, are intended to denote the roles of the entities that are so labeled in the context of a protocol stack. In this sense, the MGCP Objects that are shown act as "Providers" of a service (the MGCP Protocol layer) to "Listeners," or users, of that service (the application, such as the Call Agent or the RGW).
The JavaBeans Event Model also plays a role in the JAIN MGCP API Specification and also employs the terms "Listener" and "Provider." In the JavaBeans Event Model, a "Provider" is the source of an Event (encapsulated as an Event Object), while a "Listener" registers with the "Provider," which invokes a method of the "Listener" when the Event occurs. A JAIN MGCP "Listener" can, in fact, create and pass Events to the JAIN MGCP Provider, as, for example, would occur when a Call Agent would send a CreateConnection Event into the MGCP stack, by invoking methods of the JAIN MGCP Provider, with the only difference being that the JAIN MGCP Provider is not registered with the JAIN MGCP Listener. In the context of the JAIN MGCP API, the terms "Listener" and "Provider" will be preceded by "JAIN MGCP" whenever these terms refer to application layer or MGCP protocol layer entities, respectively. When not so qualified, the terms may be inferred as carrying their customary JavaBeans Event Model interpretations.
The CTS and the RI will test the JAIN MGCP API specification, where the CTS is equivalent to the application and the RI is equivalent to the MGCP object implementation. It is important to note that the RI is not an emulation of an MGCP/IP stack.
The implementation of the JAIN MGCP API specification is dependent on three main entities.
REQ-ER-01-01: The API implementation shall send MGCP commands and their associated parameters between the JAIN MGCP Provider and the JAIN MGCP Listener as Events.
JAIN MGCP messages are passed between the protocol stack and the application as Event Objects. Event handling methods defined in the EventListener interface conform to a standard naming convention:
void <eventOccurrenceMethodName>(<EventStateObjectType> event);
where the <EventStateObjectType> is a subclass of java.util.EventObject.
Event Provider classes provide methods for registering and unregistering event listeners, which allow potential EventListeners to establish an event flow from that Provider to the Listener. The standard naming convention for EventListener registration is:
public void add<ListenerType>(<ListenerType> listener)
throws java.util.TooManyListenersException,
throws java.util.ListenerAlreadyRegisteredException;
REQ-ER-02-01: The API implementation shall throw a java.util.TooManyListenersException if the number of Listeners that attempt to register with a given Provider exceeds the implementation's limit on that number.
REQ-ER-03-01: The API implementation shall throw a java.util.ListenerAlreadyRegisteredException if the same Listener attempts to register more than once with a given Provider.
The current architecture of MGCP makes it unlikely that more than one Listener would act on a single MGCP Event Object, so the API should preclude more than one Listener from registering on a given Provider. Note that no requirement is placed on the Listener to catch the exception that may be thrown.
The signature for removal of a Listener for a given Event Object on a given Provider is:
public void remove<ListenerType>(<ListenerType> listener);
throws java.util.ListenerNotRegisteredException;
REQ-ER-04-01: The API implementation shall throw an MGCPException with the error message "Listener is not registered" if the Listener is not registered for the given Event with the given Provider.
An overview of the JAIN MGCP Event Processing model is illustrated in Figure 4.
Figure 4. An overview of the JavaBean™ Event model
Invoking the
add<ListenerType> method adds the given listener to the set of Event Listeners registered for events associated with the <ListenerType>. Based on REQ-ER-02-01, the set of Event Listeners is at most a singleton. Similarly invoking the remove<ListenerType> method removes the given Listener from the set of Event Listeners registered for Events associated with the <ListenerType>.The error handling of the possible exceptions are all specific to the implementation of the JAIN MGCP specification, for example:
JAIN MGCP Events, which are encapsulated MGCP messages, contain both input parameters provided to the Listener by the Provider and output parameters returned by the Listener to the Provider.
REQ-ER-05-01: The API implementation shall invoke an MGCP command by passing an Event Object, which corresponds to the command, from the invoking entity (the JAIN MGCP Provider or the JAIN MGCP Listener) to the corresponding method of the JAIN MGCP Listener or JAIN MGCP Provider that processes the command.
REQ-ER-06-01: The API implementation shall provide methods defined on each Event Object for accessing both input and output parameters encapsulated within the Event Object.
This will provide MGCP message passing from object to object, by following the JavaBeans event model.
The implementation of the JAIN MGCP Provider interface provides a vendor-specific MGCP stack with the ability to communicate with a JAIN MGCP Listener implemented in an application (e.g., a Call Agent or Residential Gateway).
REQ-PR-01-01: At most one JAIN MGCP Provider shall be bound to a given MGCP stack at any time.
Since MGCP messaging is inherently unicast, binding more than one JAIN MGCP Provider to a given MGCP stack would not be useful.
Within Java, a Peer is a platform-specific implementation of a Java Interface or API; therefore, a JAIN MGCP Provider Peer is a vendor-specific implementation of the JAIN MGCP Provider Interface.
REQ-PR-03-01: The API specification shall provide a common interface to access JAIN MGCP Provider peers.
This will ensure that additional JAIN MGCP Provider peer functionality is hidden from the JAIN MGCP Listener implementation, as well as providing a common method of instantiating JAIN MGCP Provider objects. A common Object-Oriented design pattern used to handle this in other API's, e.g., JTAPI, is the Peer Factory.
REQ-LR-01-01: A JAIN MGCP Listener shall be able to register with any JAIN MGCP Provider.
This ensures that all JAIN MGCP Listeners are portable over all JAIN MGCP Providers, which is a fundamental requirement of the Java programming language i.e. "write-once, run-anywhere."
REQ-LR-02-01: A JAIN MGCP Listener shall return the same Event Object that was passed to it by a JAIN MGCP Provider, having used the Event Object’s accessor methods to populate some or all of the return parameters defined for the Event Object.
REQ-LR-03-01: A JAIN MGCP Listener shall register with a JAIN MGCP Provider to receive MGCP messages from that Provider by using the addListener method defined by that Provider.
A generic set of primitives shall be created that abstracts the functionality of the primitives of the supported variants (e.g., MGCP, SGCP, NCS, MEGACO).
REQ-GP-01-01: The API shall incorporate a common set of primitives that will map to protocol variant information.
This provides a higher level of abstraction within the API. The MGCP RFC and the PacketCable™ NCS Protocol Specification will serve as the source documents for the analysis of the common set of primitives.
REQ-GP-02-01: The API shall treat all primitives that are not common to all protocol variants as optional.
REQ-EI-01-01: The API specification shall be compatible with the Java Platform v1.2.2 Core API Specification or later.
The added features of the Java Platform v1.2.2 can be viewed at http://java.sun.com/products/jdk/1.2/docs/index.html.
REQ-RR-01-01: In order to execute the JAIN MGCP Compatibility Test Suite, or a JAIN MGCP application, the following shall be required:
The acceptance test requirements are outlined in the Java Community Process (see http://developer.java.sun.com/developer/jcp/index.html). The main Acceptance Test Requirements specified within the document include:
REQ-DC-01-01: The documentation shall be presented in HTML format.
The documentation supporting the API needs to be supplied with and in the same format as the API (HTML).
REQ-PO-01-01: A JAIN MGCP implementation shall be considered compliant if a JAIN MGCP application can run unchanged on both the JAIN MGCP implementation and the JAIN MGCP Reference Implementation.
The main aim of the JAIN MGCP process is to provide portable JAIN MGCP applications that will run over any MGCP stack that is JAIN-compliant.
REQ-QR-01-01: The JAIN MGCP API development shall follow the Java Community Process.
The Java Community Process is Sun Microsystems’s process for developing API’s (see http://developer.java.sun.com/developer/jcp/index.html).
The maintainability requirements are outlined in the Java Community Process (see http://developer.java.sun.com/developer/jcp/index.html). The main Maintainability Requirements within this document include:
REQ-CR-01-01: A JAIN MGCP Implementation shall be compatible after passing the CTS.
This will ensure that all JAIN MGCP implementations can be tested to guarantee JAIN compliance. An implementation of the JAIN MGCP specification will only be JAIN compliant if it passes the CTS. An acceptable standard will be set by the JAIN MGCP Expert group, which will be used as a guideline with the CTS and which JAIN MGCP implementations must pass in order to be compliant.
The specification deliverables are outlined in the Java Community Process (see http://developer.java.sun.com/developer/jcp/index.html). The main Specification Deliverables Requirements within this document include:
![]() Phelim O’Doherty |
![]() Dinesh Lokhande |
![]() Steve Mayer |
![]() Douglas Tait |
![]() Vito Jokubaitis Barry Hoffner Stan Moyer |
![]() Steve Davis Jeff Fitzgerald Arkady Grinberg |
JAIN Contact:
Douglas Tait, Sun Microsystems, Inc.
JAIN MGCP Edit Lead:
Vito P. Jokubaitis, Telcordia Technologies, Inc.
Document ID: |
RQS-JAINMGCP-001 |
Version: |
1.0 |
Location: |
Telcordia |
Originator |
Vito P. Jokubaitis |
Approval Date: |
|
Status: |
Final |
Approver: |
JAIN MGCP Edit Group |
This document outlines the requirements specified by the JAIN MGCP Edit group as a guideline for the public release of the JAIN MGCP specification.
JAIN MGCP Edit Group
Version |
Modified By |
Date |
Description |
0.1 |
Stanley Moyer |
07/27/99 |
Rough Draft |
1.0 |
Vito P. Jokubaitis |
11/03/00 |
Final Draft (Corrections to REQ-ER-02-01, REQ-ER-03-01, REQ-ER-04-01. Removed REQ-PR-02-01. Corrected second item under "Constraints, Assumptions, and Dependencies." |
Copyright © 1999,2000 Telcordia Technologies Inc.
TELCORDIA TECHNOLOGIES, INC. and JAIN JSPA SIGNATORIES PROPRIETARY
This document contains proprietary information that shall be distributed, routed or made available only within Telcordia Technologies, Inc. and JAIN JSPA Signatory Companies, except with written permission of Telcordia Technologies, Inc.