jain_mgcp_req_revmarked

Document Sample
jain_mgcp_req_revmarked Powered By Docstoc
					Java API's for the Integrated Network (JAIN)
                 Framework
  Media Gateway Control Protocol (MGCP)




Standard Java                         API's for the
Interface into MGCP                   Integrated
                                      Network




                      1
                                                         Table of Contents
1. OBJECTIVES AND SCOPE ................................................................................................................... 3
     1.1. JAIN MGCP API SPECIFICATION......................................................................................................... 4
2. INTRODUCTION .................................................................................................................................... 5
     2.1. SYSTEM OVERVIEW .............................................................................................................................. 6
3. REQUIREMENTS DEFINITION .......................................................................................................... 9
     3.1. THE JAIN MGCP OBJECT MODEL ....................................................................................................... 9
     3.2. JAIN MGCP NAMING CONVENTION .................................................................................................... 9
     3.3. JAIN MGCP ARCHITECTURE ..............................................................................................................10
        3.3.1. Event Requirements .....................................................................................................................11
            3.3.1.1. JAIN MGCP Event Processing ............................................................................................................. 11
            3.3.1.2. JAIN MGCP Events.............................................................................................................................. 12
        3.3.2. JAIN MGCP Provider requirements............................................................................................13
            3.3.2.1. JAIN MGCP Provider Peer Requirements ............................................................................................ 13
        3.3.3. JAIN MGCP Listener Requirements ............................................................................................13
            3.3.3.1. JAIN MGCP Listener Events ................................................................................................................ 13
            3.3.3.2. JAIN MGCP Listener Registration ....................................................................................................... 14
     3.4. GENERIC PRIMITIVES ...........................................................................................................................14
4. EXTERNAL REQUIREMENTS ...........................................................................................................14
     4.1. PERFORMANCE REQUIREMENTS ..........................................................................................................14
     4.2. EXTERNAL INTERFACES.......................................................................................................................14
     4.3. RESOURCE REQUIREMENTS .................................................................................................................14
     4.4. ACCEPTANCE TEST ISSUES .............................................................................................................14
     4.5. DOCUMENTATION REQUIREMENTS .................................................................................................14
     4.6. PORTABILITY REQUIREMENTS ........................................................................................................15
     4.7. QUALITY REQUIREMENTS ..............................................................................................................15
     4.8. MAINTAINABILITY ISSUES ..............................................................................................................15
     4.9. COMPATIBILITY REQUIREMENTS ....................................................................................................15
     4.10.     SPECIFICATION DELIVERABLES ..................................................................................................15
     4.11.     CONSTRAINTS, ASSUMPTIONS AND DEPENDENCIES ...................................................................15
5.      APPENDIX I — REFERENCES .......................................................................................................16

6.      APPENDIX II — ABBREVIATIONS AND DEFINITIONS ..........................................................16
     6.1.      ABBREVIATIONS .............................................................................................................................16
     6.2.      TERMS ............................................................................................................................................17
7.      APPENDIX III — FIGURES AND TABLES ...................................................................................17

8.      APPENDIX IV — EXAMPLE ...........................................................................................................17

9.      APPENDIX V — MGCP EDIT GROUP EXPERTS .......................................................................17

10.         APPENDIX VI — DOCUMENT INFORMATION .....................................................................18
     10.1.         CONTROL ...................................................................................................................................18
     10.2.         ABSTRACT ..................................................................................................................................18
     10.3.         DISTRIBUTION ............................................................................................................................18
     10.4.         HISTORY .....................................................................................................................................18




                                                                                  2
