All Packages Class Hierarchy This Package Previous Next Index
Applications create instances of a Call object with the Provider.createCall() method. After this method returns, the returned Call object has zero Connections associated with it and is in the Call.IDLE state. The Call object maintains a reference to its Provider object throughout the lifetime of the Call object. This Provider object does not change throughout the lifetime of the Call object.
Call objects maintain an array of Connection objects which are associated with the Call. A Call maintains a reference to a Connection object only if it is not in the Connection.DISCONNECTED state. Therefore, if a Call has a reference to a Connection, then that implies the Connection is not in the Connection.DISCONNECTED state. When Connections in a Call move into the Connection.DISCONNECTED state (e.g. when a party hangs up), the Call loses the reference to that Connection object.
A Call object in the Call.IDLE state has zero Connections associated with it. All Call objects begin in the Call.IDLE state.
The Call object is in the Call.ACTIVE state when it has one or more Connections associated with it. A Call may have Connections associated with it through some external action or through an application successfully invoking the Call.connect() method.
The Call object is in the Call.INVALID state when it has zero Connections associated with it, but previously has Connections associated with it. A Call in Call.INVALID state once had Connections which all have moved to the Connection.DISCONNECTED state. A Call object in the Call.INVALID state cannot be used further and should be deferenced by the application for garbage collection. The Provider also loses its reference to the Call object when the Call moves into the Call.INVALID state. This implies that the Call object is no longer returns by Provider.getCalls().
The predicates for the Call states are as follows. The purpose of the predicates is to states truths about each Call state.
The IDLE state (this.getState() == Call.IDLE)
The ACTIVE state (this.getState() == Call.ACTIVE)
The INVALID state (this.getState() == Call.INVALID)
When the call is in the IDLE state, the call can be initialized by setting optional parameters that influence the subsequent behavior of the call. Various JTAPI extension packages provide methods to set such parameters.
The CallObserver interface reports all events pertaining to the Call object. This not only includes state changes in the Call object, but also includes state changes in all Connections associated with the Call object, and state changes in all TerminalConnections associated with those Connections. The CallObserver interface also reports when new Connections and TerminalConnections are created in the Call. Applications instantiate an object which implements the CallObserver interface and uses the Call.addObserver() to begin the delivery of events to that observer.
public final static int IDLE
public final static int ACTIVE
public final static int INVALID
public abstract Connection[] getConnections() throws InvalidStateException, PlatformException
The pre-conditions for this method are listed below:
The post-conditions for this method are listed below:
public abstract Provider getProvider() throws PlatformException
public abstract int getState() throws PlatformException
public abstract Connection[] connect(Terminal origterm, Address origaddr, String dialedDigits) throws ResourceUnavailableException, PrivilegeViolationException, InvalidPartyException, InvalidArgumentException, InvalidStateException, MethodNotSupportedException, PlatformException
The first argument is the originating Terminal for the telephone call. The second argument represents the Address from which the call is placed. The originating address must be one of the addresses associated with the originating Terminal, otherwise an exception is thrown. The third argument is the string address to which the phone call is being placed. This is also known as the destination address and must be a valid and complete telephone address.
The pre-condition predicates for this method indicate which statements must be true in order for this method to succeed. However, these predicates do not guarantee the success of this method.
The post-condition predicates for the Call.connect() method are as follows. Note that the eventual outcome of this method is described by a number of scenarios below. These post-conditions only reflect the state immediately after the Call.connect() returns.
Two scenarios of the eventual outcome of this method are given below. Note, what is termed the "normal" operation of this method results in an active telephone call. A sequence of discrete call model changes is given by a list of discrete steps each labelled with a number. Changes in the call model falling under the same number are seen by the application as happening at once. These two scenarios do not represent all the possible outcomes of the Call.connect method. These scenarios just represent two typical scenarios.
Scenario 1: The "normal" operation of this method, where the result is two ends participating in an active telephone call.
The Call.connect() method returns, returning a two-element array of Connections. The first element at index 0 represents the originating Connection. The second element at index 1 represents the destination Connection. Both Connections are in the Connection.IDLE state.
The following events are delivered to the application via a CallObserver on this Call: a java.telephony.events.CallActiveEv, a java.telephony.events.ConnCreatedEv for each of the two Connections created.
The following events are delivered to the application via a CallObserver on this Call: a java.telephony.events.ConnConnectedEv for the originating Connection, a java.telephony.events.TermConnCreatedEv for the new TerminalConnection created, and a java.telephony.events.TermConnActiveEv for the new Terminal Connection.
Depending upon the configuration of the switch, additional TerminalConnections may be created. These TerminalConnections will be associated with Terminals which have the originating Address as one of their Addresseses. Unfortunately, there is no way for the implementation to tell which TerminalConnections will be created in advance, only that the number cannot be greater than the number of Terminals associated with the originating Address and each TerminalConnection must go to one of those Terminals associated with the originating Address. If such a Terminal Connection is created, it will be in the TerminalConnection.PASSIVE state.
Additional events are delivered because of the above paragraph: a java.telephony.events.TermConnCreateEv for all additional Terminal Connections created, and a java.telephony.events.TermConnPassiveEv for each of those Terminal Connections.
The following events are delivered to the application via the CallObserver interface: a java.telephony.events.ConnInProgressEv for the destination Connection.
The following events are delivered to the application via a CallObserver on this Call: a java.telephony.events.ConnAlertingEv for the destination Connection, a java.telephony.events.TermConnCreatedEv for all Terminal Connections created to Terminals with the destination Address, a java.telephony.events.TermConnRingingEv for all those new TerminalConnections.
The following events are delivered to the application via the CallObserver on this Call: a java.telephony.events.ConnConnectedEv for the destination Connection, and a java.telephony.events.TermConnActiveEv for the TerminalConnection which answered the telephone call.
For all other TerminalConnections in the TerminalConnection.RINGING state on the destination side, either one of two things will happen depending upon the configuration of the switch. Unfortunately, the implementation is unable to determine the behavior of the switch beforehand. In one situation, these TerminalConnections move from the TerminalConnection.RINGING state to the TerminalConnection.PASSIVE state. In the second situation, these TerminalConnections move from the TerminalConnection.RINGING state to the TerminalConnection.DROPPED state.
Because of the paragraph above, the following events will be delivered to the application via the CallObserver interface on this Call: a java.telephony.events.TermConnPassiveEv in one situation, or a java.telephony.events.TermConnDroppedEv in the other situation.
The post-condition predicates for scenario 1 are as follows. These post-conditions state what is true about the call model after the final step of scenario 1 completes.
Scenario 2: The desired telephone call is placed however the completion of the call is impossible because of a failure. For example, this scenario will occur if the destination address is busy. In this scenario the destination Connection never reaches the ALERTING state. (i.e. the destination party is never alerted to this telephone call)
The Call.connect() method returns, returning a two-element array of Connections. The first element at index 0 represents the originating Connection. The second element at index 1 represents the destination Connection. Both Connections are in the Connection.IDLE state.
The following events are delivered to the application via a CallObserver on this Call: a java.telephony.events.CallActiveEv, a java.telephony.events.ConnCreatedEv for each of the two Connections created.
The following events are delivered to the application via a CallObserver on this Call: a java.telephony.events.ConnConnectedEv for the originating Connection, a java.telephony.events.TermConnCreatedEv for the new TerminalConnection created, and a java.telephony.events.TermConnActiveEv for the new Terminal Connection.
Depending upon the configuration of the switch, additional TerminalConnections may be created. These TerminalConnections will be associated with Terminals which have the originating Address as one of their Addresseses. Unfortunately, there is no way for the implementation to tell which TerminalConnections will be created in advance, only that the number cannot be greater than the number of Terminals associated with the originating Address and each TerminalConnection must go to one of those Terminals associated with the originating Address. If such a Terminal Connection is created, it will be in the TerminalConnection.PASSIVE state.
Additional events are delivered because of the above paragraph: a java.telephony.events.TermConnCreateEv for all additional Terminal Connections created, and a java.telephony.events.TermConnPassiveEv for each of those Terminal Connections.
The following events are delivered to the application via the CallObserver interface: a java.telephony.events.ConnInProgressEv for the destination Connection.
The following events are delivered to the application via the CallObserver interface: a java.telephony.events.ConnFailedEv for the destination Connection.
The post condition predicates for scenario 2 are as follows. These post-conditions state what is true about the call model after the final step of scenario 1 completes.
public abstract void addObserver(CallObserver observer) throws ResourceUnavailableException, PlatformException
By default, when an observer is added to a telephone call, the first batch of events may be a "snapshot". That is, if the observer was added certain state changes in the call, the first batch of events will inform the application of the current state of the call. Note that these snapshot events do NOT provide a history of all events on the call. Rather they provide the minimum neccessary event to bring the application up-to-date with the current state of the call.
If an application attempts to add an instance of an observer already present on this Call, then repeated attempts to add the instance of the observer will silently fail, i.e. multiple instances of an observer are not added and no exception will be thrown.
There are no pre-conditions for this method.
The post-condition predicates for this method are:
public abstract CallObserver[] getObservers() throws PlatformException
There are no pre-conditions for this method.
The post-conditions for this method are:
public abstract void removeObserver(CallObserver observer) throws PlatformException
Also, if an observer is not part of the Call, then this method fails silently, i.e. no observer is removed an no exception is thrown.
There are no pre-conditions for this method.
The post-condition predicates for this method are:
public abstract CallCapabilities getCallCapabilities(Terminal terminal, Address address) throws InvalidArgumentException, PlatformException
All Packages Class Hierarchy This Package Previous Next Index