JavaTM Telephony Specification

7 Apr 1999

Java TM Telephony Specification

The 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

Early Access 1 1

JTAPI version 1.3

7 Apr 1999

JavaTM Telephony Specification

Java Telephony API 1.3

javax.telephony The Java Telephony API (JTAPI) is a portable, object-oriented application programming interface for Java-based computer-telephony applications. This document is an overview of the Call Center Extension Package to the Java Telephony API. JTAPI Call Center capabilities. JTAPI Call Center events package. This document provides an overview of the Call Control Extension Package to the Java Telephony API.

javax.telephony.callcenter javax.telephony.callcenter.capabilities javax.telephony.callcenter.events javax.telephony.callcontrol

javax.telephony.callcontrol.capabilities JTAPI Call Control capabilities. javax.telephony.callcontrol.events javax.telephony.capabilities javax.telephony.events javax.telephony.media javax.telephony.media.capabilities javax.telephony.media.events javax.telephony.mobile JTAPI Call Control capabilities. JTAPI Core capabilities package. JTAPI Core events overview. This document is an overview of the Media services package to the Java Telephony API. JTAPI Media capabilities packae JTAPI Media application events package. The JTAPI Mobile package extends the core capabilities of a JTAPI implementation with capabilities specific to mobile networks. This document provides an overview of the Phone Extension Package to the Java Telephony API. JTAPI Phone capabilities package. JTAPI Phone events package. JTAPI Private Data package

javax.telephony.phone javax.telephony.phone.capabilities javax.telephony.phone.events javax.telephony.privatedata

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

The Java Telephony API (JTAPI) Overview

7 Apr 1999

The Java Telephony API (JTAPI) Overview

The Java Telephony API (JTAPI) is a portable, object-oriented application programming interface for Java-based computer-telephony applications. JTAPI is comprised of a set of classes, and interfaces that constitute an optional Java extension package in the javax.* name space. JTAPI is the interface between Java computer telephony applications and telephones or telephone system implementations. JTAPI serves a broad audience, from call center application developers to web page designers. JTAPI supports both first- and third-party telephony application domains. The API is designed to make programming simple applications easy, while providing those features necessary for advanced telephony applications. The Java Telephony API is, in fact, a set of APIs. The "core" API provides the basic call model and rudimentary telephony features, such as placing telephone calls and answering telephone calls. The core API 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 are described later in this document. Applications written using the Java Telephony API are portable across the various computer platforms and telephone systems. Implementations of JTAPI will be available for existing computer-telephony integration platforms such as Sun Microsystems SunXTL, Microsoft and Intels TAPI, Novell and Lucents TSAPI, and IBMs CallPath. Additionally, independent hardware vendors may choose to provide implementations of the Java Telephony API on top of their own proprietary hardware.

Changes in JTAPI 1.3

JTAPI 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 event pattern has not been deprecated, prepare for that eventuality in JTAPI 2.0. The intent is to fully support 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. The JTAPI 1.2 methods are deprecated. A mobile package is now available to address the special needs of mobile telephony. The mobile packages 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 application portability across vendor implementations. "Application Portability" is literal - the application itself, in compiled form, may be loaded onto any conforming implementation and executed.

Early Access 1 3

JTAPI version 1.3

7 Apr 1999

Architecture

The Java programming language is used for this specification because of its support for "write once, run anywhere" application development. JTAPI implementations may not be portable. They may be very closely tied to a specific telephony environment, and in fact may rely heavily on "native code". JTAPI applications may be portable. For instance, 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 variety of 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 be knowledgeable about telephony, but reduces the amount of implementation-specific knowledge required to develop applications. The range of "targets" for JTAPI ranges from the largest call centers, to desktop systems, to network computers, to "network telephones". This range is the reason for the "core plus extensions" organization of JTAPI, discussed later. JTAPI blurs borders. It blurs the distinction between first-party and third-party call control, and it blurs the distinction between call control and media control. JTAPI isnt "just another telephony API" - although JTAPI can be implemented without existing telephony APIs, it was also designed to allow implementers to build on top of these existing telephony APIs. 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 telephony applications Interfaces applications directly to service providers or acts as a Java interface to existing telephony APIs, 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