1. Objectives and Scope
Java™ API's for the Integrated Network (JAIN™) Framework 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:
                                        JAIN Program Management
                                             (John de Keijzer)



      JAIN Protocol Expert Group      JAIN Application Expert Groups          JAIN Workgroups
            (Douglas Tait)                   (Rob Goedman)                    (Workgroup Lead)



             TCAP Edit Group                JAIN SLEE Edit Group                     Tarzan
              (Colm Hayden)                   (Shmuel Kallner)                  (France Telecom)
                                             (Dinesh Lokhande)

              ISUP Edit Group                JAIN CC Edit Group                      Others
             (In-Sheng Cheng)                    (Ravi Jain)



             OAM Edit Group                 JAIN Parlay Edit Group
             (Colm Hayden)                    (Simmon Beddus)



             MAP Edit Group                  JAIN CM Edit Group
             (Mikael Larsson)                  (Pramila Mullan)



              SIP Edit Group
              (Steve Mayer)



             MGCP Edit Group
             (Vito Jokubaitis)



             H.323 Edit Group
              (Ravi Raj Bhat)



                                   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




                                                    3
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.
This document is laid out in the following format:
        Chapter 1 – Objectives and Scope: This chapter provides an insight to JAIN, why we need JAIN,
         and what needs to be achieved in order to provide JAIN MGCP.
        Chapter 2 – Introduction: This chapter provides an introduction to the Media Gateway Control
         Protocol, how it operates, and how its operation can be mapped logically to the real world.
        Chapter 3 – Requirements Definition: This chapter defines the requirements necessary to develop
         version 1.0 of the JAIN MGCP API. Each requirement is stated succinctly, followed by an
         explanatory statement that provides any additional information that may be needed for full
         understanding of the requirement.
        Chapter 4 – External Requirements: This chapter outlines the requirements that don‟t directly
         affect an implementation of the JAIN MGCP API, but that may affect the development of the API.
        Chapter 5 – Appendix I: This chapter lists the reference materials that are cited throughout this
         document.
        Chapter 6 – Appendix II: This chapter lists the abbreviations used throughout the document, as
         well as any terms that may need additional explanation.
        Chapter 7 – Appendix III: This chapter lists the figures and tables that appear in this document.
        Chapter 8 – Appendix IV: An example of … [Editor‟s note: We can probably dispense with this
         appendix, renumbering the remaining chapters and appendix designations, unless someone
         suggests an interesting use of MGCP that isn‟t already addressed in the introductory material.]
        Chapter 9 – Appendix V: This chapter provides a brief summary of the partner companies
         involved in the development of version 1.0 of the JAIN MGCP API.
        Chapter 10 – Appendix VI: This chapter outlines the control, distribution, and history of this
         document.
        Chapter 11 – Change Log: This chapter is used to document any changes that may be incorporated
         into this document after it has been approved.

1.1. JAIN MGCP API Specification
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:
        If the wording of a specific requirement includes „shall‟ then the incorporation of this requirement
         in the JAIN MGCP API specification is mandatory.
        If the wording of a specific requirement includes „should‟ then the incorporation of this
         requirement in the JAIN MGCP API specification is strongly recommended, but is not mandatory.
The deliverables of the JAIN MGCP API specification will encompass:




                                                      4
        A Java API specification, which will define a common interface for accessing the functionality of
         proprietary implementations of the MGCP.
        The Reference Implementation is the "proof of concept" implementation of the Specification. The
         RI will emulate or simulate the functions of an MGCP stack in order to verify the requirements in
         this specification. The intention of the RI is not to implement an MGCP stack or to replace vendor
         MGCP stacks. The purpose of the RI is to provide a means for demonstrating that a Java
         application written to the JAIN MGCP API specification is compatible with that specification.
        The Compatibility Test Suite (CTS) tests the implementation of JAIN interfaces for compliance to
         the JAIN MGCP Specification. The purpose of the JAIN CTS is to verify that a Java MGCP
         protocol implementation is compatible to the JAIN MGCP API Specification.
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.

2. Introduction
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:




                                                      5
                                 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.

