overview.html

JTAPI_html 用于JTAPI的HTML文档.

</TD>
<TD WIDTH="80%">
The <EM><STRONG>java.telephony.privatedata</STRONG></EM> 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. Additionally applications may use this package to "piggy-back" a piece
of data with a Java Telephony API object.
</TD>
</TR>

</TABLE>


<BR><BR>

<H2>
<A NAME="CALLMODEL">
The Java Telephony Call Model
</A>
<HR>
</H2>

<P>
The JTAPI <EM>call model</EM> consists of a half-dozen Java object. These objects
are defined using Java interfaces in the core package. Each call model object
represents either a physical or conceptual 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.
</P>

<P>
The following diagram shows the JTAPI call model and the objects which compose
the call model. A description of each object follow the diagram.
</P>

<CENTER>
<IMG SRC="images/cmodel.gif">
</CENTER>

<CENTER>
<P>
<FONT SIZE=-1 FACE="Helvetica">
<STRONG>
Figure 4: JTAPI Call Model
</STRONG>
</FONT>
</P>
</CENTER>

<H3>
<IMG SRC="images/magenta-ball.gif">
Provider Object
</H3>

<OL>
<P>
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.
</P>
</OL>

<H3>
<IMG SRC="images/magenta-ball.gif">
Call Object
</H3>

<OL>
<P>
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. 
</P>
</OL>


<H3>
<IMG SRC="images/magenta-ball.gif">
Address Object
</H3>

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

<H3>
<IMG SRC="images/magenta-ball.gif">
Connection Object
</H3>

<OL>
<P>
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 logcal 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.
</P>
</OL>

<H3>
<IMG SRC="images/magenta-ball.gif">
Terminal Object
</H3>

<OL>
<P>
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.
</P>
</OL>


<H3>
<IMG SRC="images/magenta-ball.gif">
TerminalConnection Object
</H3>

<OL>
<P>
TerminalConnection objects model the relationship between a call 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 call (in
contrast to the Connection, which models the logical view). The
TerminalConnection describes the current state of relationship between the Call
and a particular Terminal. The states associated with the TerminalConnection
are described later in this document.
</P>
</OL>

<BR><BR>

<H2>
<A NAME="COREMETHODS">
Core Package Methods
</A>
</H2>

<P>
The core package defines three methods to support its primary features: placing
a telephone call, answering a telephone call, and dropping a telephone call.
These methods are <STRONG>Call.connect()</STRONG>,
<STRONG>TerminalConnection.answer()</STRONG>, and
<STRONG>Connection.disconnect()</STRONG>, respectively.

<H3>
<IMG SRC="images/magenta-ball.gif">
Call.connect()
</H3>

<P>
<OL>
Once an application has an idle call object (obtained via
<STRONG>Provider.createCall()</STRONG>), it may place a telephone call using the
<STRONG>Call.connect()</STRONG> 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 <STRONG>Call.connect()</STRONG> method,
representing the originating and destination ends of the telephone call.
</OL>
</P>


<H3>
<IMG SRC="images/magenta-ball.gif">
TerminalConnection.answer()
</H3>

<P>
<OL>
Applications monitor with observers (discussed later) on Terminal for when
incoming calls are presented. 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
<STRONG>TerminalConnection.answer()</STRONG> to answer that incoming telephone
call.
</OL>
</P>


<H3>
<IMG SRC="images/magenta-ball.gif">
Connection.disconnect()
</H3>

<P>
<OL>
The <STRONG>Connection.disconnect()</STRONG> 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.
</OL>
</P>


<BR><BR>

<H2>
<A NAME="CONNECTIONSTATES">
Connection Object States
</A>
<HR>
</H2>

<P>
A Connection object is always in a <em>state</em> which reflects the current
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.
</P>

<P>
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. The diagram below shows the possible state
transitions for the Connection object. Following this diagram is a brief
summary of the meaning of each state.
</P>

<CENTER>
<IMG SRC="images/state1.gif">
</CENTER>

<CENTER>
<P>
<FONT SIZE=-1 FACE="Helvetica">
Figure 5: Connection State Transitions
</FONT>
</P>
</CENTER>


