overview.html

JTAPI_html 用于JTAPI的HTML文档.

</P>
</CENTER>

<P>
In the diagram above, discrete time steps are denoted by integers down the
vertical axis. Time increases down this axis, and the integers have no
relationship between real (clock) time.
</P>

<P>
This diagram, as a whole, represents a single telephone Call. In this case,
the diagram represents a two-party telephone call (The
<STRONG>Call.connect()</STRONG> method always results in a two-party call). The
diagram may be broken into two halves: the left half and the right half. The
left half represents the originating-end of the telephone call and the right
half represents the destination-end of the telephone call.
</P>

<P>
On the left-hand (originating) side of the diagram, the two veritcal lines
represent the originating Terminal and Address (which are arguments to the
<STRONG>Call.connect()</STRONG> method) objects, as indicated on the diagram. The
horizontal lines represent either Connection objects or TerminalConnection
objects as marked. Note that the Connection objects are drawn in the inner-
most region, whereas the TerminalConnection objects are drawn in the outer-
most region.
</P>

<P>
Similarly, on the right-hand (destination) side of the diagram, the two
vertical lines represent the destination Address and Terminals. In this
example, there are two destination Terminals associated with the destination
Address. This configuration has been depicted previously in Figure 4. Note
that since there are two Terminals, there are two TerminalConnection objects
on the destination side.
</P>

<P>
This diagram can be read as follows: as time increases, the
Connection and TerminalConnection objects may or may not change states. The
appearance of a new Connection or TerminalConnection horizontal line
corresponds to a new object of that type being created during that time period.
</P>

<P>
In the example of placing a telephone call, we see that after the two
Connections are created in the IDLE state, the originating transitions to
the CONNECTED state, while the destination transitions to the INPROGRESS
state. At that time, a TerminalConnection to the originating Terminal is
created and transitions to the ACTIVE state. When the destination Connection
transitions to the ALERTING state, two TerminalConnections are created in the
RINGING state.
</P>

<P>
At this point, a person at one of the destination Terminals answers the call.
When this happens, that TerminalConnection moves to the ACTIVE state, and the
other TerminalConnection moves to the PASSIVE state. Also, the destination
Connection concurrently moves to the CONNECTED state. When the telephone call
ends, all Connections move to the DISCONNECTED state, and all
TerminalConnections move to the DROPPED state.
</P>

<P>
As a final point, this document has used the terms "logical" and "physical"
view of a telephone call. This diagram makes these concepts clear. An
application can only monitor the state changes of the Connection object
(i.e. the logical view). By looking at the diagram, the reader can hopefully
understand that these states provide a higher-level view of the progress of the
telephone call. The TerminalConnection state changes represent the physical
view. By monitoring the TerminalConnection state changes, applications can
find out what is happening at each physical endpoint.
</P>

<BR><BR>

<H2>
<A NAME="OBSERVERS">
The Java Telephony Observer Model
</A>
<HR>
</H2>

<P>
The Java Telephony API uses the Java observer/observable model to 
asynchronously notify the application of various changes in the JTAPI call
model. These changes may include the state change of an object or the creation
of an object.
</P>

<P>
The Provider, Call, Terminal, and Address objects have Observers. The
interfaces corresponding to these observers are ProviderObserver,
CallObserver, TerminalObserver, and AddressObserver, respectively.
</P>

<P>
The ProviderObserver reports all state changes to the Provider object. For
the core package, this only include when the Provider changes state from
OUT_OF_SERVCE, to IN_SERVICE, to SHUTDOWN.
</P>

<P>
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 not reported on either the
Address nor the Terminal observers.
</P>

<P>
At times, the application may want to monitor Address or Terminal objects
for incoming telephone calls. In these instances, the application uses the
<STRONG>Address.addCallObserver()</STRONG> or the
<STRONG>Terminal.addCallObserver</STRONG> 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.
</P>

<P>
The Address and Terminal observers report any state changes in these objects.
In the core there are no events for these objects. The AddressObserver and
TerminalObserver interfaces still exist, however, so other packages may
extend these interfaces.
</P>

<BR><BR>

<H2>
<A NAME="EXAMPLES">
Application Code Examples
</A>
<HR>
</H2>

<P>
This section presents two application code examples. The first places
a telephone call, and the second answers an incoming telephone call to a
Terminal.
</P>

<BR><BR>

<H3>
Outgoing Telephone Call Example
</H3>

<P>
The following code example places a telephone call using the core
Call.connect() method. It, however, looks for the states provided by the
Call Control package.
</P>

<PRE>
import java.telephony.*;
import java.telephony.events.*;

/*
 * The MyCallObserver class implements the CallObserver
 * interface and receives all events associated with the Call.
 */
 
public class MyCallObserver implements CallObserver {
 
  public void callChangedEvent(CallEv[] evlist) {
 
    for (int i = 0; i < evlist.length; i++) {
 
      if (evlist[i] instanceof ConnEv) {
 
        String name = null;
        try {
          Connection connection = 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");
        }
      }  
    }
  }
}


/*
 * Places a telephone call from 476111 to 5551212
 */
public class SampleOutcall {
 