2.1. System Overview
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:
   Trunking gateways, which interface between the telephone network and a Voice-over-Packet network.
    Such gateways typically manage a large number of digital circuits.
   Voice-over-ATM gateways, which operate much the same way as Voice-over-Packet trunking
    gateways, except that these interface to an Asynchronous Transfer Mode (ATM) network.
   Residential gateways, which provide a traditional analog (RJ11) interface to a Voice-over-Packet
    network. Examples of residential gateways include cable modem/cable set-top boxes, Digital
    Subscriber Line (xDSL) devices, and broadband wireless devices.
   Access gateways, which provide a traditional analog (RJ11) or a digital PBX interface to a Voice-over-
    Packet network. Examples of access gateways include small-scale Voice-over-Packet gateways.
   Business gateways, which provide a traditional digital PBX interface or an integrated "soft PBX"
    interface to a Voice-over-Packet network.
   Network Access Servers (NASs), which can attach a "modem" to a telephone circuit and thus provide
    data access to the Internet. We expect that, in the future, the same gateways will combine Voice-over-
    Packet services and Network Access services.
   Circuit switches, or packet switches, which can offer a control interface to an external call control
    element.
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.



                                                      6
                      Table 1. Call Agent/Residential Gateway Voice Call Example

 Calling           Calling RGW                  Call Agent               Called RGW           Called Party
Party User                                                                                        User
                        Notification Request                 Notification Request 
                                Ack                                    Ack
  off-hook
 (Dial-tone)
  dial digits
                               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.



                                                       7
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 EndpointId points towards the calling RGW,
            The message carries the session description returned by the calling RGW,
            The “mode” of the connection is set to “send/receive” because the session description is
             present.
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.




                                                      8
3. Requirements Definition

3.1. The JAIN MGCP Object Model
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:
        Introspection: Can be used by an application builder tool to discover the properties, methods and
         events of a JAIN MGCP object.
        Customization: Allows an operator to dynamically change the properties of a JAIN MGCP object
         at run time using an application builder tool.
        Events: Can be used as the vehicle for bidirectional communication between an application and a
         JAIN MGCP object, so that the invocation of an MGCP command can be accomplished by the
         passing of an event object between the application and the JAIN MGCP object that will perform
         the command.
        Persistence: Allows the state of a JAIN MGCP object to be stored for retrieval at a later time.
The three most important features of a JavaBean are:
        Property Management: Properties are named attributes associated with a bean that can be read or
         written by calling appropriate methods on the bean.
        Method Management: A JavaBean exports both standard and extended Java methods, which can
         be called from other objects or from a scripting environment, such as HTML invoking an applet.
         By default, all of the bean's public methods will be exported.
        State Management: Events provide a way for one object to notify other objects that a change in
         state has occurred. Under the Java event model, an event listener object can be registered with an
         event source. When the event source detects a state change, it will call the appropriate method on
         the event listener object.
REQ-OM-01-01: The API specification shall adhere to the JavaBeans Model. [5]
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.

3.2. JAIN MGCP Naming Convention
JAIN MGCP objects must conform to a specific naming convention in order to support JavaBean
implementation. [5] 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:



                                                       9
         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. [5]
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.

3.3. JAIN MGCP Architecture
The JAIN MGCP API specification can be mapped onto the Call Agent/Residential Gateway example of
section 2.1. This is illustrated in Figure 3.




                  Event                                                             Event
                 Objects                                                           Objects
                                   MGCP         MGCP         MGCP
                                   Object       Stack        Object




      Call        JAIN             JAIN                      JAIN             JAIN
                  MGCP             MGCP                      MGCP             MGCP           RGW
     Agent        “Listener”       “Provider”                “Provider”       “Listener”




                    CTS              RI                        RI                CTS


            Scope of JAIN MGCP AP I Specification


                                  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



                                                     10
