java telephony api pdf

JavaTM Telephony SpecificationThe Java Telephony API (JTAPI) Overview The Java Telephony API (JTAPI) is a portable,object-oriented application programming interface for Java-based computer-telephony applications.

See: Description

JTAPI version 1.3Early Access 1

1

7 Apr 1999JavaTM Telephony Specification

Java Telephony API 1.3

javax.telephonyThe Java Telephony API (JTAPI ) is a portable,object-oriented application programming interface forJava-based computer-telephony applications.

javax.telephony.callcenterThis document is an overview of the Call Center ExtensionPackage to the Java Telephony API.

javax.telephony.callcenter.capabilities JTAPI Call Center capabilities.

javax.telephony.callcenter.events JTAPI Call Center events package.

javax.telephony.callcontrolThis document provides an overview of the Call ControlExtension Package to the Java Telephony API.

javax.telephony.callcontrol.capabilities JTAPI Call Control capabilities.

javax.telephony.callcontrol.events JTAPI Call Control capabilities.

javax.telephony.capabilities JTAPI Core capabilities package.

javax.telephony.events JTAPI Core events overview.

javax.telephony.mediaThis document is an overview of the Media services packageto the Java Telephony API.

javax.telephony.media.capabilities JTAPI Media capabilities packae

javax.telephony.media.events JTAPI Media application events package.

javax.telephony.mobileThe JTAPI Mobile package extends the core capabilities of aJTAPI implementation with capabilities specific to mobile networks.

javax.telephony.phoneThis document provides an overview of the Phone Extension Package to the Java Telephony API.

javax.telephony.phone.capabilities JTAPI Phone capabilities package.

javax.telephony.phone.events JTAPI Phone events package.

javax.telephony.privatedata JTAPI Private Data package

javax.telephony.privatedata.capabilities JTAPI Private Data capabilities package

javax.telephony.privatedata.events JTAPI Private Data events package

JTAPI version 1.3 Early Access 1

2

JavaTM Telephony Specification 7 Apr 1999

The Java Telephony API (JTAPI) OverviewThe Java Telephony API (JTAPI) is a portable, object-oriented application programming interface forJava-based computer-telephony applications. JTAPI is comprised of a set of classes, and interfaces thatconstitute an optional Java extension package in the javax.* name space. JTAPI is the interface betweenJava computer telephony applications and telephones or telephone system implementations.

JTAPI serves a broad audience, from call center application developers to web page designers. JTAPIsupports both first- and third-party telephony application domains. The API is designed to makeprogramming simple applications easy, while providing those features necessary for advanced telephonyapplications.

The Java Telephony API is, in fact, a set of API’s. The "core" API provides the basic call model andrudimentary telephony features, such as placing telephone calls and answering telephone calls. The coreAPI is surrounded by standard extension APIs providing functionality for specific telephony domains,such as call centers and media stream access. The JTAPI core and extension package architectures aredescribed later in this document.

Applications written using the Java Telephony API are portable across the various computer platforms andtelephone systems. Implementations of JTAPI will be available for existing computer-telephonyintegration platforms such as Sun Microsystem’s SunXTL, Microsoft and Intel’s TAPI, Novell andLucent’s TSAPI, and IBM’s CallPath. Additionally, independent hardware vendors may choose to provideimplementations of the Java Telephony API on top of their own proprietary hardware.

Changes in JTAPI 1.3JTAPI 1.3 now supports the listener event pattern and contains two new packages:

The core package now has a listener event pattern in the style of JDK 1.1+. While observer eventpattern has not been deprecated, prepare for that eventuality in JTAPI 2.0. The intent is to fullysupport the listener event pattern in all JTAPI packages in the JTAPI 2.0 release.

The JTAPI 1.2 media package is now being replaced by the ECTF S.410 media specification. TheJTAPI 1.2 methods are deprecated.

A mobile package is now available to address the special needs of mobile telephony. The mobilepackages only supports the listener event pattern.

Rationale for a Java-based Telephony API

Why Java?The driving force behind the use of Java for this specification is the desire to maximize applicationportability across vendor implementations. "Application Portability" is literal - the application itself, incompiled form, may be loaded onto any conforming implementation and executed.


3

7 Apr 1999The Java Telephony API (JTAPI) Overview

The Java programming language is used for this specification because of its support for "write once, runanywhere" application development. JTAPI implementations may not be portable. They may be very closely tied to a specific telephonyenvironment, and in fact may rely heavily on "native code". JTAPI applications may be portable. Forinstance, JTAPI code may be loaded as an applet and executed by an Internet browser.

Why JTAPI?The goals for JTAPI are simple, if ambitious - to create an API that allows applications to run on a varietyof operating systems and hardware platforms, against a variety of telephony networks.

JTAPI is intended to be a simple API as well. JTAPI still requires application developers to beknowledgeable about telephony, but reduces the amount of implementation-specific knowledge requiredto develop applications.

The range of "targets" for JTAPI ranges from the largest call centers, to desktop systems, to networkcomputers, to "network telephones". This range is the reason for the "core plus extensions" organization ofJTAPI, discussed later.

JTAPI blurs borders. It blurs the distinction between first-party and third-party call control, and it blurs thedistinction between call control and media control.

JTAPI isn’t "just another telephony API" - although JTAPI can be implemented without existingtelephony APIs, it was also designed to allow implementers to build on top of these existing telephonyAPIs.

The basic design philosophy guiding JTAPI design includes:

Brings simplicity to the most basic telephony applications Provides a scalable framework that spans desktop applications to distributed call center telephonyapplications Interfaces applications directly to service providers or acts as a Java interface to existing telephonyAPIs, such as SunXTL, TSAPI, and TAPI Based on a simple core that is augmented with standard extension packages Runs on a wide range of hardware configurations, wherever Java run-time can be used

ArchitectureJTAPI enables portability of telephony applications, for both public and private networks, across a broadspectrum of telephony platforms. To achieve this portability, JTAPI users two architectural concepts:

The JTAPI Peer The Core Plus Extension Architecture


4

Architecture 7 Apr 1999

JTAPI PeerAn implementation of JTAPI for a particular telephony platform is called a Peer. Examples of peertelephony platforms are PBX systems, media servers, call center servers and telephone sets. JTAPI,standard Java APIs and the JVM (Java Virtual Machine) are implemented on top of the telephonyplatform peer as shown in Figure 1. The peer represents the telephony system’s operating system (OS) andthe hardware of the platform.

Figure 1 JTAPI Peer

An application accesses the functionality of the peer through the programming interfaces provided byJTAPI and the JVM.

Figure 1 depicts a simplified, centralized, pure JTAPI implementation. JTAPI is not restricted to thismodel. A JTAPI peer platform may already contain existing standard telephony APIs such as TAPI,TSAPI and vendor specific APIs such as Nortel Networks Meridian Link, IBM Callpath and LucentPassageway. As shown in Figure 2, JTAPI can also be implemented on top these API.


5

7 Apr 1999JTAPI Peer

Figure 2 JTAPI Wrapper

The JTAPI architecture also allows JTAPI to work in distributed environments as show in Figure 3.


6

JTAPI Peer 7 Apr 1999

Figure 3 Distributed JTAPI

Core Plus Extension ArchitectureThe core plus extension architecture defines a minimum package of core functionality that most JTAPIimplementations will have. The core functionality provides the functionality to make and answer simpletwo party calls. For applications which require additional call or media stream control, additional optionalpackages extend the core interfaces can be included in a JTAPI implementation as required. Figure 2shows the core plus extension concept.


7

7 Apr 1999Core Plus Extension Architecture

Figure 4 JTAPI Core + Extension Architecture

JTAPI extension packages are not restricted to extending just the functionality present in the core. In fact,most package extend the core functionality and add functionality not present in the core. In one case, thenew JTAPI 1.3 media packages can be implemented independent from the core.

