JTAPI FAQ

Version: $Revision: 1.10 $
Created on: $Date: 2003-04-11 14:01:36 $

Q:  Using JTapiPeer.getProvider(providerString) the newly instantiated Provider instance creates a new connection to the PBX. How can do I disconnect this connection ?

A: Calling shutdownProvider() on the Provider object causes the provider to diconnect from the PBX. See the JTAPI documentation.


Q:  How do I check whether a remote party was busy when a make call attempt failed ?

A: You will get a failed event on a "standard" call observer, that returns CAUSE_NORMAL when calling getCause(). This information is not sufficient to identify the reason why a call failed. To get the real reason, your observer must implement the javax.telephony.callcontrol.CallControlCallObserver interface. The observer will receive additional, more detailled call control events. The call control equivalent to a normal failed event is the javax.telephony.callcontrol.events.CallCtlConnFailedEv, which has a getCallControlCause() method that returns more detailled information.


Q:  How do I check whether the given number for a remote party was wrong when a make call attempt failed ?

A: Under certain conditions the Call.connect() method will throw an InvalidPartyException immediatly when traing to dial a wrong number (e.g. when the number contains invalid characters or a non-existing device inside the same PBX is called). To check the reason for a failed event, proceed as described in the answer above.

Q:  I can't get my simple test program to work. My calls to Provider.getAddress() always fail. What can I do ?

A: Check your CAP and SccP setup. Here are the steps to perform:

In CAP management:

  • Set up an SccP instance using the CAP management application.
  • Set up a CAP user for the address you want to monitor. Assign a "CAP" license to this user. Alternatively you can also enable automatic license allocation in the CAP license management.
  • Set a password for this user.
  • Check the "CTI user" checkbox on this user.
  • Check the extension in the phone number field.
In your source:
  • Check your JTAPI provider URL. The provider URL must contain the host and port number of the SccP. The applicationID must be "CAP". The "login" is the canonical device id for the device configured above, including brackets and hyphens (e.g. "login=+49(30)12345-678"). The "passwd" parameter should contain the password set for the device in CAP management.
  • Call Provider.getAddress() with a canonical device id (same as given in the connect string).
Optional: Additional steps when building server applications

In the previous steps the "login" and the requested address object were identical. This is desirable if a client application authenticates a single device and performs operations on it. A server application however has to deal with several devices. Instead of having multiple provider objects connected with different login parameters, the "CAP" user has to be created.

In CAP management:
  • Create a user called "CAP" that is an "Admin" user type. Set a password on this user.
In your source:
  • Edit the JTAPI provider URL and change the login to "CAP" and the password to CAP's password.
  • Calling Provider.getAddress() with different canonical numbers should work fine (assuming the numbers are valid and have a CAP license assigned or automatic license allocation is enabled).
How to check the CAP settings ?
  • To check whether a device exists and the password is properly configured in the CAP management, send a request from your webbrowser to http://<host>:8170/mgmnt/auth/req?authenticate=<userId>&passwd=<password> where <userId> is either your user id (e.g. "CAP") or a canonical device ID. Note that the "+" sign in a canonical device IDs must be URL encoded to "%2B". The call will return
    6::authenticated
    if everything is fine or
    -8::user unknown
    if the user was not correctly created.
  • To check whether a device was a license for a certain service assigned, call
    http://<host>:8170/admin/req?registerLicense=CAP&userId=<userId>
    This call should return
    0:OK
    if the license was configured properly. Check your licensing otherwise.

Q:  I get a ProviderUnavailableException that contains the message "sealing violation". What does this mean ?

A: This message indicates that you most likely have duplicate class definitions in your classpath. Certain applications (e.g. Application Servers following the J2EE classloader specification) don't allow other classes to access inherited protected methods when the class was loaded from a different classloader. To solve this issue, make sure all your classes are loaded from the same classloader. For J2EE application servers this means that the jar files that contain the JTAPI library should be deployed in the same EAR as the rest of the application, as otherwise the jar will be loaded by different classloaders. See

http://www.experts-exchange.com/Programming/Programming_Languages/Java/Q_20233886.html

for more information.




Q:  How can I perform a blind transfer ?

A: JTAPI does not support blind transfers directly. The standard transfer(Call aSecondCall) method has very strict preconditions (one TerminalConnection must be HELD, the other must be TALKING). The second transfer(String aDeviceToTransferTo) method is implemented as a SingleStepTransfer request, that is not supported by all PBXs. However, some switches do support transferring calls to a consultation call that is still alerting. The current implementation supports this feature by offering a non-standard additional blindTransfer(Call aSecondCall) method that behaves exactly like transfer(Call aSecondCall), but allows the second TerminalConnection to be ALERTING. To use this extension, cast the javax.telephony.Call object to a de.ilink.cti.cstajtapi.extensions.ExtendedCallControlCall and call the method:

	Call firstCall ; // Assume this exists
	CallControlCall consultationCall ; // Assume this exists
	((de.ilink.cti.cstajtapi.extensions.ExtendedCallControlCall)consultationCall).blindTransfer(firstCall) ;


Important note: Due to a lack in the underlying CSTA protocol, the endpoint(s) on the first call don't get any information on the state of the endpoint that joined from the second call. The remote connection (viewed from the endpoint(s) of the first call) can be either connected or alerting after the blind transfer. The implementation assumes that the remote end is connected, no matter whether this is really the case or not. This might lead to inconsistent data if a transferred call is monitored from both the consulted and the transferred endpoint(s). The information on the consulted endpoint is always correct, the other information should be ignored. Please also note that is problem only applies to blind transfers, as otherwise JTAPI's constraints guarantee that the consulted endpoint is always connected.


Q:  How are device monitors on my PBX handled ?

A: As monitor licenses on a PBX are sometimes limited and JTAPI does not offer a method to manually stop the monitoring of a specific Address or Terminal, the implementation has some built-in logic to determine whether a device should be further monitored or not.
The approach taken is based on the reachabilty of the corresponding objects in the Java VMs object graph. When you obtain an Address instance from the Provider, the provider only keeps a WeakReference to the underlying device object. To prevent a device from being garbage collected (and thereby unmonitored), the following options exist:

  • Keep a strong reference (e.g. via a member variable of a using object) to the Address or Terminal of the device.
  • Add an observer or listener to the Address or Terminal of the device. AddressObserver/Listener, TerminalObserver/Listener and CallObserver/Listener (registered on an Address or Terminal) are all possible choices. Registering an observer causes the device to be retained until the last observer has been deregistered.
To implicitly remove a device monitor, check that you have removed all strong references to any object that points to the device (including calls, connections, etc.) and remove all listeners and observers registered on the device.

If you are planning to use this JTAPI implementation in a very active environment and operate on a (in contrast to the devices used in JTAPI) very limited number of available monitor licenses, please note that a device monitor is not removed until the last call on the device has been finished.

As the implemented solution is based on the non-deterministic nature of the garbage collector of the underlying Java VM, no guarantee can be given when a device monitor is actually removed. Calls arriving or placed before a device is garbage collected prevent the device monitor from being stopped.