(encapsulated as an Event Object), while a “Listener” registers a method with the “Provider” that is to be
called when the Event occurs. A JAIN MGCP “Listener” can, in fact, act as a “Provider” of an Event to a
“Listener” method that is exposed by a JAIN MGCP “Provider,” as, for example, would occur when a Call
Agent would send a CreateConnection Event into the MGCP stack. This “overloading” of the terms
“Listener” and “Provider,” while a source of potential confusion, is nevertheless based on precedent in the
JAIN effort. To mitigate confusion, when used 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.
        JAIN MGCP Events: - Within the API, MGCP messages are encapsulated as JAIN MGCP Event
         Objects that are passed between the JAIN MGCP Provider and the JAIN MGCP Listener.
        JAIN MGCP Provider: - Within the API, the JAIN MGCP Provider is defined as the entity that
         provides an application access to the services of the MGCP stack. The JAIN MGCP Provider acts
         as the source of a JAIN MGCP Event Object when it receives a request made by a remote
         application. The request‟s parameters are encapsulated in an Event Object and passed to the JAIN
         MGCP Listener. The JAIN MGCP Provider acts as a sink for a JAIN MGCP Event Object when
         the application that the JAIN MGCP Provider services needs to send an MGCP request to a
         remote application.
        JAIN MGCP Listener: - Within the API, the JAIN MGCP Listener is defined as the entity that
         uses the services provided by the JAIN MGCP Provider.
Thus, the JAIN MGCP API must provide definitions for Listener interfaces for all the MGCP commands,
for all the Event Objects that correspond to these MGCP commands, and for the means for Listeners to
register with corresponding Providers.

3.3.1. Event Requirements

3.3.1.1. JAIN MGCP Event Processing

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 MGCPException;
REQ-ER-02-01: The API implementation shall send throw an MGCPException with the error message
“More than one Listener attempted to register” if more than one Listener attempts to register for a given
Event with a given Provider.




                                                     11
REQ-ER-03-01: The API implementation shall send throw an MGCPException with the error message
“Same Listener attempted to register more than once” if the same Listener attempts to register more
than once for a given Event 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 MGCPException;
REQ-ER-04-01: The API implementation shall send 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.


                       JAIN MGCP Listener

                                                                         Register
                   Fire JA IN         JAIN                               JAIN MGCP
                 MGCP E vent          MGCP                               Listener
                                      Event

                                                            JAIN MGCP Provider

                         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:
        Adding the same JAIN MGCP Listener more than once to the same JAIN MGCP Provider.
        Removing a JAIN MGCP Listener more than once from the same JAIN MGCP Provider.
        Removing a JAIN MGCP Listener that is not registered with a JAIN MGCP Provider.
        Adding more JAIN MGCP Listeners than a JAIN MGCP Provider can handle.

3.3.1.2. JAIN MGCP Events

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 Provider) to the registered Listener
method 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.




                                                     12
This will provide MGCP message passing from object to object, by following the JavaBeans event model.
[Reference 6]

3.3.2. JAIN MGCP Provider requirements
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 port at any time.
Since MGCP messaging is inherently unicast, permitting more than one JAIN MGCP Provider on a given
MGCP port would not be useful.
REQ-PR-02-01: The JAIN MGCP Provider shall pass an Event to at most one registered JAIN MGCP
Listener.
See REQ-ER-03-01. Since at most one Listener shall be registered with a given Provider, violation of this
requirement would signify a serious implementation error.
REQ-PR-03-01: The JAIN MGCP Provider shall register exactly one Listener method for each type of
Event that a JAIN MGCP Listener wishes to pass to it.
An attempt to register more than one such method would violate REQ-ER-03-01. Failure to register at
least one such method would mean that a JAIN MGCP Listener would have no sink for a JAIN MGCP
Event Object it wished to pass to the MGCP stack via a JAIN MGCP Provider.
REQ-PR-04-01: The JAIN MGCP Provider shall not return from processing an Event passed to it by a
JAIN MGCP Listener until it has received a response from the remote application to which the Event is
directed.
Under some circumstances, the JAIN MGCP Provider will never return; e.g., no Listener is registered by
the remote application for processing a given Event. It is expected that a JAIN MGCP Listener will start a
timer when sending an Event to a JAIN MGCP Provider and will take appropriate action should the timer
expire.

3.3.2.1. JAIN MGCP Provider Peer Requirements

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-Error! Bookmark not defined.Error! Bookmark not defined.-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.

3.3.3. JAIN MGCP Listener Requirements
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.”

3.3.3.1. JAIN MGCP Listener Events

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.



                                                    13
3.3.3.2. JAIN MGCP Listener Registration

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.