PackagesThe Java Telephony API is composed of a set of Java language packages. Each package provides aspecific piece of functionality for certain aspect of computer-telephony applications. The core package isrequired by most JTAPI implementations. The other packages are optional. Implementations of telephonyservers choose the optional packages they support based upon the capabilities of their underlying platformand hardware.

All JTAPI packages are in the javax.telephony name hierarchy. The packages defined in JTAPI 1.3 are:


8

Packages 7 Apr 1999

Core package javax.telephony

Call Control javax.telelphone.callcontrol

Call Center javax.telelphone.callcenter

Media javax.telelphone.media

Mobile javax.telelphone.mobile

Phone javax.telelphone.phone

Private Data javax.telelphone.privatedata

CoreThe javax.telephone package, or core package, contains the coreinterfaces. The core package provides thebasic framework to model telephone calls and rudimentary telephony features. These features includeplacing a telephone call, answering a telephone call, and disconnecting a connection to a telephone call.Simple telephony applications will only need to use the core to accomplish their tasks, and do not need toconcern themselves with the details of other packages.

The core package contains:

Basic call control methods: createCall(), connect(), answer(), disconnect()

Capabilities for each of these methods. Simple state transitions with corresponding events.

Call ControlThe javax.telephony.callcontrol package extends the core package by providing more advancedcall-control features and a more detailed state model of telephone calls. The additional calling featuresinclude:

conference calling transfer forwarding call hold call join message waiting do not disturb call park & pickup


9

7 Apr 1999Core

Call CenterThe javax.telephony.callcenter package provides applications the ability to perform advanced featuresnecessary for managing large call centers. Examples of these advanced features include:

ACD agent support Routing, Automated Call Distribution (ACD), Predictive Calling Application Data (associated with telephony objects.)

MediaThe javax.telephony.media package provides application the ability to manipulate media streamsassociated with calls. For JTAPI 1.3, a new media API that implements the ECTF S.410 specification hasbeen added. This version of JTAPI media API is designed as a complete replacement for the mediapackage defined in JTAPI 1.2. It matches the ECTF model of a CTI server that supports multi-vendorapplications and shared resources in an enterprise environment, but it can also be effectively used onsingle-use desktop environments. It represents the first object-oriented API based on the ECTF S.100 API.

The JTAPI 1.3 media package uses an extensible resource architecture to provide media services for:

Players Recorders Signal Detectors Signal Generators

The media architecture allows new resources to easily added in future JTAPI releases. Resources for faxservers and automatic speech recognition are already in the planning stages.

All classes in the 1.2 release of the media package are deprecated in JTAPI release 1.3. The new mediapackage is defined to ensure there are no namespace overlaps allowing the coexistence of both packagesfor a transition period.

MobileThe javax.telephony.mobile package provides features required for applications running on mobiletelephones or within a mobile telephone network environment. JTAPI Mobile extends core JTAPI withthe following mobile network functionality:

Mobile Call Control, Mobile Network Access and Control Media Services for Mobile Applications


10

Call Center 7 Apr 1999

Telephony platforms supporting these applications by providing JTAPI

Mobile include (but are not limited to):

Individual mobile telephone sets (wireless) Individual mobile data-only devices (pagers) GSM, TDMA and CDMA mobile stations

PhoneThe javax.telephony.phone package permits applications to control the physical features of telephonehardware phone sets. Implementations may describe Terminals as collections of components, where eachof these component-types has interfaces in this package. The phone package provides interfaces to model:

buttons displays lamps ringers hook switches speakers microphones

Private DataThe javax.telephony.privatedata package enables applications to communicate data directly with theunderlying hardware switch. This data may be used to instruct the switch to perform a switch-specificaction. Applications may also use the package to "piggy-back" a piece of data with a Java Telephony APIobject.

Call ModelThe call model consists of the six core call control objects, call events, and implementation capabilities.These call objects, events and capabilities comprise the essence of JTAPI and are described in this section.

Core ObjectsThe Call Model used in JTAPI consists of six primary or core call control objects;

Provider - the "window" through which JTAPI applications see the telephony system. Call - the dynamic "collection of logical and physical entities" that bring two or more endpointstogether. Address - a logical end-point - a "phone number". Connection - the dynamic relationship between a Call and an Address. Terminal - a physical end-point - a "phone set". TerminalConnection - the dynamic relationship between a Connection and a Terminal.


11

7 Apr 1999Call Model

These objects are defined using Java interfaces in the core package. Each call model object

represents either a physical or logical entity in the telephone world. The primary purpose of these callmodel objects is to describe telephone calls and the endpoints involved in a telephone call. These callmodel objects are related to one another in specific ways, which is summarized below and described inmore detail in the core package specification.

Figure 5 shows the JTAPI call model and the objects that compose the call model. A description of eachobject follows the figure.

Figure 5 Call Model


12

Core Objects 7 Apr 1999

ProviderThe Provider object is an abstraction of telephony service-provider software. The provider might managea PBX connected to a server, a telephony/fax card in a desktop machine, or a computer networkingtechnology, such as IP. A Provider hides the service-specific aspects of the telephony subsystem andenables Java applications and applets to interact with the telephony subsystem in a device-independentmanner.

CallThe Call object represents a telephone call, the information flowing between the service provider and thecall participants. A telephone call comprises a Call object and zero or more connections. In a two-partycall scenario, a telephone call has one Call object and two connections. A conference call is three or moreconnections associated with one Call object.

AddressThe Address object represents a telephone number. It is an abstraction for the logical endpoint of atelephone call. Note that this is quite distinct from a physical endpoint. In fact, one address maycorrespond to several physical endpoints (i.e. Terminals)

ConnectionA Connection object models the communication link between a Call object and an Address object. Thisrelationship is also referred to as a "logical" view, because it is concerned with the relationship betweenthe Call and the Address (i.e. a logical endpoint). Connection objects may be in one of several states,indicating the current state of the relationship between the Call and the Address. These Connection statesare summarized later.

TerminalThe Terminal object represents a physical device such as a telephone and its associated properties. EachTerminal object may have one or more Address Objects (telephone numbers) associated with it, as in thecase of some office phones capable of managing multiple call appearances. The Terminal is also known asthe "physical" endpoint of a call, because it corresponds to a physical piece of hardware.

TerminalConnectionTerminalConnection objects model the relationship between a Connection and the physical endpoint of aCall, which is represented by the Terminal object. This relationship is also known as the "physical" viewof the Connection (in contrast to the Connection, which models the logical view). TheTerminalConnection describes the current state of relationship between the Connection and a particularTerminal. The states associated with the TerminalConnection are described later in this document.


13

7 Apr 1999Provider

CapabilitiesTelephony environments vary widely in their ability to perform certain functions. This variation mayreflect technical considerations or administrative considerations. JTAPI does nothing to reduce thisvariation (if you don’t subscribe to a conferencing feature, JTAPI won’t changethis). What JTAPI does dois provide a mechanism for finding out exactly what an application (which, after all, may have beendownloaded over the Internet) can do in its current execution environment. This mechanism, taken fromexisting telephony APIs, is called Capabilities.

The javax.telephony.capabilities package contains the mechanisms that allow applications to querywhether certain actions may be performed. Capabilities take two forms:

Static capabilities indicate whether an implementation, or a specific call model object, supports amethod (e.g. the Terminal is capable of rejecting an incoming call). Dynamic capabilities indicate whether a certain action is allowable on a specific call model object,given the current state of the call model. (e.g. the Reject() method can only be invoked when there isan incoming telephone call.)

For instance, although almost all telephone users can make an outgoing call, applications

which blindly assume that this is true will fail in "incoming-only" environments.

Many static capabilities can be determined at initialization time, but dynamic capabilities can come andgo. For this reason, a well-behaved JTAPI application will query relevant capabilities at initializationtime, in order to "gray out" unsupported/unavailable features in user interface displays, but will checkagain when preparing to invoke the relevant method. This will minimize the number of exceptions theapplication will encounter.

A JTAPI application can still be "well-behaved" without checking capabilities, as long as it catchesMethodNotSupportedException and InvalidStateException. This approach is simple, but does not allowthe application to present an accurate user interface (the user may attempt actions which aren’t allowed bythe implementation).