Architecture
JTAPI enables portability of telephony applications, for both public and private networks, across a broad spectrum of telephony platforms. To achieve this portability, JTAPI users two architectural concepts: The JTAPI Peer The Core Plus Extension Architecture

JTAPI version 1.3

Early Access 1 4

JTAPI Peer

7 Apr 1999

JTAPI Peer
An implementation of JTAPI for a particular telephony platform is called a Peer. Examples of peer telephony 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 telephony platform peer as shown in Figure 1. The peer represents the telephony systems operating system (OS) and the hardware of the platform.

Figure 1 JTAPI Peer An application accesses the functionality of the peer through the programming interfaces provided by JTAPI and the JVM. Figure 1 depicts a simplified, centralized, pure JTAPI implementation. JTAPI is not restricted to this model. 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 Lucent Passageway. As shown in Figure 2, JTAPI can also be implemented on top these API.

Early Access 1 5

JTAPI version 1.3

7 Apr 1999

JTAPI Peer

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

JTAPI version 1.3

Early Access 1 6

Core Plus Extension Architecture

7 Apr 1999

Figure 3 Distributed JTAPI

Core Plus Extension Architecture

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

Early Access 1 7

JTAPI version 1.3

7 Apr 1999

Packages

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, the new JTAPI 1.3 media packages can be implemented independent from the core.

Packages
The Java Telephony API is composed of a set of Java language packages. Each package provides a specific piece of functionality for certain aspect of computer-telephony applications. The core package is required by most JTAPI implementations. The other packages are optional. Implementations of telephony servers choose the optional packages they support based upon the capabilities of their underlying platform and hardware. All JTAPI packages are in the javax.telephony name hierarchy. The packages defined in JTAPI 1.3 are:

JTAPI version 1.3

Early Access 1 8

Core

7 Apr 1999

Core package Call Control Call Center Media Mobile Phone Private Data

javax.telephony javax.telelphone.callcontrol javax.telelphone.callcenter javax.telelphone.media javax.telelphone.mobile javax.telelphone.phone javax.telelphone.privatedata

Core
The javax.telephone package, or core package, contains the coreinterfaces. The core package provides the basic framework to model telephone calls and rudimentary telephony features. These features include placing 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 to concern 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 Control
The javax.telephony.callcontrol package extends the core package by providing more advanced call-control features and a more detailed state model of telephone calls. The additional calling features include: conference calling transfer forwarding call hold call join message waiting do not disturb call park & pickup

Early Access 1 9

JTAPI version 1.3

7 Apr 1999

Call Center

Call Center
The javax.telephony.callcenter package provides applications the ability to perform advanced features necessary 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.)

Media
The javax.telephony.media package provides application the ability to manipulate media streams associated with calls. For JTAPI 1.3, a new media API that implements the ECTF S.410 specification has been added. This version of JTAPI media API is designed as a complete replacement for the media package defined in JTAPI 1.2. It matches the ECTF model of a CTI server that supports multi-vendor applications and shared resources in an enterprise environment, but it can also be effectively used on single-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 fax servers 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 media package is defined to ensure there are no namespace overlaps allowing the coexistence of both packages for a transition period.

Mobile
The javax.telephony.mobile package provides features required for applications running on mobile telephones or within a mobile telephone network environment. JTAPI Mobile extends core JTAPI with the following mobile network functionality: Mobile Call Control, Mobile Network Access and Control Media Services for Mobile Applications

JTAPI version 1.3

Early Access 1 10

Call Model

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

Phone
The javax.telephony.phone package permits applications to control the physical features of telephone hardware phone sets. Implementations may describe Terminals as collections of components, where each of these component-types has interfaces in this package. The phone package provides interfaces to model: buttons displays lamps ringers hook switches speakers microphones

Private Data
The javax.telephony.privatedata package enables applications to communicate data directly with the underlying hardware switch. This data may be used to instruct the switch to perform a switch-specific action. Applications may also use the package to "piggy-back" a piece of data with a Java Telephony API object.

Call Model
The 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 Objects
The 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 endpoints together. 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.

Early Access 1 11

JTAPI version 1.3

7 Apr 1999

Core Objects

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 call model objects is to describe telephone calls and the endpoints involved in a telephone call. These call model objects are related to one another in specific ways, which is summarized below and described in more detail in the core package specification. Figure 5 shows the JTAPI call model and the objects that compose the call model. A description of each object follows the figure.