3.4. Generic Primitives
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.
REQ-GP-02-01: The API shall treat all primitives that are not common to all protocol variants as
optional.

4. External Requirements

4.1. External Interfaces
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 new Java Platform v1.2.2 can be viewed at [correct URL needs to be provided].

4.2. Resource Requirements
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 JAIN MGCP API is implemented over a JAIN compliant protocol stack or over the
         Reference Implementation.
        A Java Virtual Machine

4.4.      Acceptance Test Issues
The acceptance test requirements are outlined in the Java Community Process. See [1] or view at
http://developer.java.sun.com/developer/jcp/index.html. The main Acceptance Test Requirements specified
within the document include:
        The API specification will be acceptable to the majority of participants of the JAIN MGCP expert
         group and the Process Management Office (Sun Microsystems).
        All public comments as a result of a public review shall be read, considered, documented and, if
         necessary, incorporated into a new review of the API specification.
        API deficiencies shall be documented and made available to Sun Microsystems.

4.5.      Documentation Requirements
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).




                                                      14
4.6.     Portability Requirements
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.

4.7.     Quality Requirements
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 [1] or view at
http://developer.java.sun.com/developer/jcp/index.html.

4.8.     Maintainability Issues
The maintainability requirements are outlined in the Java Community Process. See [1] or view at
[http://developer.java.sun.com/developer/jcp/index.html]. The main Maintainability Requirements within
this document include:
       The Interpretation Guru shall be responsible for ongoing maintenance in response to requests such
        as clarification, interpretation, enhancements and change requests by participants and the public.
       A change log should be made available via a public web site that lists all revisions made to the
        specification by the Interpretation Guru during maintenance.

4.9.     Compatibility Requirements
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.

4.10.    Specification Deliverables
The specification deliverables are outlined in the Java Community Process. See [1] or view at
http://developer.java.sun.com/developer/jcp/index.html. The main Specification Deliverables Requirements
within this document include:
       A Java API specification shall be specified for JAIN MGCP.
       A Reference Implementation shall be developed to uncover areas of the API that are under-
        defined, incomplete or ambiguous.
       A Compatibility Test Suite shall be developed to ensure JAIN MGCP specification compatibility.
       A User Guide shall be developed for the JAIN MGCP specification. This will provide an overview
        of the JAIN MGCP specification, a detailed description of the API and how its implementation
        can produce portable MGCP applications.

4.11.    Constraints, Assumptions and Dependencies
       This API specification will not be dependent on any other JAIN API specification, however it will
        be compatible with the JAIN OAM API. The JAIN OAM API may handle the provisioning and
        management of the JAIN MGCP API depending on the vendor‟s implementation of the API. The
        JAIN OAM specification is the interface for the service provider to provision the network.


                                                    15
          Transmissions rates, hardware characteristics, routing configurations, etc. are all covered by the
          JAIN OAM specification.
         The API specification shall require that any Provider-Listener pairing reside on the same Java
          Virtual Machine. [Barry Hoffner to provide rationale.]

         The API specification shall provide the ability to reuse previously instantiated objects. This offers
          the capability of keeping object instantiation to a minimum, therefore maximizing performance.

5. APPENDIX I — References
[1] Sun Microsystems Open Process for Developing and Revising Java Specifications (Version 1.0,
    December 1998), Java Software, Sun Microsystems, Inc.,
    http://developer.java.sun.com/developer/jcp/index.html.
[2] Internet Draft, Media Gateway Control Protocol (MGCP), <draft-huitema-megaco-mgcp-v0r1-05.txt>,
    February 21, 1999.
[3] Internet Draft, Media Gateway Control Protocol Architecture and Requirements, <draft-ietf-megaco-
    reqs-00.txt>, January 27, 1999.
[4]
[5] JavaBeans API Specification (v1.01)

6. APPENDIX II — Abbreviations and Definitions

6.1.       Abbreviations
      ANSI - American National Standards Institute
      API - Application Programming Interface
      ASN.1 - Abstract Syntax Notation 1
      CTS - Compatibility Test Suite
      HTML - HyperText Mark-up Language
      IN - Intelligent Network
      ITU - International Telecommunications Union
      JAIN - Java API for Integrated Networks
      JTAPI - Java Telephony Application Programming Interface
      P&M - Provisioning and Management
      QMS - Quality Management System
      RI - Reference Implementation
      SS7 - Signaling System 7
      MGCP - Media Gateway Control Protocol
      IETF - Internet Engineering Task Force
      IP - Internet Protocol
      TCP - Transmission Control Protocol
      UDP - User Datagram Protocol
      SDP - Session Description Protocol


                                                       16
6.2.        Terms
Common Interface: - An Interface that defines a common fully functional set of methods from a specified
group of protocol variants.
Interpretation Guru: - The expert that handles the maintenance of the specification.
Listener Interface: - The Listener Interface is the Java Listener interface specified in the JAIN MGCP API.
Peer: - A particular platform specific implementation of a Java interface or API.
Provider Peer: - The Provider Peer is the stack vendor specific implementation of the Provider Interface.
Provider Interface: - The Provider Interface is the Java Provider interface specified in the JAIN MGCP
API.
Shall: - Within the Requirements Chapter 3, if the wording of a specific requirement includes „shall‟ then
the incorporation of this requirement in the JAIN MGCP specification is mandatory.
Should: - Within the Requirements Chapter 3, if the wording of a specific requirement includes „should‟
then the incorporation of this requirement in the JAIN MGCP specification is strongly recommended but is
not mandatory.
Specification Lead: - The expert responsible for writing the specification with input from the other experts,
and hence responsible for developing consensus within the group. This person shall possess strong
diplomatic and writing skills as well as technical expertise.
MGCP_User: - Any User of the Media Gateway Control Protocol.

7. APPENDIX III — Figures and Tables
FIGURE 1. JAIN CONSORTIUM LAYOUT .......................................................................................................... 3
FIGURE 2. PACKET PROTOCOL ARCHITECTURE ............................................................................................... 6
FIGURE 3. JAIN MGCP ARCHITECTURE ........ERROR! BOOKMARK NOT DEFINED.ERROR! BOOKMARK NOT
    DEFINED.
FIGURE 4. AN OVERVIEW OF THE JAVABEAN™ EVENT MODEL......................................................................12
FIGURE 5. A POSSIBLE SOLUTION OF A DISTRIBUTED JAIN MGCP IMPLEMENTATION .................................16

TABLE 1. CALL AGENT/RESIDENTIAL GATEWAY VOICE CALL EXAMPLE ....................................................... 7



8. APPENDIX IV — Example

9. APPENDIX V — MGCP Edit Group Experts
                                                                                                                            Sang Lee
                                                                                                                           Steve Mayer


                                     Douglas Tait                                 Ravi Raj Bhat
Keiichi Sasaki                                                                                                            Steve Davis
                                                                               JAIN Contact:                             Jeff Fitzgerald
                                                                          douglas.tait@east.sun.com                     Arkady Grinberg
                                                                        JAIN MGCP Edit Lead:
                                                                    vjokubaitis@research.telcordia.com
                                   Vito Jokubaitis
                                   Barry Hoffner



                                                                    17
                            Stan Moyer

10.        APPENDIX VI — Document Information

10.1.       Control
 Document ID:              RQS-JAINMGCP-001

 Version:                  0.1

 Location:                 Telcordia

 Originator                Stanley Moyer

 Approval Date:

 Status:                   Draft

 Approver:                 JAIN MGCP Edit Group

10.2.       Abstract
This document outlines the requirements specified by the JAIN MGCP Edit group as a guideline for the
public release of the JAIN MGCP specification.

10.3.       Distribution
JAIN MGCP Edit Group

10.4.       History
 Version                    Modified By                    Date            Description

 0.1                        Stanley Moyer                  07/27/99        Rough Draft




                                                  18

				
DOCUMENT INFO
Shared By:
Categories:
Tags:
Stats:
views:6
posted:7/12/2011
language:English
pages:18