Capabilities are aligned one-to-one with methods; if a method isn’t implemented in all environments, acapability exists to allow the application to check whether it is available at execution time.

Every core JTAPI call-model object has an associated capability object:

ProviderCapabilities CallCapabilities AddressCapabilities ConnectionCapabilities TerminalCapabilities TerminalConnectionCapabilities


14

Capabilities 7 Apr 1999

Because call model objects in JTAPI extension packages support additional methods, these packages haveassociated extended capability objects corresponding to these methods as well.

The two new JTAPI 1.3 packages, media and mobile, do not extend the capabilities mechanism. Instead,they either depend on catching the exception, MethodNotSupportedException, or providing a contract tothe user that all the methods in the interface are supported. In the latter case, the instanceOf operator canbe used to determine if an interface is present.

EventsJTAPI applications need to know about state changes in call model objects that aren’t the result ofanything the application has done. For instance, an application may want to know when an incoming callhas arrived at a specific terminal in order to update a user’s view of that terminal on a graphical userinterface.

JTAPI supports two event model:

Listener Event Model Observer Event Model

Beginning with JTAPI 1.3, the core package supports the listener event model in the style of JDK 1.1. InJTAPI 1.2 and earlier releases, JTAPI only supported the observer event model. The addition of thelistener event model brings JTAPI up to date with the latest Java technology. In a future JTAPI 2.0release, all JTAPI packages will support the listener event model and the observer model will bedeprecated.

Event BasicsThe JTAPI call model is a loosely coupled finite state machine. To use this model, there are six conceptswith which one must be familiar:

Entity : A Call model object, provided to model the capabilities (and current activities) of an externaltelephony system, which is directly controlled by a telephony platform and affected by external Callactivity. State: The operational condition of an Entity in the Call model, or of the Call model taken as awhole. Event: A report to an application that an Entity has changed State, modeling a change in state of theexternal telephony system. Event Notification: The delivery of Events to applications which have specifically requested them. Registration: The request made by an application to be given Event Notification. Applicationsinterested in Event Notification register as either observers or listeners; Target: an application object that registers for and can receive events

The Call model objects for which applications may register for event notification, are:

Provider Call


15

7 Apr 1999Events

Address Terminal

Events correspond one-to-one with call model state transitions. The general idea is that call model objectentities, instantiated by a JTAPI implementation, generate events when a stimuli occur that cause a statechange to the call model. Applications that want to know about state changes register their target object asan observer or listener. The target object will be notified of model state changes when they occur. Themechanisms for event registration and notificationfor listeners are done differently from how they aredone for observers. The details of how each event model works will be provided in the following sections.

Meta-EventsMeta-event are events that transcend other related, subordinate events. For example, a call transfermeta-event could imply call-hold, call-ringing, call-answer, and call-release events. All of the subordinateevents could have occurred as part of the transfer event. An application may only see that a transfermeta-event has happened.

Meta-events are implemented differently in the listener and observer models. The relevant JavaDocsections should be viewed to see how each model implements meta-events.

The Listener Event ModelStarting with JTAPI 1.3, the primary way to arrange for a provider to report events is to use listeners,following the pattern established in Java release 1.1. Listener and event interfaces have been added toJTAPI core along with add and remove listener methods in JTAPI core object model interfaces.

Listener InterfacesThere are six listener interfaces defined in JTAPI core:

CallListener CallConnectionListener CallTerminalConnectionListener TerminalListener AddressListener ProviderListener

All events pertaining to call model objects are delivered through objects implementing the listenerinterfaces. For example, events pertaining to call objects are delivered through objects that implement theCallEvent interface. These objects must register for the events in which they are interested by calling thecall model objects’ add listeners methods. For instance, a object implementing a CallListener wouldregister with the call object of interest by invoking the call object’s Call.addListener() method.

Connection-related and TerminalConnection-related events are reported via the ConnectionListener andTerminalConnectionListener interfaces respectively extensions of the CallListener interface. These eventsinclude the creation of these objects and their state changes. These events extend the ConnectionEventinterface and the TerminalConnectionEvent interface, respectively.


16

Meta-Events 7 Apr 1999

Listener EventsAn event is delivered to the application whenever the state of the call models changes. There are sixlistener event interfaces defined in JTAPI core for delivering call model event information:

CallEvent ConnectionEvent TerminalConnectionEvent TerminalEvent AddressEvent ProviderEvent

An event interface represents a group of events. For example, a CallEvent will be generated when a callbecome active or goes to an invalid condition. The specific reason for the event generation can bedetermined from the EventID carried in a CallEvent object. In the CallEvent case, the event IDscorresponding to Call state changes are CallActiveEventID and CallInvalidEventID respectively.

When Call Event Transmission EndsAt times it may become impossible for the implementation to report events to an application. In this case,a CALL_EVENT_TRANSMISSION_ENDED is delivered to an object registered as a CallListener (or anextension of that interface).

This is the final event receives by the Listener, and it is no longer reported via the Call.getListeners()method.

Event GranularityAn application controls the granularity of events which are reported by the listener interfaces that itimplements. The interfaces are organized in an inheritance hierarchy with the CallListener at the top, theConnectionListener inheriting from CallListener and finally the TerminalConnectionListener inheritingfrom ConnectionListener. Each successively lower level in the hierarchy provides more detailed eventreporting. The implementation determines what level of events to report by ascertaining which interfacehas been implemented.

Registering Call Listeners via Address and TerminalApplications may receive events about a Call by adding an Listener via the Address or Terminal objectsusing the Address.addCallListener() and Terminal.addCallListener() (and related) methods. Thesemethods provide the ability for an application to receive Call-related events when a Call contains aparticular Address or Terminal. In particular, methods exist to add a CallListener, ConnectionListener andTerminalConnectionListener via Address and Terminal. See the specifications for Address and Terminalfor more details.


17

7 Apr 1999Listener Events

Listener Meta-EventsThe listener meta-events are optional high level JTAPI event that provide details of high level callfunctions. The high level details my pertain to single call or to multiple call operations. Single callmeta-events are used to report call-progress details of a call. Mutli-call meta-events are used to report theprogress of multi-call operations such as call transfer and conference. JTAPI 1.3 only supports single callmeta-events. Multi-call meta-events are planned for JTAPI 2.0.

Currently, meta events are defined in pairs, and they convey three types of information:

the high level operation which has occurred; the start and end of the sequence of "regular" JTAPI events generated due to the high leveloperation. The regular JTAPI events convey the consequential JTAPI call model state changes; the JTAPI entities which were involved in the higher-level operation.

A JTAPI application is alerted to changes in the state of its associated telephony platform by a stream ofJTAPI event objects, delimited by start and end MetaEvents. An application learns of the details of a statechange by processing all the events between the starting and ending MetaEvents. When usingmeta-events, applications should wait for the matching "ending" MetaEvent to be received beforeprocessing the regular events to avoid making an incorrect determination about the state of its associatedtelephony platform.

The specific Meta event is provided by the Event.getID() value returned by the event. The specific Metaevent provides context information about the higher-level event.

The Observer Event ModelThe Provider, Call, Terminal, and Address objects have Observers. The interfaces corresponding to theseobservers are ProviderObserver, CallObserver, TerminalObserver, and AddressObserver, respectively.

The ProviderObserver reports all state changes to the Provider object. For the core package, state changesare reported when the Provider changes state from OUT_OF_SERVCE, to IN_SERVICE, toSHUTDOWN.

The Call observer reports state change information for all Connections and TerminalConnections that arepart of the telephone call as well as state changes to the Call itself. These state changes are reported onneither the Address nor the Terminal observers.

At times, the application may want to monitor Address or Terminal objects for incoming telephone calls.In these instances, the application uses the Address.addCallObserver() or the Terminal.addCallObserver()methods. These methods instruct the implementation to automatically add a CallObserver to any calls thatcome to an Address or Terminal. These CallObservers are removed once the call leaves the Address orTerminal.