Figure 5 Call Model

JTAPI version 1.3

Early Access 1 12

Provider

7 Apr 1999

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

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

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

Connection
A Connection object models the communication link between a Call object and an Address object. This relationship is also referred to as a "logical" view, because it is concerned with the relationship between the 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 states are summarized later.

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

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

Early Access 1 13

JTAPI version 1.3

7 Apr 1999

Capabilities

Capabilities
Telephony environments vary widely in their ability to perform certain functions. This variation may reflect technical considerations or administrative considerations. JTAPI does nothing to reduce this variation (if you dont subscribe to a conferencing feature, JTAPI wont changethis). What JTAPI does do is provide a mechanism for finding out exactly what an application (which, after all, may have been downloaded over the Internet) can do in its current execution environment. This mechanism, taken from existing telephony APIs, is called Capabilities. The javax.telephony.capabilities package contains the mechanisms that allow applications to query whether certain actions may be performed. Capabilities take two forms: Static capabilities indicate whether an implementation, or a specific call model object, supports a method (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 is an 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 and go. For this reason, a well-behaved JTAPI application will query relevant capabilities at initialization time, in order to "gray out" unsupported/unavailable features in user interface displays, but will check again when preparing to invoke the relevant method. This will minimize the number of exceptions the application will encounter. A JTAPI application can still be "well-behaved" without checking capabilities, as long as it catches MethodNotSupportedException and InvalidStateException. This approach is simple, but does not allow the application to present an accurate user interface (the user may attempt actions which arent allowed by the implementation). Capabilities are aligned one-to-one with methods; if a method isnt implemented in all environments, a capability 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

JTAPI version 1.3

Early Access 1 14

Events

7 Apr 1999

Because call model objects in JTAPI extension packages support additional methods, these packages have associated 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 to the user that all the methods in the interface are supported. In the latter case, the instanceOf operator can be used to determine if an interface is present.

Events
JTAPI applications need to know about state changes in call model objects that arent the result of anything the application has done. For instance, an application may want to know when an incoming call has arrived at a specific terminal in order to update a users view of that terminal on a graphical user interface. 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. In JTAPI 1.2 and earlier releases, JTAPI only supported the observer event model. The addition of the listener event model brings JTAPI up to date with the latest Java technology. In a future JTAPI 2.0 release, all JTAPI packages will support the listener event model and the observer model will be deprecated.

Event Basics
The JTAPI call model is a loosely coupled finite state machine. To use this model, there are six concepts with which one must be familiar: Entity: A Call model object, provided to model the capabilities (and current activities) of an external telephony system, which is directly controlled by a telephony platform and affected by external Call activity. State: The operational condition of an Entity in the Call model, or of the Call model taken as a whole. Event: A report to an application that an Entity has changed State, modeling a change in state of the external 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. Applications interested 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

Early Access 1 15

JTAPI version 1.3

7 Apr 1999

Meta-Events

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

Meta-Events
Meta-event are events that transcend other related, subordinate events. For example, a call transfer meta-event could imply call-hold, call-ringing, call-answer, and call-release events. All of the subordinate events could have occurred as part of the transfer event. An application may only see that a transfer meta-event has happened. Meta-events are implemented differently in the listener and observer models. The relevant JavaDoc sections should be viewed to see how each model implements meta-events.

The Listener Event Model

Starting 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 to JTAPI core along with add and remove listener methods in JTAPI core object model interfaces.

Listener Interfaces
There 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 listener interfaces. For example, events pertaining to call objects are delivered through objects that implement the CallEvent interface. These objects must register for the events in which they are interested by calling the call model objects add listeners methods. For instance, a object implementing a CallListener would register with the call object of interest by invoking the call objects Call.addListener() method. Connection-related and TerminalConnection-related events are reported via the ConnectionListener and TerminalConnectionListener interfaces respectively extensions of the CallListener interface. These events include the creation of these objects and their state changes. These events extend the ConnectionEvent interface and the TerminalConnectionEvent interface, respectively.

JTAPI version 1.3

Early Access 1 16

Listener Events

7 Apr 1999

Listener Events
An event is delivered to the application whenever the state of the call models changes. There are six listener 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 call become active or goes to an invalid condition. The specific reason for the event generation can be determined from the EventID carried in a CallEvent object. In the CallEvent case, the event IDs corresponding to Call state changes are CallActiveEventID and CallInvalidEventID respectively.

When Call Event Transmission Ends

At 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 an extension of that interface). This is the final event receives by the Listener, and it is no longer reported via the Call.getListeners() method.

