| Date post: | 25-Oct-2014 |
| Category: |
Documents |
| Upload: | genesysnice |
| View: | 40 times |
| Download: | 5 times |
An Introduction to theJava Telephony API (JTAPI)
Marcel Graf
Marcel Graf/Zurich/IBM@IBMCHIBM Research DivisionZurich Research Lab
March 2000
1 / 22/g/ct/website/internal-2.0/src/jtapi-tutorial.fmlast modified April 3, 2000 2:38 pm22 pages
n ahislica-
ofrol.-n
s.sys-eral
1 Java Telephony API (JTAPI)
1.1 Scope
The Java Telephony API (JTAPI) is an object-orientedapplication programming interface for Java-based telephonyapplications. Similar APIs for other platforms are the Tele-phony API (TAPI) for the Microsoft Windows platform and theTSAPI for the Novell Netware platform.
1.2 JTAPI basics
1.2.1 First party vs. third party call control
The purpose of JTAPI is to serve as an interface betweeJava application and a telephone system. The point where tinterface is located determines the degree of control an apption has. In a first-party call control scenario the interface islocated at a terminal. The application has the same degree control a normal telephone user has. In a third-party call contscenario the interface is located inside the telephone systemDepending on the telephone system this internal access provides the application usually with more control capabilities thaa first-party call control scenario.
A design goal of JTAPI has been to cover both scenarioAs a consequence JTAPI provides a model of the telephonetem and of telephone calls that corresponds to the more genthird-party view, even when JTAPI is used for first-party call
Figure 1: First-party and third-party call control in a Private Tele-phone Network with a PBX
JTAPIfirst-party call control
JTAPIthird-party call control
appl.
appl.
2 / 22
the
thete
ll
s. ofts
.
a
ect.-ct
eso-
control. A third-party view of a call does not distinguishbetween the local end and the remote end of a call. Insteadtwo ends are symmetrical.
1.2.2 The JTAPI call model
1.2.2.1 Principles
Underlying the design of JTAPI is acall model which is ahigh-level, technology independent abstraction. It describescall as a set of finite state machines (FSM) that undergo statransitions as the call evolves.
The call model is very general to cover many different cascenarios. It is able to describe for example
• A call between two parties,• Multiple simultaneous calls on the same terminal,• A conference between multiple parties,• A call setup that alerts multiple terminals.
The call model describes the call as well as the call partieAltogether it defines five base classes (in the general senseobject types). Two classes describe call parties. Their objecare persistent and independent of calls:
• A user is represented by anAddress object. The main attributeof the Address object is the user identifier.
• A telephone terminal is represented by aTerminal object. Themain attribute of the Terminal object is the terminal address
The three other classes describe a call. Their objectinstances are not persistent, but created dynamically duringcall. Each includes a finite state machine:
• A Call object is created for each call.• A Connectionobject is created for each user participating in th
call. It connects the user’s Address object with the Call obje• A TerminalConnection object is created for each terminal par
ticipating in the call. It connects the terminal’s Terminal objewith the Connection object.
1.2.2.2 Sample call configurations
This section presents selected call configuration examplwhich help to explain the call model. It starts with a basic twparty call and then extends the example with another call,another terminal and another user.
3 / 22
antwith
ntsalhed
s-
ce
l.l isc-
Two-party call
An example of a call with two participants is shown inFigure 2. For novices it may be surprising that in this simplecase there are two Connection objects attached to the Callobject, one for each participant. This representation is importfor the seamless extension to the case of a conference call three or more parties, which is shown in a different examplefurther down. One should note that the model is completelysymmetric (it does not distinguish between local and remoteentities) because it provides a third-party view.
Two simultaneous calls
An example of a user who has two simultaneous calls othe same terminal is shown in Figure 3. All call-related objechave doubled their number. The Address object and Terminobject of the user who has two calls exist once but are attacto two Connection and TerminalConnection objects.
Call setup with two alerting terminals
An example of a two-party call with two alerting terminalis shown in Figure 4. It motivates the separation of TerminalConnection objects from Connection objects. In the exampleBob has multiline appearance, that means that when Bob iscalled, several terminals are ringing. The multiline appearanis represented by the two TerminalConnection objects thatattach to the Connection object of Bob, one for each terminaWhen one of the terminals answers the call the other terminadisconnected (in terms of the call model the TerminalConnetion object goes into a disabled state).
Figure 2: Call model for two-party call
Call
Cnx
Addr
TrmTrmCnx
Addr
Cnx TrmCnx Trm
b205.ibm.com s131.ibm.com [email protected]
b205.ibm.com
s131.ibm.com
4 / 22
s
Three-party call
An example of a conference call with three participants ishown in Figure 5. It motivates the separation of Connectionobjects from Call objects. The call model turns out to be astraightforward extension of the basic call with two partici-pants. The model simply adds a third leg with Connection,Address, TerminalConnection and Terminal objects for thethird participant.
Figure 3: Call model for two simultaneous calls
Figure 4: Call model for two alerting terminals
Call
Cnx
Addr
TrmTrmCnx
Addr
Cnx TrmCnx Trm
[email protected] b205.ibm.com
s131.ibm.com [email protected]
h101.ibm.com [email protected]
b205.ibm.com
s131.ibm.com
h101.ibm.com
Call
Cnx TrmCnx
Addr
Cnx TrmCnx Trm
Call
Cnx
Addr
TrmTrmCnx
Addr
TrmCnx Trm
[email protected] b205.ibm.com
s131.ibm.com
s145.ibm.com
b205.ibm.com
s131.ibm.com
TrmCnx Trm
Cnx
s145.ibm.com
5 / 22
1.2.2.3 Finite state machines
This section describes the call-related objects and theirfinite state machines in more detail.
Figure 5: Call model for three-party call
Addr
Cnx TrmCnx Trm h101.ibm.com
Call
Cnx
Addr
TrmTrmCnx
Addr
Cnx TrmCnx Trm
b205.ibm.com s131.ibm.com [email protected]
b205.ibm.com
s131.ibm.com
h101.ibm.com [email protected]
6 / 22
ll
Call object
A Call object is created for each call. The state of the Caobject depends on the number of Connection objects.
Figure 6: Finite state machine: Call object
IDLE This is the initial state for all Calls. In this state, the Callhas zero Connections.
ACTIVE A Call with some current ongoing activity is in thisstate. Calls with one or more associated Connectionsmust be in this state.
INVALID This is the final state for all Calls. Call objects whichlose all of their Connections objects (via a transition ofthe Connection object into the Connection.DISCON-NECTED state) moves into this state. Calls in this statehave zero Connections and these Call objects may notbe used for any future action.
IDLE
ACTIVE
INVALID
initial state
Call
Call
Call
7 / 22
gll
Connection object
A Connection object is created for each user participatinin the call. It connects the user’s Address object with the Caobject.
Figure 7: Finite state machine: Connection object
IDLE This state is the initial state for all new Connections.Connections which are in the Connection.IDLEstate are not actively part of a telephone call, yettheir references to the Call and Address objects arevalid.
INPROGRESS This state implies that the Connection, which repre-sents the destination end of a telephone call, is in theprocess of contacting the destination side. Undercertain circumstances, the Connection may notprogress beyond this state. Extension packageselaborate further on this state in various situations.
ALERTING This state implies that the Address is being notifiedof an incoming call.
IDLE
INPRO-
ALERT.
initial state
GRESS
CON-NECTED
DISCON-NECTED
(UNKNOWN and FAILED states not shown)
Cnx
Cnx
Cnx
8 / 22
ne
TerminalConnection object
A TerminalConnection object is created for each telephoterminal participating in a Connection. It connects the termi-nal’s Terminal object with the Connection object.
CONNECTED This state implies that a Connection and its Addressis actively part of a telephone call. In commonterms, two people talking to one another are repre-sented by two Connections in the Connection.CON-NECTED state.
DISCONNECTED This state implies a Connection is no longer part ofthe telephone call, although its references to Calland Address still remain valid. A Connection in thisstate is interpreted as once previously belonging tothis telephone call.
FAILED This state indicates that a Connection to that end ofthe call has failed for some reason. One reason whya Connection would be in the Connection.FAILEDstate is because the party was busy.
Figure 8: Finite state machine: TerminalConnection object
IDLE This state is the initial state for all TerminalConnec-tions. TerminalConnection objects do not stay inthis state for long. They typically transition intoanother state quickly.
Cnx
Cnx
Cnx
IDLE
RING-
PASSIVE
initial state
ING
ACTIVE
DROPPED(UNKNOWN state not shown)
TrmCnx
9 / 22
lens. atthecall
i-
1.2.2.4 Preconditions and postconditions
When looking at the call state at the level of an individuaCall, Connection or TerminalConnection object one will noticthat the state machines define many possible state transitioWhen combining these state machines in a call and lookingthe overall call state resulting from them it may appear that engendered space is too large, i.e. it contains meaningless states. To discard these meaningless states JTAPI specifiesrestrictions at a higher level in the form of pre- and postcondtions for method calls on objects of the call model.
RINGING This state indicates the a Terminal is ringing, indi-cating that the Terminal has an incoming Call.
ACTIVE This state indicates that a Terminal is actively partof a telephone call. This usually implies that theparty speaking on that Terminal is part of the tele-phone call.
PASSIVE This state indicates that a Terminal is part of a tele-phone call but not in an active fashion. This mayimply that a resource of the Terminal is being usedand may limit actions on the Terminal.
DROPPED This state indicates that a particular Terminal haspermanently left the telephone call.
TrmCnx
TrmCnx
TrmCnx
TrmCnx
10 / 22
forallstly.
er
1.2.2.5 Sample call setup
This section shows the state transitions of the call modela call setup. The scenario is a two-party call where user A cuser B. Shown are the call models of two JTAPI interfaces athe terminal of user A and the terminal of user B, respective
Call model at terminal A Signallingmessage
Call model at terminal B
After initialization the service provider reports two objects in itsaddress space: a Terminal representing the local terminal and anAddress representing the local user. The application adds an Observto the local Terminal.
The application creates aCall object to place a call.
The application places thecall.
Addr Trm A
addObserver()
Addr Trm B
addObserver()
Provider.createCall()
Addr Trm A Addr Trm B
Addr Trm ACall Addr Trm B
Addr Trm ACall
connect(...)
Addr Trm B
11 / 22
The service provider cre-ates a Call with two calllegs, each with a Connec-tion and TerminalConnec-tion. After creation theFSMs are IDLE.
The local call leg transi-tions into CONNECTED/ACTIVE. The protocolstack sends a SETUP mes-sage.
Call model at terminal A Signallingmessage
Call model at terminal B
Call
Cnx
Addr
TrmTrmCnxA
BAddr
Cnx TrmCnx Trm
Addr Trm B
Call
Cnx
Addr
TrmTrmCnxA
BAddr
Cnx TrmCnx Trm
SETUP Addr Trm B
12 / 22
The service provider cre-ates a Call with two calllegs, each with a Connec-tion and TerminalConnec-tion. After creation theFSMs are IDLE.
The remote call leg transi-tions into CONNECTED/ACTIVE. The local callleg transitions intoALERTING/RINGING.The protocol stack sendsback an ALERTING mes-sage.
Call model at terminal A Signallingmessage
Call model at terminal B
Call
Cnx
Addr
TrmTrmCnxA
BAddr
Cnx TrmCnx Trm
Call
Cnx
Addr
TrmTrmCnxA
BAddr
Cnx TrmCnx Trm
Call
Cnx
Addr
TrmTrmCnxA
BAddr
Cnx TrmCnx Trm
ALERTING
Call
Cnx
Addr
TrmTrmCnxA
BAddr
Cnx TrmCnx Trm
13 / 22
The remote call leg transi-tions into ALERTING/RINGING.
The application notifiesthe user that a call is com-ing in from A.
User B is alerted and the system waits until he answers the call.
User B tells the applica-tion to answer the call.
The local call leg transi-tions into CONNECTED/ACTIVE. The protocolstack sends a CONNECTmessage.
Call model at terminal A Signallingmessage
Call model at terminal B
Call
Cnx
Addr
TrmTrmCnxA
BAddr
Cnx TrmCnx Trm
Call
Cnx
Addr
TrmTrmCnxA
BAddr
Cnx TrmCnx Trm
Call
Cnx
Addr
TrmTrmCnxA
BAddr
Cnx TrmCnx Trm
Call
Cnx
Addr
TrmTrmCnxA
BAddr
Cnx TrmCnx Trm
answer()
Call
Cnx
Addr
TrmTrmCnxA
BAddr
Cnx TrmCnx Trm
CONNECT
Call
Cnx
Addr
TrmTrmCnxA
BAddr
Cnx TrmCnx Trm
14 / 22
bemi-re-
n of
e
lls
a
m.
on-nalds
1.2.3 Uniformity of representation vs. uniformity of control
One of the powerful principles of JTAPI is that the callmodel that the service provider presents to the application isindependent from the location of the JTAPI interface: it can somewhere inside the telephone system or at one of the ternals participating in the call. The example presented in the pceding section demonstrates that, neglecting the propagatiosignalling messages, the call models at terminal A and B areidentical. This uniformity of representation can not always bmaintained, namely when signalling protocols do not carryenough information. In the PSTN for example conference caare not visible to a terminal, even with ISDN signalling.
The uniformity of representation does not imply howeveruniformity of control. The fact that the application sees uniformobjects does not mean that it has the same control over theObviously first-party call control is not uniform. For examplean application at terminal A is only able to manipulate the Cnection and TerminalConnection objects that attach to termiA’s Terminal object. If an application tries to invoke a methoon an object it has no control over the service provider throwan exception.
The remote call leg transi-tions into CONNECTED/ACTIVE.
The call is established.
Call model at terminal A Signallingmessage
Call model at terminal B
Call
Cnx
Addr
TrmTrmCnxA
BAddr
Cnx TrmCnx Trm
Call
Cnx
Addr
TrmTrmCnxA
BAddr
Cnx TrmCnx Trm
15 / 22
l
ndut
al
pa-
ony
all-t
rthe
al
in
e
re
ll-ll
hen/elro-
1.2.4 Several levels of detail
JTAPI makes use of inheritance to achieve a design goasummarized by the motto “simple things should be simple”.The application can choose between a basic view of entities acalls and more detailed views revealing more information abodifferent aspects. The objects that provide the detailed viewinherit from the objects of the basic view and define additionstates and methods.
The basic view is provided by thecore package, thedetailed views for example by thecallcontrol andcallcenterpackages.
1.2.5 Actors above and below the API
Most API designs are built on a master/slave relationshibetween the application and the service provider: The appliction is in control; it initiates actions and the service providerresponds to these actions. This is not the case with a telephAPI. It is in the nature of a telephone system that a call ismanipulated by many actors: foremost the users control the cvia their terminals. As we have seen an application may perform first-party or third-party call control. It is not excluded thaseveral unrelated applications manipulate the same call. Anapplication is just one of several actors. The service providereports the external actions (and of course also the actions oflocal application) through state changes of the call model.Regarding the control of a call JTAPI is therefore a symmetricAPI, control can be exerted both from above and from belowthe API.
JTAPI makes use of theObserver [GHJV95] andEventObjectpatterns to inform the application about state changesthe call model. The application registers an object as anObserverwith the service provider. Its purpose is to observe thcall model, which is theSubject. Whenever the state of a finitestate machine in the call model changes the service providegenerates anEvent Object that describes the state change. Thservice provider then calls the application’s Observer objectand hands it a reference to the Event Object.
Because the appliction is not the only actor in a call a wewritten application must not assume that state transitions wifollow a given path; it must be always prepared to deal withunexpected state changes resulting from external actions. Wdesigning an application for a user interface the Model/ViewController pattern can be successfully applied: The call modcorresponds to the pattern’s Model. The application has to p
16 / 22
serl
ey
IPer--
re
er
t-
anme),-
en-
are
vide the View and the Controller. The View renders the callstate in a graphical representation. The Controller accepts uinput and initiates actions on the call. Because the call modereports all actions, be they triggered externally or from theapplication, the View and Controller can be kept separate, thcommunicate only through the call model.
1.3 Using JTAPI for IP telephony
First-party and third-party call control in IP telephony
Just like in a traditional telephone system call control in telephony can be performed first-party via an interface at a tminal or third-party via an interface inside the telephone system. In a peer-to-peer architecture however the call controlfunctions are fully implemented by the terminals such that theis no longer an ‘inside’. In that case a proxy has to be intro-duced that intervenes in the call control protocol.
Addressing
Fortunately JTAPI’s call model distinguishes between usidentifiers and terminal addresses in the form of separateAddress objects and Terminal objects. Therefore it is straighforward to map the user identifiers of an IP telephone systemwhich have often the form of e-mail addresses to Addressobjects. Telephone terminals are internet hosts which have IP address (which may also be represented by a domain nathis address maps to Terminal objects. Throughout the examples given in this document we have already used this convtion.
A shortcoming of JTAPI’s call model is that Addressobjects and Terminal objects are static. More precisely theretwo kinds of Address and Terminal objects:
Figure 9: First-party and third-party call control in IP telephony
JTAPIfirst-party call control
JTAPIthird-party call control
appl.
appl.
H.323Term.
H.323Proxy
H.323Term.
H.323Term.
H.323Term.
17 / 22
ro-
ter-be
ot intheyger
ofhod
ore
ow
n it-
r ter-n
he
tsallh
• There are static Addresses and Terminals that the service pvider knows about already before any call exists. On a first-party call control interface these are the objects for the localminal and the user of that terminal. These objects are said toin theaddress space of the provider.
• Then there are those Addresses and Terminals which are nthe address space of the provider but which appear becauseparticipate in a call. The application has no way of accessinthem except through call objects, therefore the service providis free to create them dynamically when they are needed.
JTAPI assumes that the relationship between Addressobjects and Terminal objects is fixed throughout the lifetimethese objects (see for example the documentation of the metTerminal.getAddresses()). In IP telephony however the rela-tionship between user identifiers and terminal addresses is mdynamic than this.
1.3.0.1 Mapping features of an H.323 terminal to JTAPI
This section presents features of an H.323 terminal and hthey are represented in JTAPI.
Multiple simultaneous calls
Because there is no physical line for a bearer connectiois easy for IP telephone terminals to support multiple simultaneous calls. An example of their representation in JTAPIthrough multiple call instances is shown in Figure 3.
Call hold
When a terminal puts a call on hold it stops processingmedia from the other terminals, stops sending media to theother terminals, and sends a signalling message to the otheminals that tells them to stop sending media to the terminal. Aimportant point to note about call hold is that each party has tpossibility to put a call on hold independently from all otherparties. An example of a two-party call is shown below. A puthe call on hold. Independently of that B could also put the con hold. Note how JTAPI correctly represents the party whicput the call on hold.
18 / 22
e
Call hold is a feature of the call control extension packagof JTAPI.Call model at terminal A Signallingmessage
Call model at terminal B
A call is established between terminals A and B.
The application puts thecall on hold by invokinghold() on the local Call-ControlTerminalConnec-tion.
The local CallControlTer-minalConnection transi-tions into HELD. Theprotocol stack sends aHOLD message.
Call
Cnx
Addr
TrmTrmCnxA
BAddr
Cnx TrmCnx Trm
Call
Cnx
Addr
TrmTrmCnxA
BAddr
Cnx TrmCnx Trm
Call
Cnx
Addr
TrmTrmCnxA
BAddr
Cnx TrmCnx Trm
hold()
Call
Cnx
Addr
TrmTrmCnxA
BAddr
Cnx TrmCnx Trm
Call
Cnx
Addr
TrmTrmCnxA
BAddr
Cnx TrmCnx Trm
HOLD
Call
Cnx
Addr
TrmTrmCnxA
BAddr
Cnx TrmCnx Trm
19 / 22
ak-alsne
then
r
n-
Multiple alerting terminals
Multiple alerting terminals are as easily supported by IPtelephone terminals as multiple simultaneous calls. When ming a call to a user who wants to be alerted via several terminthe calling terminal simply establishes several H.323 calls, oto each terminal. When one of the called terminals answerscalls to the other terminals are immediately disconnected. Aexample of the call model in this case is shown in Figure 4.
Multi-party conference calls
The Recommendation H.323 specifies several modes foconferences.
1.3.1 Multimedia
[Call control vs. media control. Call establishment not idetical to media stream establishment.]
The remote CallControl-TerminalConnection tran-sitions into HELD.
Now the call is in a state where it is put on hold by A. Note that B’sability to put the call on hold is not affected by it.
Call model at terminal A Signallingmessage
Call model at terminal B
Call
Cnx
Addr
TrmTrmCnxA
BAddr
Cnx TrmCnx Trm
Call
Cnx
Addr
TrmTrmCnxA
BAddr
Cnx TrmCnx Trm
20 / 22
Figure 10: Call model for three-party call with media streams for onemedium
Addr
Cnx TrmCnx Trm h101.ibm.com
Call
Cnx
Addr
TrmTrmCnx
Addr
Cnx TrmCnx Trm
b205.ibm.com s131.ibm.com [email protected]
b205.ibm.com
s131.ibm.com
h101.ibm.com [email protected]
Src
Snk
Snk
Snk
Snk
Src
Src
Snk
Snk
21 / 22
MediaEndpoint
Figure 11: Finite state machine: MediaEndpoint object
IDLE This is the initial state for a newly created MediaEnd-points. There are no media resources allocated yet.
ACTIVE Media resources are allocated and media data are beingtransmitted.
HELD Media resources are allocated but media transmission issuspended.
CLOSED The media resources are deallocated.
IDLE
PASSIVE
initial state
ACTIVE
CLOSED
ME
ME
ME
ME
22 / 22