The Address and Terminal observers report any state changes in these objects. In the core package thereare no events for these objects. The AddressObserver and TerminalObserver interfaces still exist,however, so other packages may extend these interfaces.


18

Listener Meta-Events 7 Apr 1999

Adding ObserversApplications may directly add an observer to a call model objects by invoking the objects addObservermethod. For instance, the Address.addObserver(AddressObserver) method can be used to add an observerto an address object. Applications may also add observers to Call objects indirectly via theAddress.addCallObserver() and Terminal.addCallObserver() methods. These methods add the givenobserver to the Call object when the Call arrives at the Address or Terminal.

Observer EventsThe Ev interface is the parent of all JTAPI Observer event interfaces. All JTAPI event interfaces extendthis interface, either directly or indirectly. Event interfaces within each JTAPI package are organized in ahierarchical fashion. There is one Observer event interface for each JTAPI event defined.

The JTAPI event system notifies applications when changes in various JTAPI objects occur. Eachindividual change in an object is represented by an event sent to the appropriate observer. Because severalchanges may happen to an object at once, events are delivered as a batch. A batch of events represents aseries of events and changes to the call model which happened exactly at the same time. For this reason,events are delivered to observers as arrays.

Event IDs

Each event carries a corresponding identification integer. The Ev.getID() method returns thisidentification number for each event. The actual event identification integer is defined in each of thespecific event interfaces. Each event interface must carry a unique id.

Cause Codes

Each events carries a cause or a reason why the event happened. The Ev.getCause() method returnsthis cause value. The different types of cause values are also defined in this interface.

Core Package Event Hierarchy

The core package defines a hierarchy of event interfaces. The base of this hierarchy is the Evinterface. Directly extending this interface are those events interfaces for each object which supportsan observer: ProvEv, CallEv, AddrEv, and TermEv.

Since Connection and TerminalConnection events are reported via the CallObserver interface, theConnEv and TermConnEv interfaces extends the CallEv interface.

Core MethodsThe core package defines three methods to support its primary features: placing a telephone call,answering a telephone call, and disconnecting a connection to a telephone call. These methods areCall.connect(), TerminalConnection.answer(), and Connection.disconnect(), respectively.


19

7 Apr 1999Adding Observers

Call.connect(Terminal, Address, String)

Once an application has an idle call object (obtained via Provider.createCall()), it may place atelephone call using the Call.connect() method. The application must specify the originatingTerminal (physical endpoint) and the originating Address (logical endpoint) on that Terminal (in thecase that a Terminal has multiple telephone numbers on it). It also provides the destination telephonenumber string. Two Connection objects are returned from the Call.connect() method, representing theoriginating and destination ends of the telephone call.

TerminalConnection.answer()

Applications monitor Terminals, with observers or listeners, for the arrival of incoming calls. Anincoming telephone call to a Terminal is indicated by a TerminalConnection to that Terminal in theRINGING state (see TerminalConnection states below). At that time, applications may invoke theTerminalConnection.answer() to answer that incoming telephone call.

Connection.disconnect()

The Connection.disconnect() method is used to remove an Address from the telephone call. TheConnection object represents the relationship of that Address to the telephone call. Applicationstypically invoke this method when the Connection is in the CONNECTED state, resulting in theConnection moving to the DISCONNECTED state. In the core package, application may onlyremove entire Addresses from the Call, and all of the Terminals associated with that Address whichare part of the call are removed as well. The call control extension package provides the ability forapplication to remove individual Terminals only from the Call.

Call StatesA Connection object is always in a state that reflects the relationship between a Call and an Address. Thestate in which a Connection exists is not only important to the application for information purposes, it isalways an indication of which methods and actions can be invoked on the Connection object.

The state changes which Connection objects undergo are governed by rules shown below in a statetransition diagram. This diagram guarantees to application developers the possible states in which theConnection object can transition given some current state. These state transition rules are invaluable toapplication developers. Figure 6 below shows the possible state transitions for the Connection object.Following Figure 6 is a brief summary of the meaning of each state.


20

Call States 7 Apr 1999

Figure 6 Connection State Transitions

Connection States

IDLE state

The IDLE state is the initial state for all new Connection objects. Connections typically transitionquickly out of the IDLE state into another state. A Connection in the IDLE state indicates that theparty has just joined the telephone call in some form. No Core methods are valid on Connections inthe IDLE state.

INPROGRESS state

The INPROGRESS state indicates that a telephone call is currently being placed to this destination endpoint.

ALERTING state

The ALERTING state indicates that the destination party of a telephone call is being alerted to anincoming telephone call.

CONNECTED state

The CONNECTED state indicates that a party is actively part of a telephone call. A Connection inthe CONNECTED state implies that the associated party is talking to the other parties on the call oris connected to tone.


21

7 Apr 1999Connection States

DISCONNECTED state

The DISCONNECTED state indicates that a party is no longer a part of a telephone call. No methodsare valid for Connections in the DISCONNECTED state.

FAILED state

The FAILED state indicates that a telephone call placed to the endpoint has failed. For example, if anapplication uses Call.connect() to place a telephone call to a party who is busy, the Connectionassociated with the called party transitions into the FAILED state.

UNKNOWN state

The UNKNOWN state indicates that the Provider cannot determine the state of the Connection at thepresent time. A Connection may transition in and out of the UNKNOWN state at any time, unless itis in either the DISCONNECTED or FAILED state. The effects of the invocation of any method on aConnection in this state are unpredictable.

TerminalConnection Object StatesThe TerminalConnection object represents the relationship between a Terminal and a Connection. Asmentioned previously, these objects represent a physical view of the Call, describing which physicalTerminal endpoints are part of the telephone call. Similar to Connection objects, TerminalConnectionobjects have their own set of states and state transition diagram. This state transition diagram, with a briefdescription of each state follows.


22

TerminalConnection Object States 7 Apr 1999

Figure 7 Terminal Connection State Diagram

IDLE state

The IDLE state is the initial state for all TerminalConnection objects. It has the same connotation forthe Connection object’s IDLE state.

ACTIVE state

The ACTIVE state indicates a Terminal is actively part of a telephone call. This often implies that theTerminal handset is off-hook.

RINGING state

The RINGING state indicates that a Terminal is signaling to a user that an incoming telephone call ispresent at the Terminal.

DROPPED state

The DROPPED state indicates that a Terminal was once part of a telephone call, but has sincedropped off of that telephone call. The DROPPED state is the final state for all TerminalConnections.

PASSIVE state

The PASSIVE state indicates a Terminal is part of a telephone call, but not actively so. ATerminalConnection in the PASSIVE state indicates that a resource on the Terminal is being used bythis telephone call. Packages providing advanced features permit Terminals to join calls from thePASSIVE state.

UNKNOWN state

The UNKNOWN state indicates that the Provider is unable to determine the current state of aTerminalConnection. It has a similar connotation to that of the Connection object’s UNKNOWN state.

Obtaining a ProviderAll JTAPI applications must obtain a reference to a Provider in order to do almost anything interesting.There are two elements used to obtain a provider:

JtapiPeerFactory

The JtapiPeerFactory is a static class defined in JTAPI. Its sole public method, getJtapiPeer() returnsthe JtapiPeer implementation requested or it returns a default implementation.

JtapiPeer

JtapiPeer is an interface. It is used by the JTAPI server implementers. It defines the methods thatapplications use to get Provider objects, to query services available on those providers, and to get the


23

7 Apr 1999Obtaining a Provider

name of the JtapiPeer object instance.

To obtain a provider:

The application first invokes JtapiPeerFactory.getJtapiPeer() to get a JtapiPeer. The application then invokes JtapiPeer.getProvider() to get a Provider.

The JtapiPeer, in addition to the getProvider(), also contains two other methods:

getName()

Returns the name of this JtapiPeer object instance as a String.

getServices()

Returns the services that this implementation supports in a String[] array.

Some the interesting things a provider can do are:

createCall()

Creates and returns a new instance of the Call object.