Event Granularity
An application controls the granularity of events which are reported by the listener interfaces that it implements. The interfaces are organized in an inheritance hierarchy with the CallListener at the top, the ConnectionListener inheriting from CallListener and finally the TerminalConnectionListener inheriting from ConnectionListener. Each successively lower level in the hierarchy provides more detailed event reporting. The implementation determines what level of events to report by ascertaining which interface has been implemented.

Registering Call Listeners via Address and Terminal

Applications may receive events about a Call by adding an Listener via the Address or Terminal objects using the Address.addCallListener() and Terminal.addCallListener() (and related) methods. These methods provide the ability for an application to receive Call-related events when a Call contains a particular Address or Terminal. In particular, methods exist to add a CallListener, ConnectionListener and TerminalConnectionListener via Address and Terminal. See the specifications for Address and Terminal for more details.

Early Access 1 17

JTAPI version 1.3

7 Apr 1999

Listener Meta-Events

Listener Meta-Events
The listener meta-events are optional high level JTAPI event that provide details of high level call functions. The high level details my pertain to single call or to multiple call operations. Single call meta-events are used to report call-progress details of a call. Mutli-call meta-events are used to report the progress of multi-call operations such as call transfer and conference. JTAPI 1.3 only supports single call meta-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 level operation. 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 of JTAPI event objects, delimited by start and end MetaEvents. An application learns of the details of a state change by processing all the events between the starting and ending MetaEvents. When using meta-events, applications should wait for the matching "ending" MetaEvent to be received before processing the regular events to avoid making an incorrect determination about the state of its associated telephony platform. The specific Meta event is provided by the Event.getID() value returned by the event. The specific Meta event provides context information about the higher-level event.

The Observer Event Model

The Provider, Call, Terminal, and Address objects have Observers. The interfaces corresponding to these observers are ProviderObserver, CallObserver, TerminalObserver, and AddressObserver, respectively. The ProviderObserver reports all state changes to the Provider object. For the core package, state changes are reported when the Provider changes state from OUT_OF_SERVCE, to IN_SERVICE, to SHUTDOWN. The Call observer reports state change information for all Connections and TerminalConnections that are part of the telephone call as well as state changes to the Call itself. These state changes are reported on neither 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 that come to an Address or Terminal. These CallObservers are removed once the call leaves the Address or Terminal. The Address and Terminal observers report any state changes in these objects. In the core package there are no events for these objects. The AddressObserver and TerminalObserver interfaces still exist, however, so other packages may extend these interfaces.

JTAPI version 1.3

Early Access 1 18

Adding Observers

7 Apr 1999

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

Observer Events
The Ev interface is the parent of all JTAPI Observer event interfaces. All JTAPI event interfaces extend this interface, either directly or indirectly. Event interfaces within each JTAPI package are organized in a hierarchical 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. Each individual change in an object is represented by an event sent to the appropriate observer. Because several changes may happen to an object at once, events are delivered as a batch. A batch of events represents a series 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 this identification number for each event. The actual event identification integer is defined in each of the specific 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 returns this 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 Ev interface. Directly extending this interface are those events interfaces for each object which supports an observer: ProvEv, CallEv, AddrEv, and TermEv. Since Connection and TerminalConnection events are reported via the CallObserver interface, the ConnEv and TermConnEv interfaces extends the CallEv interface.

Core Methods
The 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 are Call.connect(), TerminalConnection.answer(), and Connection.disconnect(), respectively.

Early Access 1 19

JTAPI version 1.3

7 Apr 1999

Call States