<H3>
<IMG SRC="images/magenta-ball.gif">
IDLE state
</H3>

<P>
<OL>
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.
</OL>
</P>

<H3>
<IMG SRC="images/magenta-ball.gif">
INPROGRESS state
</H3>


<P>
<OL>
The INPROGRESS state indicates that a telephone call is currently being placed
to this destination endpoint.
</OL>
</P>

<H3>
<IMG SRC="images/magenta-ball.gif">
ALERTING state
</H3>

<P>
<OL>
The ALERTING state indicates that the destination party of a telephone call
is being alerted to an incoming telephone call.
</OL>
</P>


<H3>
<IMG SRC="images/magenta-ball.gif">
CONNECTED state
</H3>

<P>
<OL>
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.
</OL>
</P>

<H3>
<IMG SRC="images/magenta-ball.gif">
DISCONNECT state
</H3>

<P>
<OL>
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.
</OL>
</P>

<H3>
<IMG SRC="images/magenta-ball.gif">
FAILED state
</H3>

<P>
<OL>
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.
</OL>
</P>

<H3>
<IMG SRC="images/magenta-ball.gif">
UNKNOWN state
</H3>

<P>
<OL>
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. The effects of the invocation of any method on
a Connection in this state is unpredictable.
</OL>
</P>

<BR><BR>

<H2>
<A NAME="TERMINALCONNECTIONSTATES">
TerminalConnection Object States
</A>
<HR>
</H2>

<P>
The TerminalConnection object represents the relationship between a Terminal
and a Call. 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.
</P>

<CENTER>
<IMG SRC="images/state2.gif">
</CENTER>

<CENTER>
<P>
<FONT SIZE=-1 FACE="Helvetica">
Figure 6: TerminalConnection state transitions
</FONT>
</P>
</CENTER>


<H3>
<IMG SRC="images/magenta-ball.gif">
IDLE state
</H3>

<P>
<OL>
The IDLE state is the initial state for all TerminalConnection objects. It
has the same connotation for the Connection object's IDLE state.
</OL>
</P>

<H3>
<IMG SRC="images/magenta-ball.gif">
ACTIVE state
</H3>

<P>
<OL>
The ACTIVE state indicates a Terminal is actively part of a telephone call.
This often implies that the Terminal handset is off-hook.
</OL>
</P>

<H3>
<IMG SRC="images/magenta-ball.gif">
RINGING state
</H3>

<P>
<OL>
The RINGING state indicates that a Terminal is signaling to a user that an
incoming telephone call is present at the Terminal.
</OL>
</P>

<H3>
<IMG SRC="images/magenta-ball.gif">
DROPPED state
</H3>

<P>
<OL>
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.
</OL>
</P>


<H3>
<IMG SRC="images/magenta-ball.gif">
PASSIVE state
</H3>

<P>
<OL>
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 which
provide advanced features permit Terminals to join calls from the PASSIVE
state.
</OL>
</P>

<H3>
<IMG SRC="images/magenta-ball.gif">
UNKNOWN state
</H3>

<P>
<OL>
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 object's UNKNOWN state.
</OL>
</P>

<BR><BR>

<H2>
<A NAME="PLACINGCALL">
Placing a Telephone Call
<HR>
</H2>

<P>
The past several sections have outlines the JTAPI call model, the key methods
in the core package, and the Connection and TerminalConnection states. This
section ties all of this information together, presenting a common scenario
found in most telephony applications. This section describes the state changes
the entire call model typically undergoes when an application places a simple
telephone call. Readers will hopefully come away with a coherent understanding
of the call model changes for this simple example.
</P>

<P>
The vehicle used to describe the state changes undergone by the call model is
the diagram below. This diagram is a <EM>call model timing diagram</EM>, where
changes in the various objects are depicted as times increases down the 
vertical axis.
Such a diagram is given below describing the typical state changes after an
application invokes the <STRONG>Call.connect()</STRONG> method.
</P>

<CENTER>
<P>
<IMG SRC="images/timeline.gif">
</P>
</CENTER>

<CENTER>
<P>
<FONT SIZE=-1 FACE="Helvetica">
Figure 7: Call Model timing diagram
</FONT>