getAddresses()

Returns an array of Addresses associated with the Provider and within the Provider’s domain.

getCalls()

Returns an array of Call objects currently associated with the Provider.

getState()

Returns the current state of the Provider, either Provider.IN_SERVICE,Provider.OUT_OF_SERVICE, or Provider.SHUTDOWN.

getTerninals(string)

Returns an instance of the Terminal class which corresponds to the given name.

Call ScenariosThis section is meant to convey a sense of how to use JTAPI to perform basic call control. In this sectionwe will provide you with basic examples that employ JTAPI objects to make an outgoing call and receivean incoming call.

Because JTAPI 1.3 supports two event models, the use of both will be illustrated in the followingexamples. However, the listener model is the preferred event model and you are strongly urged to migrateexisting code based on observers to the listener model. The examples will serve to illustrate how to rewriteobserver based code as well as use listener based code.


24

Call Scenarios 7 Apr 1999

Outgoing Telephone Call Example (Observer based)The following code example places a telephone call using the core Call.connect() method. It looks for thestates provided by the Call Control package.

import javax.telephony.*;import javax.telephony.events.*;

/* * The MyOutCallObserver class implements the CallObserver * interface and receives all events associated with the Call. */ public class MyOutCallObserver implements CallObserver { /* * Events arrive as an array * We identify each of the events by its ID * then take appropriate action for each event. * In this example we just print out some messages */

public void callChangedEvent(CallEv[] evlist) { for (int i = 0; i < evlist.length; i++) { if (evlist[i] instanceof ConnEv) { String name = null; try { Connection connection = ((ConnEv)evlist[i]).getConnection(); Address addr = connection.getAddress(); name = addr.getName(); } catch (Exception excp) { // Handle Exceptions } String msg = "Connection to Address: " + name + " is "; if (evlist[i].getID() == ConnAlertingEv.ID) { System.out.println(msg + "ALERTING"); } else if (evlist[i].getID() == ConnInProgressEv.ID) { System.out.println(msg + "INPROGRESS"); } else if (evlist[i].getID() == ConnConnectedEv.ID) { System.out.println(msg + "CONNECTED"); } else if (evlist[i].getID() == ConnDisconnectedEv.ID) { System.out.println(msg + "DISCONNECTED"); } } } }}


25

7 Apr 1999Outgoing Telephone Call Example (Observer based)

import javax.telephony.*;import javax.telephony.events.*;import MyOutCallObserver;

/* * Places a telephone call from 476111 to 5551212 */public class Outcall { public static final void main(String args[]) { /* * Create a provider by first obtaining the default implementation * of JTAPI and then the default provider of that implementation. */ Provider myprovider = null; try { JtapiPeer peer = JtapiPeerFactory.getJtapiPeer(null); myprovider = peer.getProvider(null); } catch (Exception excp) { System.out.println("Can’t get Provider: " + excp.toString()); System.exit(0); } /* * We need to get the appropriate objects associated with the * originating side of the telephone call. We ask the Address for * a list of Terminals on it and (arbitrarily) choose the first. */ Address origaddr = null; Terminal origterm = null; try { origaddr = myprovider.getAddress("4761111"); /* Just get some Terminal on this Address */ Terminal[] terminals = origaddr.getTerminals(); if (terminals == null) { System.out.println("No Terminals on Address."); System.exit(0); } origterm = terminals[0]; } catch (Exception excp) { // Handle exceptions; } /* * Create the telephone call object and add an observer. */ Call mycall = null; try { mycall = myprovider.createCall(); mycall.addObserver(new MyOutCallObserver()); } catch (Exception excp) { // Handle exceptions }


26

Outgoing Telephone Call Example (Observer based) 7 Apr 1999

/* * Place the telephone call. */ try { Connection c[] = mycall.connect(origterm, origaddr, "5551212"); } catch (Exception excp) { // Handle all Exceptions } }}

Outgoing Telephone Call Example (Listener based)The following code example places a telephone call using the core Call.connect() method. It looks for thestates provided by the Call Control package.

import javax.telephony.*;

/* * The MyOutCallListener class implements the ConnectionListener * interface and receives all events associated with the Call. */ public class MyOutCallListener implements ConnectionListener { private String msg = "Connection to Address: " + name + " is ";

public void connectionAlerting(ConnectionEvent event){ System.out.println(msg + "ALERTING"); }

public void connectionConnected(ConnectionEvent event){ System.out.println(msg + "CONNECTED"); }

public void connectionCreated(ConnectionEvent event){ System.out.println(msg + "CREATED"); } public void connectionDisconnected(ConnectionEvent event){ System.out.println(msg + "DISCONNECTED"); }

public void connectionFailed(ConnectionEvent event){ System.out.println(msg + "FAILED"); }

public void connectionInProgress(ConnectionEvent event){ System.out.println(msg + "INPROGRESS"); }

public void connectionUnknown(ConnectionEvent event){ System.out.println(msg + "UNKNOWN"); }

public void callActive(CallEvent event){


27

7 Apr 1999Outgoing Telephone Call Example (Listener based)

} public void callInvalid(CallEvent event){ }

public void callListenerEnded(CallEvent event){ } public void callMetaMergeStarted(CallEvent event){ }

public void callMetaTransferStarted(CallEvent event){ }

public void callMetaTransferEnded(CallEvent event){ }

}

import javax.telephony.*;import MyOutCallListener;

/* * Places a telephone call from 476111 to 5551212 */public class Outcall { public static final void main(String args[]) { /* * Create a provider by first obtaining the default implementation * of JTAPI and then the default provider of that implementation. */ Provider myprovider = null; try { JtapiPeer peer = JtapiPeerFactory.getJtapiPeer(null); myprovider = peer.getProvider(null); } catch (Exception excp) { System.out.println("Can’t get Provider: " + excp.toString()); System.exit(0); } /* * We need to get the appropriate objects associated with the * originating side of the telephone call. We ask the Address for * a list of Terminals on it and (arbitrarily) choose the first. */ Address origaddr = null; Terminal origterm = null; try { origaddr = myprovider.getAddress("4761111"); /* Just get some Terminal on this Address */ Terminal[] terminals = origaddr.getTerminals(); if (terminals == null) {


28

Outgoing Telephone Call Example (Listener based) 7 Apr 1999

System.out.println("No Terminals on Address."); System.exit(0); } origterm = terminals[0]; } catch (Exception excp) {

// Handle exceptions; } /* * Create the telephone call object and add an observer. */ Call mycall = null; try { mycall = myprovider.createCall(); mycall.addConnectionListener(new MyOutCallListener()); } catch (Exception excp) { // Handle exceptions } /* * Place the telephone call. */ try { Connection c[] = mycall.connect(origterm, origaddr, "5551212"); } catch (Exception excp) { // Handle all Exceptions } }}

Incoming Telephone Call Example (Observer based)The following code example illustrates how an application answers a Call at a particular Terminal. Itshows how applications accept calls when (and if) offered. This code example greatly resembles the coreInCall code example.

import javax.telephony.*;import javax.telephony.events.*;

/* * The MyInCallObserver class implements the CallObserver and * recieves all Call-related events. */ public class MyInCallObserver implements CallObserver { public void callChangedEvent(CallEv[] evlist) { TerminalConnection termconn; String name; for (int i = 0; i < evlist.length; i++) { if (evlist[i] instanceof TermConnEv) { termconn = null;


29

7 Apr 1999Incoming Telephone Call Example (Observer based)

name = null; try { TermConnEv tcev = (TermConnEv)evlist[i]; Terminal term = termconn.getTerminal(); termconn = tcev.getTerminalConnection(); name = term.getName(); } catch (Exception excp) { // Handle exceptions. }

String msg = "TerminalConnection to Terminal: " + name + " is "; if (evlist[i].getID() == TermConnActiveEv.ID) { System.out.println(msg + "ACTIVE"); } else if (evlist[i].getID() == TermConnRingingEv.ID) { System.out.println(msg + "RINGING"); /* Answer the telephone Call using "inner class" thread */ try { final TerminalConnection _tc = termconn; Runnable r = new Runnable() { public void run(){ try{ _tc.answer(); } catch (Exception excp){ // handle answer exceptions } }; }; Thread T = new Thread(r); T.start(); } catch (Exception excp) { // Handle Exceptions; } } else if (evlist[i].getID() == TermConnDroppedEv.ID) { System.out.println(msg + "DROPPED"); } } } }}

import javax.telephony.*;import javax.telephony.events.*;import MyInCallObserver;

/* * Create a provider and monitor a particular terminal for an incoming call. */public class Incall { public static final void main(String args[]) {


30

Incoming Telephone Call Example (Observer based) 7 Apr 1999

/* * Create a provider by first obtaining the default implementation of * JTAPI and then the default provider of that implementation. */ Provider myprovider = null; try { JtapiPeer peer = JtapiPeerFactory.getJtapiPeer(null); myprovider = peer.getProvider(null); } catch (Exception excp) { System.out.println("Can’t get Provider: " + excp.toString()); System.exit(0); } /* * Get the terminal we wish to monitor and add a call observer to that * Terminal. This will place a call observer on all call which come to * that terminal. We are assuming that Terminals are named after some * primary telephone number on them. */ try { Terminal terminal = myprovider.getTerminal("4761111"); terminal.addCallObserver(new MyInCallObserver()); } catch (Exception excp) { System.out.println("Can’t get Terminal: " + excp.toString()); System.exit(0); } }}

Incoming Telephone Call Example (Listener based)The following code example illustrates how an application answers a Call at a particular Terminal. Itshows how applications accept calls when (and if) offered. This code example greatly resembles the coreInCall code example.

import javax.telephony.*;

private String msg = "TerminalConnection to Terminal: " + name + " is ";

/* * The MyInCallListener class implements the TerminalConectionListener * and recieves all Call-related events. */ public class MyInCallListener implements TerminalConnectionListener { public void terminalConnectionActive(TerminalConnectionEvent event){ System.out.println(msg + "ACTIVE"); }

public void terminalConnectionCreated(TerminalConnectionEvent event){ }

public void terminalConnectionDropped(TerminalConnectionEvent event){ System.out.println(msg + "DROPPED"); }


31

7 Apr 1999Incoming Telephone Call Example (Listener based)

public void terminalConnectionPassive(TerminalConnectionEvent event){ }

public void terminalConnectionRinging(TerminalConnectionEvent event){

System.out.println(msg + "RINGING"); TerminalConnection termconn = event.getTerminalConnection();

/* Answer the telephone Call using "inner class" thread */ try { final TerminalConnection _tc = termconn; Runnable r = new Runnable() { public void run(){ try{ _tc.answer(); } catch (Exception excp){ // handle answer exceptions } } } Thread T = new Thread(r); T.start(); } catch (Exception excp) { // Handle Exceptions; } }

public void terminalConnectionUnknown(TerminalConnectionEvent event){

public void connectionAlerting(ConnectionEvent event){ System.out.println(msg + "ALERTING"); }

public void connectionConnected(ConnectionEvent event){ System.out.println(msg + "CONNECTED"); }

public void connectionCreated(ConnectionEvent event){ System.out.println(msg + "CREATED"); } public void connectionDisconnected(ConnectionEvent event){ System.out.println(msg + "DISCONNECTED"); }

public void connectionFailed(ConnectionEvent event){ System.out.println(msg + "FAILED"); }

public void connectionInProgress(ConnectionEvent event){ System.out.println(msg + "INPROGRESS"); }

public void connectionUnknown(ConnectionEvent event){ System.out.println(msg + "UNKNOWN"); }


32

Incoming Telephone Call Example (Listener based) 7 Apr 1999

public void callActive(CallEvent event){ } public void callInvalid(CallEvent event){ }

public void callListenerEnded(CallEvent event){ } public void callMetaMergeStarted(CallEvent event){ }

public void callMetaTransferStarted(CallEvent event){ }

public void callMetaTransferEnded(CallEvent event){ }

}

import javax.telephony.*;import MyInCallListener;

/* * Create a provider and monitor a particular terminal for an incoming call. */public class Incall { public static final void main(String args[]) { /* * Create a provider by first obtaining the default implementation * of JTAPI and then the default provider of that implementation. */ Provider myprovider = null; try { JtapiPeer peer = JtapiPeerFactory.getJtapiPeer(null); myprovider = peer.getProvider(null); } catch (Exception excp) { System.out.println("Can’t get Provider: " + excp.toString()); System.exit(0); } /* * Get the terminal we wish to monitor and add a call observer to * that Terminal. This will place a call observer on all call * which come to that terminal. We are assuming that Terminals * are named after some * primary telephone number on them. */ try { Terminal terminal = myprovider.getTerminal("4761111"); terminal.addCallCallListenerClass(MyInCallListener()); } catch (Exception excp) { System.out.println("Can’t get Terminal: " + excp.toString());


33

7 Apr 1999Incoming Telephone Call Example (Listener based)

System.exit(0); } }}

Security in JTAPIJTAPI peer implementations use the Java "sandbox" model for controlling access to sensitive operations.Callers of JTAPI methods are categorized as "trusted" or "untrusted", using criteria determined by theruntime system. Trusted callers are allowed full access to JTAPI functionality. Untrusted callers arelimited to operations that cannot compromise the system’s integrity.

JTAPI may be used to access telephony servers or implementations that provide their own securitymechanisms. These mechanisms remain in place; parameters such as user name and password areprovided through parameters on the JtapiPeer.getProvider() method.

Appendix

JTAPI DefinitionJTAPI is the set of classes, interfaces, and principles of operation that constitute a standard Java extensionpackage in the javax.* name space. JTAPI is the interface between Java computer telephony applicationsand telephones or telephone system implementations. JTAPI provides access to one or more of thefollowing areas of functionality: Call Control, Telephone Physical Device Control, Media Services forTelephony, and Administrative Services for Telephony.

Applications using the JTAPI interface include (but are not limited to):

Call logging and tracking software Auto-dialing software Screen-based telephone applications Screen-pop software Call routing applications Automated attendants Interactive Voice Response (IVR) systems Agent software Call center management software Fax send and receive Voicemail

Telephony platforms supporting these applications by providing JTAPI include (but are not limited to):

Individual telephone sets (both wired and wireless) PBXs and CT Servers based on circuit switching technology Elements of IP Telephony (and other packet voice networks) including endpoints, gateways, mediaservices servers, and call control implementations Computer platforms and software applications utilizing other call control (CTI) and media services


34

Security in JTAPI 7 Apr 1999

APIs or protocols

JTAPI is an interface that allows value-add telephony software products to be developed to run on anyproduct implementation that exposes a JTAPI interface. JTAPI applications are portable between differenttelephony products. For example, the same JTAPI application can run on a cellular phone and a mediaserver on a VoIP network if both expose a JTAPI interface. JTAPI makes this possible by presenting anabstraction of telephony services that is independent of a given implementation’s underlying network andits relationship to that network.

JTAPI provides access to the following areas of functionality:

Call Control

Call Control refers to control and observation over call control functionality (such as address translation,call setup, call tear down, call routing, supplementary services, and access to call associated information).This includes support for wired and wireless implementations from those with the simplest call controlfeatures to those with the full suite of PBX/ACD call control functionality. It also applies toimplementations which provide JTAPI access to only a single telephony device (e.g. first party) and thosewhich provide access spanning multiple devices (e.g. third party).

Telephone Physical Device Control

Physical Device Control includes monitoring and control over one or more user interface elements of atelephone including: its display, buttons and lamps (real and virtual), auditory components, hook switchesassociated with physical telephone devices independent of call control functionality.

Media Services for Telephony

Media Services includes manipulation and processing of the media streams associated with calls(including tone generation and detection, fax processing, recording and playback, text to speech,automatic speech recognition, etc.).

Administrative Services for Telephony

Start-up, shut-down, and management (fault, configuration, accounting, performance and security) oftelephony resources providing functionality through the JTAPI interface.

JTAPI is used to access the functionality of a telephone system, and could be used between the moduleswithin an implementation, however not all the functionality required to implement a telephone system isincluded. JTAPI does not expose individual signalling protocols (such as SS7, ISDN, GSM, etc.) andassociated features that a particular telephone or telephone system implementation is likely to needinternally. Nor does it include non-telephony services that Java-based telephones are likely to need (suchas interfaces to draw a telephone user interface on a bitmapped display). Implementations which intend toexpose other types of functionality such as power management, messaging, web browsing, SNMPsupport, access to device-specific functions, etc., will use other complementary Java interfaces to do so.


35

7 Apr 1999JTAPI Definition

The scope of JTAPI corresponds to the top-most layer of interfaces defined by the ECTF architecturalframework and encompasses the functionality of the call control (C.xxx), media services (S.xxx), andadministrative services (M.xxx) areas. For further information, refer to the ECTF architectural framework(described in documents available at http://www.ectf.org/ectf/tech/tech.htm).

The Tao of JTAPIJTAPI has these guiding principles:

JTAPI should maximize telephony application portability. This is achieved through the choice ofJava as a language binding as well as through the abstraction of first-party versus third-party callcontrol. JTAPI should be scaleable from PDAs, cellular phones, and set-top boxes, to desktop applications, tolarge call centers. JTAPI should be simple. The call model targets transitions of real-world objects, not services whichcan be built on those transitions. JTAPI should be compatible with the C.001 Call Model - although both are evolving. JTAPI should be extensible . JTAPI 1.1 covers a small subset of (say) CSTA services, but JTAPIshould be defined in a way that allows extensions to be defined that cover these services. JTAPI should be implementable on existing telephony APIs, such as TAPI, TSAPI, SunXTL,CallPath, and S.100.

Frequently Asked Questions

What is the scope of JTAPI?

>From Jim Wright’s presentation at 1997’s JavaOne conference: JTAPI " Enables portable JavaTMapplications to setup, control and tear down calls (and control their associated data streams) to and frompublic and private networks, on a broad spectrum of host telephony platforms".

It’s important to note that JTAPI isn’t just a call control API - it also controls associated media streams.Providing a single API that covers both these areas is one of JTAPI’s design goals.

What is the relationship of JTAPI to other telephony APIs?As shown in Figure 6, JTAPI is independent of existing telephony APIs, but can be implemented usingthese APIs as primitives.Most of the JTAPI implementations we are aware of are based on these APIs, butas shown in Figure 6, JTAPI can be implemented entirely in Java if a switching platform supports this.

We should mention that diagrams like this may give the impression that the JTAPI implementation has torun on the same platform as an existing telephony API, but this isn’t true. Figure 7 shows a very typicalimplementation architecture, called "thin-client", which uses Java’s Remote Method Invocation (RMI)technology to access a telephony server across a network. Other networking technologies could be used aswell (JOE, etc.), as long as the client and the server understand the same technology. JTAPI is neutral onthis issue.


36

The Tao of JTAPI 7 Apr 1999

Where can I get the class files for JTAPI?

The JTAPI API provides a unified view of diverse underlying telephony environments. For instance, theJTAPI call model can express either first-party or third-party call control, although underlyingimplementations will typically support one or the other.

This diversity, hidden from applications, falls squarely on JTAPI implementers. We believe it’s infeasibleto write a JTAPI implementation that is portable across the underlying telephony APIs.

So, unlike many Java APIs, you don’t download Java class files and run your application. JTAPI requiresan implementation, specific to your telephony environment, in order to function. To meet thisrequirement, vendors provide JTAPI implementations that run in specific telephony environments.

What Java packages are included in JTAPI?JTAPI uses a "core plus extensions" structure. The packages included in JTAPI 1.1.1 are:

package javax.telephony - This package is "Core JTAPI". It includes all call model objects used inJTAPI, and specifies the methods any application can assume on any JTAPI-conformingimplementation. Any JTAPI implementation must support Core JTAPI. package javax.telephony.callcenter - This package extends Core JTAPI to provide the following keyCall Center features: Routing, Automatic Call Distribution (ACD) , Predictive Calling, andApplication Data. package javax.telephony.callcontrol - This package extends Core JTAPI to provide more informationabout the call model, and to support advanced services like conferencing. package javax.telephony.phone - This package permits implementations to describe physicalTerminals in terms of standardized components. Applications may query each Terminal, using thispackage, for the components that make up the Terminal, and applications may control certainattributes of these components, such as speaker volume. package javax.telephony.privatedata - This package enables applications to communicate datadirectly with the underlying hardware switch. This data may be used to instruct the switch to performa switch-specific action. Additional applications may use this package to "piggy-back"implementation-specific data onto Java Telephony API objects. Note: Use of this package effectivelyties an application to a specific underlying implementation.

Each of these packages has two associated packages - "events", which describes the events observers see,and "capabilities", which describes the methods applications use to find out whether certain actions maybe performed.

These packages are available from http://java.sun.com/products/jtapi/index.html.

JTAPI 1.2 adds (with associated "events" and ""capabilities"):

package javax.telephony.media - This package provides applications access to the media on thetelephone line. A wide variety of media-centric telephony applications exist today, includingworkstation answering machines, IVR systems, PPP daemons, and fax applications. Thispackage provides support for these types of media telephony applications.


37

7 Apr 1999What Java packages are included in JTAPI?

What do implementers need to implement?At the very least, implementers must support the javax.telephony, javax.telephony.capabilities, andjavax.telephony.events packages. These packages constitute "Core JTAPI".

Additional packages may be supported as necessary.

Is JTAPI "blocking" or "non-blocking"?The correct answer is "yes".

JTAPI has design goals of minimizing application complexity and portability. Most JTAPI methods donot immediately return control to the application. Instead, most methods guarantee "post-conditions" whenthey return control to the application.

These post-conditions are documented in comments on each method in the detailed specification.

For instance, javax.telephony.connection.disconnect() guarantees that, when control is returned to theapplication, the connection has been DISCONNECTED, and the associated terminal connection has beenDROPPED (among other post-conditions).

This approach requires application execution threads to block until these post-conditions are met. Theapplication doesn’t have to check to make sure these state transitions are really happening.

So JTAPI is, strictly speaking, blocking. Application developers are responsible for knowing when theirapplications are likely to suspend execution. In particular, observer event delivery threads should notmake potentially blocking JTAPI method calls, because this could lead to circular waiting deadlocks (theobserver is waiting on the response to the method call, which the implementation can’t deliver because theobserver is blocked).

The exception to this rule is that JTAPI methods tend to wait on machines, but not on humans.Javax.telephony.connection.disconnect() waits until the connection is actually disconnected, because thishappens fairly rapidly. Javax.telephony.call.connect() does not wait until the call is actually connected,because this would block the application while the called party wakes up, gets out of bed, walks down thehall, and answers the phone.

And this is why a blocking API also uses an "entity-observer-event" model!

Why are there so many kinds of observers?

This question can be answered at two levels:

Applications may be interested in a logical connection endpoint - an Address - or a physical connectionendpoint - a Terminal. Think of being interested in a phone number, which could appear on many phonesets, versus being interested in a single phone set. That’s why there are both Address and Terminalobservers.


38

What do implementers need to implement? 7 Apr 1999

Some environments may restrict the application’s ability to monitor calls as they move fromaddress/terminal to address/terminal. In many cases, different "monitors" are used by the underlyingimplementation, depending on whether the application is interested in the call while it’s at a specificaddress/terminal, or interested in the call through the life of the call. That’s why call observers must be"extended" to remain in place when the call leaves an address/terminal. 22

How can I make JTAPI do "X"?

JTAPI doesn’t cover every possible situation in every possible telephony environment, and it never will.

JTAPI wasn’t designed top-down, to anticipate all requirements of computer telephony. The contents ofJTAPI to date have been determined pragmatically. When people working on the specificationencountered a situation or application that isn’t covered, they contribute proposals extending JTAPI, and,if there is sufficient interest, the specification is extended to include these proposals as modified by the"JTAPI team".

If JTAPI would be perfect for your application except that it doesn’t "do X", these are the suggestedguidelines:

Make sure JTAPI really doesn’t "do X". JTAPI is pretty flexible. For example, several proposals forextensions to cover conferencing situations have been withdrawn because JTAPI applications canhold() any TerminalConnection or disconnect() any Connection in the conference - not just "the near end".

Raise this deficiency as an issue, especially if it’s not obvious how to map "X" onto JTAPI. Forinstance, a proposed CallControlCall.swap() method was accepted for JTAPI 1.2 because someunderlying telephony systems require you to hold an active call before you can unhold an inactivecall (because they won’t let you have two active calls at once), while others prevent you from doingso (because they won’t let you have two held calls at once) - so there was no way to alternatebetween calls portably.

Define "X" in the most general terms possible. It’s more likely we’ll extend JTAPI to make a"high-speed data call" than to make a "19.2 Kb/s data call", because applications will be moreportable if they request "the highest speed connection your implementation supports".

Identify the market segments affected by the deficiency. This helps determine the amount ofenthusiasm for removing the deficiency.

If "X" exists only in a limited market segment, consider extending JTAPI using your own "reverseddomain name package" ("COM.grommet.DialAndNuke" for the interface to dial into yourmicrowave oven). Most of the interesting JTAPI objects are specified as interfaces, and there’s noproblem if implementations create JTAPI objects that implement additional interfaces.24 If "X" turnsout to be interesting and widely deployed, the methods you specified can be "added back" to theJTAPI specification fairly easily.


39

7 Apr 1999Is JTAPI "blocking" or "non-blocking"?

JTAPI Pitfalls and Development TipsThis sections contains information on some common JTAPI pitfalls and develop tips.

Check CapabilitiesTelephony environments vary widely in their functionality. JTAPI cannot reduce this variation, howeverJTAPI provides ability to check the capabilities of the telephony environment.

Well behaved JTAPI applications check capabilities at initialization time.

JTAPI application can still be well behaved if they catch the MethodNotSupportedException.

Applications should be flexible in how they respond to reduced or unavailable capabilities.

JTAPI has static and dynamic capabilities. Static can be determined at initialization time Dynamiccapabilities depend on the current state of the call model .

Observer Event Threads & Blocking MethodsJTAPI, strictly speaking, is a blocking API and most JTAPI methods dont return immediately. Instead,methods guarantee post conditions. Application developers are responsible for knowing when theirapplications are likely to suspend execution. In particular, event observer threads should not makepotentially blocking calls. This could lead to deadlock. Use "anonymous inner classes", defined in JDK1.1, to create a background thread to avoid making blocking JTAPI calls in Observer code. An example ofan anonymous inner class is provided below.

public class ExampleObserver { ...//anonymous inner class

(new Runnable() { public void run() {

// blocking method call } }).start();

. . .

}

Use instanceOf() to get exact object typeWhen using the core plus one or more extensions the object type returned by a Provider method could be:

a core object (e.g. call, terminal) an extension object (e.g. CallCenterCall)


40

JTAPI Pitfalls and Development Tips 7 Apr 1999

Use instanceOf() to check the exact object type if the extension objects functionality is to be used.

getProvider() PitfallA potentially dangerous way to get a provider object is:

Provider myProvider = JtapiPeerFactory.getJtapiPeer(null).getProvider();

The JtapiPeer object instantiated by an application may be garbage collected before another applicationcalls JtapiPeerFactory.getJtapiPeer(null).getProvider(). If this happens, a new/different instance ofProvider will be created. This may not be a desirable outcome to the JTAPI applications if they assume toshare the same call tree.

A safer way to get a JTAPI provider is:

JtapiPeer myJtapiPeer = JtapiPeerFactor.getJtapiPeer(null); Provider myProvider = myJtapiPeer.getProvider();<

Note that the reference, myJtapiPeer, to the instance of JtapiPeer should be kept for the life of the Providerreferenced by myProvider. A way to do this is to keep a reference to the provider in the in the peer and areference to the peer in the JVM-wide System.properties. Not pretty but it works.

Be careful when using extension eventsThere is currently no way to query the peer/provider for what events it may send out. Not all events for anextension package may be supported by the implementation. It is best to depend on core events, but beready to take full advantage of non-core events when they happen, For example, suppose an applicationassumes a call-control extension is available expects to get an CallCtlConnOfferedEv prior to aTermConnRingingEv so the application can prepare for an incoming call. But some providers don’tsupport ISDN and therefore may not issue a CallCtlConnOfferedEv. The application may not handle justreceiving a TermConnRingingEv correctly. The application is dependant on an CallCtlConnOfferedEvthat might not ever appear, although there is no way to know in advance.

Don’t count on Meta-Events.Meta-events are not required to be supported. Meta event semantics are vaguely defined in JTAPI 1.2.JTAPI 1.3 has layed a foundation defining and clarifying precisely when meta events arrive and what theirrole is, and JTAPI 2.0 will go further to flexibly define how extension packages can extend meta events.The start and end boundaries of meta-event are not precisely defined. JTAPI 2.0 will more preciselydefine meta-events

Examine all events in a batch before acting.

Search through a batch of event before acting for on any. Find the ’big ones (e.g. TermConnDroppedEv).This will prevents unnecessary event processing work.


41

7 Apr 1999getProvider() Pitfall

Overview

Table of Contents............... 1JavaTM Telephony Specification............. 3The Java Telephony API (JTAPI) Overview................. 3Changes in JTAPI 1.3............. 3Rationale for a Java-based Telephony API................... 3Why Java?................... 4Why JTAPI?................... 4Architecture................... 5JTAPI Peer.............. 7Core Plus Extension Architecture.................... 8Packages.................... 9Core................... 9Call Control................... 10Call Center.................... 10Media.................... 10Mobile.................... 11Phone................... 11Private Data................... 11Call Model................... 11Core Objects.................... 13Provider..................... 13Call.................... 13Address................... 13Connection................... 13Terminal................. 13TerminalConnection................... 14Capabilities.................... 15Events................... 15Event Basics................... 16Meta-Events................ 16The Listener Event Model................. 16Listener Interfaces.................. 17Listener Events............. 17When Call Event Transmission Ends................. 17Event Granularity.......... 17Registering Call Listeners via Address and Terminal................. 18Listener Meta-Events............... 18The Observer Event Model................. 19Adding Observers.................. 19Observer Events.................. 19Core Methods................... 20Call States


i

7 Apr 1999

................. 21Connection States

.............. 22TerminalConnection Object States

................. 23Obtaining a Provider

.................. 24Call Scenarios

.......... 25Outgoing Telephone Call Example (Observer based)

.......... 27Outgoing Telephone Call Example (Listener based)

.......... 29Incoming Telephone Call Example (Observer based)

.......... 31Incoming Telephone Call Example (Listener based)

................. 34Security in JTAPI

................... 34Appendix

.................. 34JTAPI Definition

................. 36The Tao of JTAPI

............... 36Frequently Asked Questions

............... 36What is the scope of JTAPI?

........ 36What is the relationship of JTAPI to other telephony APIs?

............ 37Where can I get the class files for JTAPI?

............ 37What Java packages are included in JTAPI?

............ 38What do implementers need to implement?

............. 38Is JTAPI "blocking" or "non-blocking"?

........... 38Why are there so many kinds of observers?

.............. 39How can I make JTAPI do "X"?

............. 40JTAPI Pitfalls and Development Tips

................. 40Check Capabilities

........... 40Observer Event Threads & Blocking Methods

............ 40Use instanceOf() to get exact object type

................. 41getProvider() Pitfall

............. 41Be careful when using extension events

............... 41Don’t count on Meta-Events.

........... 41Examine all events in a batch before acting.


ii

7 Apr 1999

java telephony api pdf

Documents