Call.connect(Terminal, Address, String) Once an application has an idle call object (obtained via Provider.createCall()), it may place a telephone call using the Call.connect() method. The application must specify the originating Terminal (physical endpoint) and the originating Address (logical endpoint) on that Terminal (in the case that a Terminal has multiple telephone numbers on it). It also provides the destination telephone number string. Two Connection objects are returned from the Call.connect() method, representing the originating and destination ends of the telephone call. TerminalConnection.answer() Applications monitor Terminals, with observers or listeners, for the arrival of incoming calls. An incoming telephone call to a Terminal is indicated by a TerminalConnection to that Terminal in the RINGING state (see TerminalConnection states below). At that time, applications may invoke the TerminalConnection.answer() to answer that incoming telephone call. Connection.disconnect() The Connection.disconnect() method is used to remove an Address from the telephone call. The Connection object represents the relationship of that Address to the telephone call. Applications typically invoke this method when the Connection is in the CONNECTED state, resulting in the Connection moving to the DISCONNECTED state. In the core package, application may only remove entire Addresses from the Call, and all of the Terminals associated with that Address which are part of the call are removed as well. The call control extension package provides the ability for application to remove individual Terminals only from the Call.

Call States
A Connection object is always in a state that reflects the relationship between a Call and an Address. The state in which a Connection exists is not only important to the application for information purposes, it is always 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 state transition diagram. This diagram guarantees to application developers the possible states in which the Connection object can transition given some current state. These state transition rules are invaluable to application 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.

JTAPI version 1.3

Early Access 1 20

Connection 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 transition quickly out of the IDLE state into another state. A Connection in the IDLE state indicates that the party has just joined the telephone call in some form. No Core methods are valid on Connections in the 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 an incoming telephone call. CONNECTED state The CONNECTED state indicates that a party is actively part of a telephone call. A Connection in the CONNECTED state implies that the associated party is talking to the other parties on the call or is connected to tone.

Early Access 1 21

JTAPI version 1.3

7 Apr 1999

TerminalConnection Object States

DISCONNECTED state The DISCONNECTED state indicates that a party is no longer a part of a telephone call. No methods are 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 an application uses Call.connect() to place a telephone call to a party who is busy, the Connection associated 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 the present time. A Connection may transition in and out of the UNKNOWN state at any time, unless it is in either the DISCONNECTED or FAILED state. The effects of the invocation of any method on a Connection in this state are unpredictable.

TerminalConnection Object States

The TerminalConnection object represents the relationship between a Terminal and a Connection. As mentioned previously, these objects represent a physical view of the Call, describing which physical Terminal endpoints are part of the telephone call. Similar to Connection objects, TerminalConnection objects have their own set of states and state transition diagram. This state transition diagram, with a brief description of each state follows.

JTAPI version 1.3

Early Access 1 22

Obtaining a Provider

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 for the Connection objects IDLE state. ACTIVE state The ACTIVE state indicates a Terminal is actively part of a telephone call. This often implies that the Terminal handset is off-hook. RINGING state The RINGING state indicates that a Terminal is signaling to a user that an incoming telephone call is present at the Terminal. DROPPED state The DROPPED state indicates that a Terminal was once part of a telephone call, but has since dropped 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. A TerminalConnection in the PASSIVE state indicates that a resource on the Terminal is being used by this telephone call. Packages providing advanced features permit Terminals to join calls from the PASSIVE state. UNKNOWN state The UNKNOWN state indicates that the Provider is unable to determine the current state of a TerminalConnection. It has a similar connotation to that of the Connection objects UNKNOWN state.

Obtaining a Provider
All 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() returns the 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 that applications use to get Provider objects, to query services available on those providers, and to get the

Early Access 1 23

JTAPI version 1.3

7 Apr 1999

Call Scenarios

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 Providers 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 Scenarios
This section is meant to convey a sense of how to use JTAPI to perform basic call control. In this section we will provide you with basic examples that employ JTAPI objects to make an outgoing call and receive an incoming call. Because JTAPI 1.3 supports two event models, the use of both will be illustrated in the following examples. However, the listener model is the preferred event model and you are strongly urged to migrate existing code based on observers to the listener model. The examples will serve to illustrate how to rewrite observer based code as well as use listener based code.

JTAPI version 1.3

Early Access 1 24

Outgoing Telephone Call Example (Observer based)

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 the states 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"); } } } } }

Early Access 1 25

JTAPI version 1.3

7 Apr 1999

