Java Programmer's Guide and Reference

JTAPI example

The IBM CallPath Enterprise Toolkit for Java includes a basic example application, JtapiAppl, that illustrates how you can write an application using the JTAPI classes. You cannot run this example application as an applet.

Notes:

1. The example application was written using JDK 1.1.

2. Limited testing was performed on this example application.

3. You may have to modify this example application so that it runs in your environment.

JtapiAppl does the following:

1. Gets a JtapiPeer
2. Gets a Provider from the JtapiPeer
3. Waits for the Provider to go to the Provider.IN_SERVICE state
4. Creates a Call
5. Connects an Address and Terminal to another number
6. Answers the new Terminal
7. Disconnects the Call
8. Shuts down the Provider
9. Exits

Note:

You must configure at least one address (extension) on the CallPath Enterprise JTAPI Daemon for the Provider login ID.

JtapiAppl files

The following JtapiAppl files, as well as the associated class files, are stored in the ibmcpath.jar file:

ApplEvent.java

This class file is used to pass Call event information from the SampleCallObserver to the Application.

ConnectArgs.java

This class file is used to collect the arguments needed for the Call.connect() method.

Connect_Args.java

This class file extends Frame and is used to provide the arguments to the ConnectArgs class.

JtapiAppl.java

This file contains the class JtapiAppl, which is the application's main class.

MainDisplay.java

This class file extends Frame and is used to display status information about the progress of the example application.

ProviderFrame.java

The ProviderFrame class file extends Frame and is used to collect the ServerName, Login, and optional Password needed to create a Provider.

SampleCallObserver.java

The file containing the CallObserver that is attached to the Call when it is created. It watches for certain events, then sends the events to the JtapiAppl event queue.

SampleProviderObserver.java

This file contains the ProviderObserver that is added to the Provider. It waits for Provider events and sets a flag indicating the current condition of the Provider. The application can invoke a method to wait for the Provider to go to the Provider.IN_SERVICE state.

Understanding JtapiAppl

The JtapiAppl class is the "starting point" of the application. It has an event queue and a method that the SampleCallObserver uses to add events to the queue. The events are then processed by the application in the order received. Each of these events has handler methods that you can program to perform the desired actions when particular events occur. (The example application has only implemented a few of these handler methods. Most of the handler methods in the example are empty methods.)

• The SampleProviderObserver class allows the application to wait for the Provider to enter the Provider.IN_SERVICE state. Although this is the sole purpose of the SampleProviderObserver in this example application, you can enhance this observer to send events to the JtapiAppl event queue when the Provider changes state.
• The SampleCallObserver class receives Call events and creates ApplEvent objects based on the occurrence of certain key events. The JtapiAppl.doIt() method waits for these key events and calls the appropriate method to handle each event as it occurs.

  Note:

  The SampleCallObserver does not handle the event directly because it is actually running on a thread owned by the CallPath Enterprise JTAPI implementation. It filters out the unwanted events and creates ApplEvent objects for the events for which the JtapiAppl.doIt() method is waiting. JtapiAppl can then process the events in its thread.

• The MainDisplay class displays status data.
• The Connect_Args and ProviderFrame classes gather input needed to run the application.
• The Connect_Args class contains the data needed to issue the Call.connect() method (Address, Terminal, and String).

Running JtapiAppl

To start JtapiAppl, enter java JtapiAppl or jre JtapiAppl at the command prompt. Initially, one Java frame is displayed in the background, and a second Java frame is displayed in the foreground:

1. Use the frame in the background to view the status of the application, as well as messages.
2. Use the frame in the foreground to enter the following:
   • The port and name of the CallPath Enterprise Server (for example, 7600@cpserv)
   • The user login and optional password (required if the user of the CallPath Enterprise JTAPI Daemon is configured for passwords)
3. When you are finished, press Enter; a third Java frame is displayed containing a list of addresses to which the Provider has access.
4. Double-click the address from which you want to make the call.
5. Do one of the following:
   • Enter an address in the Destination Address field.
   • Double click one of the addresses in the Destination Address list.
   Press Enter to accept the Destination Address.
6. When the Connect button becomes active, click Connect to connect the phones. If the destination Terminal can be controlled by the Provider, the application will automatically answer it. If the destination Terminal cannot be controlled by the Provider, the following message will be displayed:

   Please Answer Terminal
   nnnn
   

7. After the destination Terminal enters the TALKING state, the application will disconnect it or prompt the user to hang up the Terminal.
8. After the Call goes to the INVALID state and the Provider goes to the SHUTDOWN state, click Exit to terminate the application.

Getting JtapiPeer in an application and an applet

The JtapiAppl example application uses the JtapiPeerFactory.getJtapiPeer() method to get the JtapiPeer. An applet is not able to use this method. Instead, an applet does the following to instantiate a JtapiPeer:

JtapiPeer myJtapiPeer; 



        .



        .



try {



       myJtapiPeer = Class.forName("com.ibm.telephony.callpath.CSAJtapiPeer").newInstance();



        }

   catch (Exception e) {



                . . .



        }