  public static final void main(String args[]) {
 
    /*
     * Create a provider by first obtaining the default implementation of
     * JTAPI and then the default provider of that implementation.
     */
    Provider myprovider = null;
    try {
      JtapiPeer peer = JtapiPeerFactory.getJtapiPeer(null);
      myprovider = peer.getProvider(null);
    } catch (Exception excp) {
      System.out.println("Can't get Provider: " + excp.toString());
      System.exit(0);
    }
 
   /*
    * We need to get the appropriate objects associated with the
    * originating side of the telephone call. We ask the Address for a list
    * of Terminals on it and arbitrarily choose one.
    */
    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 MyCallObserver());
    } catch (Exception excp) {
      // Handle exceptions
    }
 
    /*
     * Place the telephone call.
     */
    try {
      Connection c[] = mycall.connect(origterm, origaddr, "5551212");
    } catch (Exception excp) {
      // Handle all Exceptions
    }
  }
}
</PRE>

<BR><BR>

<H3>
Incoming Telephone Call Example
</H3>

<P>
The following code example illustrates how an application answers a Call
at a particular Terminal. It shows how application accept calls when (and if)
they are offered to it. This code example greatly resembles the core InCall
code example.
</P>

<PRE>
import java.telephony.*;
import java.telephony.events.*;

/*
 * The MyObserver class implements the CallObserver and
 * recieves all Call-related events.
 */
 
public class MyObserver implements CallObserver {
 
  public void callChangedEvent(CallEv[] evlist) {
 
    for (int i = 0; i < evlist.length; i++) {
 
      if (evlist[i] instanceof TermConnEv) {
        TerminalConnection termconn = null;
        String name = null;
 
        try {
          TermConnEv tcev = (TermConnEv)evlist[i];
          TerminalConnection termconn = tcev.getTerminalConnection();
          Terminal term = termconn.getTerminal();
          String 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 */
          try {
            termconn.answer();
          } catch (Exception excp) {
            // Handle Exceptions;
          }
        }
        else if (evlist[i].getID() == TermConnDropped.ID) {
          System.out.println(msg + "DROPPED");
        }
      }  
    }
  }
}

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


<BR><BR>

<H2>
<A NAME="PROVIDER">
Locating and Obtaining Providers
</A>
<HR>
</H2>

<P>

The Java Telehony API defines a convention by which telephony server
implementations of JTAPI make their services available to applications.

<P>

The two elements that link an application to a server are:
<P>
<H3>
<IMG SRC="images/magenta-ball.gif">
JtapiPeerFactory
</H3>
<OL>
The JtapiPeerFactory class is the first point of contact for an application 
that needs 
telephony services.  It has the ability to return a named JtapiPeer 
object or a default JtapiPeer object. It is defined as a static class.
</OL>

<P>
<H3>
<IMG SRC="images/magenta-ball.gif">
JtapiPeer
</H3>
<OL>

The JtapiPeer interface is the basis for a vendor's particular implementation
of the Java Telephony API. Each vendor which provides an implementation of
JTAPI must implement this interface in a class that can be loaded by the
JtapiPeerFactory.

<P>
It is through a class that implements the JtapiPeer object that an application
gets a Provider object.
</OL

<P>
<H3>
JtapiPeerFactory: Getting Started
</H3>
<p>

The JtapiPeerFactory is a static class defined in JTAPI.  Its sole public
method, <EM> getJtapiPeer() </EM> gets the JtapiPeer implementation
requested or it returns a default implementation.

<P>

<EM> getJtapiPeer() </EM> takes the name of the desired JTAPI server
implementaion class as a parameter to return an object instance of 
that class.
If no name is provided, <EM> getJtapiPeer() </EM> returns the default
JTAPI server implementation object.
<P>
<P>
<H3>
JtapiPeer: Getting a Provider Object
</H3>
</OL>
<p>

JtapiPeer is an interface.  It is used by the JTAPI server
implementors.  It defines the methods that applications use to get
Provider objects, to query services available on those providers, and
to get the name of the JtapiPeer object instance.  By creating a class
that implements the JtapiPeer interface, JTAPI implementations make the
following methods available to applications.

<P>
  
Applications use the <EM>getProvider()</EM> method on this interface
to obtain new Provider objects. Each implementation may support one or
more different "services" (e.g. for different types of underlying network
substrate). A list of available services can be obtained via the
<EM>getServices()</EM> method.
<p>
Applications may also supply optional arguments to the Provider. These
arguments are appended to the string argument passed to the
<EM>getProvider()</EM> method. The string argument has the following
format:
<p>
&lt service name &gt ; arg1 = val1; arg2 = val2; ...
<p>
Where &lt service name &gt  is not optional, and each optional argument pair
which follows is separated by a semi-colon. The keys for these arguments
is implementation specific, except for two standard-defined keys:
<OL>
<LI>login: provides the login user name to the Provider.
<LI>passwd: provides a password to the Provider.
</OL>


Applications use the <EM>getName()</EM> method to get the name of this
JtapiPeer object instance. It has a <EM> name </EM> parameter, which
is the same name used as an argument to 
<EM>JtapiPeerFactory.getJtapiPeer()</EM> method.

</P>


<BR><BR>

<H2>
<A NAME="SECURITY">
Security in the Java Telephony API
</A>
<HR>
</H2>

<P>
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
system's integrity.
</P>
<P>
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.

</P> 

</FONT>
</BODY>
</HTML>