Outgoing 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("Cant 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 }

JTAPI version 1.3

Early Access 1 26

Outgoing Telephone Call Example (Listener 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 the states 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){

Early Access 1 27

JTAPI version 1.3

7 Apr 1999

Outgoing 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("Cant 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) {

JTAPI version 1.3

Early Access 1 28

Incoming Telephone Call Example (Observer 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. It shows how applications accept calls when (and if) offered. This code example greatly resembles the core InCall 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;

Early Access 1 29

JTAPI version 1.3

7 Apr 1999

Incoming 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[]) {

JTAPI version 1.3

Early Access 1 30

Incoming Telephone Call Example (Listener 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("Cant 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("Cant 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. It shows how applications accept calls when (and if) offered. This code example greatly resembles the core InCall 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"); }

Early Access 1 31

JTAPI version 1.3

7 Apr 1999

Incoming 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"); }

JTAPI version 1.3

Early Access 1 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("Cant 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("Cant get Terminal: " + excp.toString());

Early Access 1 33

JTAPI version 1.3

7 Apr 1999

Security in JTAPI

System.exit(0); } } }

Security in JTAPI
JTAPI 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 the runtime system. Trusted callers are allowed full access to JTAPI functionality. Untrusted callers are limited to operations that cannot compromise the systems integrity. JTAPI may be used to access telephony servers or implementations that provide their own security mechanisms. These mechanisms remain in place; parameters such as user name and password are provided through parameters on the JtapiPeer.getProvider() method.

Appendix JTAPI Definition

JTAPI is the set of classes, interfaces, and principles of operation that constitute a standard Java extension package in the javax.* name space. JTAPI is the interface between Java computer telephony applications and telephones or telephone system implementations. JTAPI provides access to one or more of the following areas of functionality: Call Control, Telephone Physical Device Control, Media Services for Telephony, 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, media services servers, and call control implementations Computer platforms and software applications utilizing other call control (CTI) and media services

JTAPI version 1.3

Early Access 1 34

JTAPI Definition

7 Apr 1999

APIs or protocols JTAPI is an interface that allows value-add telephony software products to be developed to run on any product implementation that exposes a JTAPI interface. JTAPI applications are portable between different telephony products. For example, the same JTAPI application can run on a cellular phone and a media server on a VoIP network if both expose a JTAPI interface. JTAPI makes this possible by presenting an abstraction of telephony services that is independent of a given implementations underlying network and its 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 control features to those with the full suite of PBX/ACD call control functionality. It also applies to implementations which provide JTAPI access to only a single telephony device (e.g. first party) and those which 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 a telephone including: its display, buttons and lamps (real and virtual), auditory components, hook switches associated 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) of telephony resources providing functionality through the JTAPI interface. JTAPI is used to access the functionality of a telephone system, and could be used between the modules within an implementation, however not all the functionality required to implement a telephone system is included. JTAPI does not expose individual signalling protocols (such as SS7, ISDN, GSM, etc.) and associated features that a particular telephone or telephone system implementation is likely to need internally. Nor does it include non-telephony services that Java-based telephones are likely to need (such as interfaces to draw a telephone user interface on a bitmapped display). Implementations which intend to expose other types of functionality such as power management, messaging, web browsing, SNMP support, access to device-specific functions, etc., will use other complementary Java interfaces to do so.

Early Access 1 35

JTAPI version 1.3

7 Apr 1999

The Tao of JTAPI

The scope of JTAPI corresponds to the top-most layer of interfaces defined by the ECTF architectural framework and encompasses the functionality of the call control (C.xxx), media services (S.xxx), and administrative 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 JTAPI

JTAPI has these guiding principles: JTAPI should maximize telephony application portability. This is achieved through the choice of Java as a language binding as well as through the abstraction of first-party versus third-party call control. JTAPI should be scaleable from PDAs, cellular phones, and set-top boxes, to desktop applications, to large call centers. JTAPI should be simple. The call model targets transitions of real-world objects, not services which can 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 JTAPI should 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 Wrights presentation at 1997s JavaOne conference: JTAPI " Enables portable JavaTM applications to setup, control and tear down calls (and control their associated data streams) to and from public and private networks, on a broad spectrum of host telephony platforms". Its important to note that JTAPI isnt just a call control API - it also controls associated media streams. Providing a single API that covers both these areas is one of JTAPIs 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 using these APIs as primitives.Most of the JTAPI implementations we are aware of are based on these APIs, but as 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 to run on the same platform as an existing telephony API, but this isnt true. Figure 7 shows a very typical implementation architecture, called "thin-client", which uses Javas Remote Method Invocation (RMI) technology to access a telephony server across a network. Other networking technologies could be used as well (JOE, etc.), as long as the client and the server understand the same technology. JTAPI is neutral on this issue.

JTAPI version 1.3

Early Access 1 36

What Java packages are included in 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, the JTAPI call model can express either first-party or third-party call control, although underlying implementations will typically support one or the other. This diversity, hidden from applications, falls squarely on JTAPI implementers. We believe its infeasible to write a JTAPI implementation that is portable across the underlying telephony APIs. So, unlike many Java APIs, you dont download Java class files and run your application. JTAPI requires an implementation, specific to your telephony environment, in order to function. To meet this requirement, 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 in JTAPI, and specifies the methods any application can assume on any JTAPI-conforming implementation. Any JTAPI implementation must support Core JTAPI. package javax.telephony.callcenter - This package extends Core JTAPI to provide the following key Call Center features: Routing, Automatic Call Distribution (ACD) , Predictive Calling, and Application Data. package javax.telephony.callcontrol - This package extends Core JTAPI to provide more information about the call model, and to support advanced services like conferencing. package javax.telephony.phone - This package permits implementations to describe physical Terminals in terms of standardized components. Applications may query each Terminal, using this package, for the components that make up the Terminal, and applications may control certain attributes of these components, such as speaker volume. package javax.telephony.privatedata - This package enables applications to communicate data directly with the underlying hardware switch. This data may be used to instruct the switch to perform a 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 effectively ties 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 may be 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 the telephone line. A wide variety of media-centric telephony applications exist today, including workstation answering machines, IVR systems, PPP daemons, and fax applications. This package provides support for these types of media telephony applications.

Early Access 1 37

JTAPI version 1.3

7 Apr 1999

What do implementers need to implement?

What do implementers need to implement?

At the very least, implementers must support the javax.telephony, javax.telephony.capabilities, and javax.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 do not immediately return control to the application. Instead, most methods guarantee "post-conditions" when they 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 the application, the connection has been DISCONNECTED, and the associated terminal connection has been DROPPED (among other post-conditions). This approach requires application execution threads to block until these post-conditions are met. The application doesnt 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 their applications are likely to suspend execution. In particular, observer event delivery threads should not make potentially blocking JTAPI method calls, because this could lead to circular waiting deadlocks (the observer is waiting on the response to the method call, which the implementation cant deliver because the observer 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 this happens 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 the hall, 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 connection endpoint - a Terminal. Think of being interested in a phone number, which could appear on many phone sets, versus being interested in a single phone set. Thats why there are both Address and Terminal observers.

JTAPI version 1.3

Early Access 1 38

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

7 Apr 1999

Some environments may restrict the applications ability to monitor calls as they move from address/terminal to address/terminal. In many cases, different "monitors" are used by the underlying implementation, depending on whether the application is interested in the call while its at a specific address/terminal, or interested in the call through the life of the call. Thats 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 doesnt cover every possible situation in every possible telephony environment, and it never will. JTAPI wasnt designed top-down, to anticipate all requirements of computer telephony. The contents of JTAPI to date have been determined pragmatically. When people working on the specification encountered a situation or application that isnt 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 doesnt "do X", these are the suggested guidelines: Make sure JTAPI really doesnt "do X". JTAPI is pretty flexible. For example, several proposals for extensions to cover conferencing situations have been withdrawn because JTAPI applications can hold() any TerminalConnection or disconnect() any Connection in the conference - not just "the near end". Raise this deficiency as an issue, especially if its not obvious how to map "X" onto JTAPI. For instance, a proposed CallControlCall.swap() method was accepted for JTAPI 1.2 because some underlying telephony systems require you to hold an active call before you can unhold an inactive call (because they wont let you have two active calls at once), while others prevent you from doing so (because they wont let you have two held calls at once) - so there was no way to alternate between calls portably. Define "X" in the most general terms possible. Its more likely well extend JTAPI to make a "high-speed data call" than to make a "19.2 Kb/s data call", because applications will be more portable if they request "the highest speed connection your implementation supports". Identify the market segments affected by the deficiency. This helps determine the amount of enthusiasm for removing the deficiency. If "X" exists only in a limited market segment, consider extending JTAPI using your own "reversed domain name package" ("COM.grommet.DialAndNuke" for the interface to dial into your microwave oven). Most of the interesting JTAPI objects are specified as interfaces, and theres no problem if implementations create JTAPI objects that implement additional interfaces.24 If "X" turns out to be interesting and widely deployed, the methods you specified can be "added back" to the JTAPI specification fairly easily.

Early Access 1 39

JTAPI version 1.3

7 Apr 1999

JTAPI Pitfalls and Development Tips

JTAPI Pitfalls and Development Tips

This sections contains information on some common JTAPI pitfalls and develop tips.

Check Capabilities
Telephony environments vary widely in their functionality. JTAPI cannot reduce this variation, however JTAPI 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 Dynamic capabilities depend on the current state of the call model .

Observer Event Threads & Blocking Methods

JTAPI, 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 their applications are likely to suspend execution. In particular, event observer threads should not make potentially blocking calls. This could lead to deadlock. Use "anonymous inner classes", defined in JDK 1.1, to create a background thread to avoid making blocking JTAPI calls in Observer code. An example of an 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 type

When 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)

JTAPI version 1.3

Early Access 1 40

getProvider() Pitfall

7 Apr 1999

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

getProvider() Pitfall
A 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 application calls JtapiPeerFactory.getJtapiPeer(null).getProvider(). If this happens, a new/different instance of Provider will be created. This may not be a desirable outcome to the JTAPI applications if they assume to share 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 Provider referenced by myProvider. A way to do this is to keep a reference to the provider in the in the peer and a reference to the peer in the JVM-wide System.properties. Not pretty but it works.

Be careful when using extension events

There is currently no way to query the peer/provider for what events it may send out. Not all events for an extension package may be supported by the implementation. It is best to depend on core events, but be ready to take full advantage of non-core events when they happen, For example, suppose an application assumes a call-control extension is available expects to get an CallCtlConnOfferedEv prior to a TermConnRingingEv so the application can prepare for an incoming call. But some providers dont support ISDN and therefore may not issue a CallCtlConnOfferedEv. The application may not handle just receiving a TermConnRingingEv correctly. The application is dependant on an CallCtlConnOfferedEv that might not ever appear, although there is no way to know in advance.

Dont 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 their role 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 precisely define 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.

Early Access 1 41

JTAPI version 1.3

7 Apr 1999

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

Early Access 1 i

JTAPI version 1.3

7 Apr 1999

Connection States . . . . . . . . . TerminalConnection Object States . . . . . . Obtaining a Provider . . . . . . . . . Call Scenarios . . . . . . . . . . Outgoing Telephone Call Example (Observer based) . . Outgoing Telephone Call Example (Listener based) . . Incoming Telephone Call Example (Observer based) . . Incoming Telephone Call Example (Listener based) . . Security in JTAPI . . . . . . . . . Appendix . . . . . . . . . . . JTAPI Definition . . . . . . . . . . The Tao of JTAPI . . . . . . . . . Frequently Asked Questions . . . . . . . What is the scope of JTAPI? . . . . . . . What is the relationship of JTAPI to other telephony APIs? Where can I get the class files for JTAPI? . . . . What Java packages are included in JTAPI? . . . . What do implementers need to implement? . . . . Is JTAPI "blocking" or "non-blocking"? . . . . . Why are there so many kinds of observers? . . . How can I make JTAPI do "X"? . . . . . . JTAPI Pitfalls and Development Tips . . . . . Check Capabilities . . . . . . . . . Observer Event Threads & Blocking Methods . . . Use instanceOf() to get exact object type . . . . getProvider() Pitfall . . . . . . . . . Be careful when using extension events . . . . . Dont count on Meta-Events. . . . . . . . Examine all events in a batch before acting. . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

21 22 23 24 25 27 29 31 34 34 34 36 36 36 36 37 37 38 38 38 39 40 40 40 40 41 41 41 41

JTAPI version 1.3

Early Access 1 ii