JSR-043: JTAPI-1.4

javax.telephony
Interface Terminal

All Known Subinterfaces:
AgentTerminal, CallControlTerminal, MediaTerminal, MobileTerminal, PhoneTerminal

public interface Terminal

A Terminal represents a physical hardware endpoint connected to the telephony domain.

Introduction

An example of a Terminal is a telephone set, but a Terminal does not have to take the form of this limited and traditional example. For example, computer workstations and hand-held devices are modeled as Terminals if they act as physical endpoints in a telephony network.

A Terminal object has a string name which is unique for all Terminal objects. The Terminal does not attempt to interpret this string in any way. This name is first assigned when the Terminal is created and does not change throughout the lifetime of the object. The method Terminal.getName() returns the name of the Terminal object. The name of the Terminal may not have any real-world interpretation. Typically, Terminals are chosen from a list of Terminals obtained from an Address object.

Terminal objects may be classified into two categories: local and remote. Local Terminal objects are those terminals which are part of the Provider's local domain. These Terminal objects are created by the implementation of the Provider object when it is first instantiated. All of the Provider's local terminals are reported via the Provider.getTerminals() method. Remote Terminal objects are those outside of the Provider's domain which the Provider learns about during its lifetime through various happenings (e.g. an incoming call from a currently unknown address). Remote Terminal objects are not reported via the Provider.getTerminals() method. Note that applications never explicitly create new Terminal objects.

Address and Terminal objects

Address and Terminal objects exist in a many-to-many relationship. An Address object may have zero or more Terminals associated with it. For each Terminal associated with an Address, that Terminal must also reflect its association with the Address. Since the implementation creates Address (and Terminal) objects, it is responsible for insuring the correctness of these relationships. The Terminals associated with an Address is given by the Address.getTerminals() method.

An association between an Address and Terminal object indicates that the Terminal contains the Address object as one of its telephone number addresses. In many instances, a telephone set (represented by a Terminal object) has only one telephone number (represented by an Address object) associated with it. In more complex configurations, telephone sets may have several telephone numbers associated with them. Likewise, a telephone number may appear on more than one telephone set. For example, feature phones in PBX environments may exhibit this configuration.

Terminals and Call objects

Terminal objects represent the physical endpoints of a telephone call. With respect to a single Address endpoint on a Call, multiple physical Terminal endpoints may exist. Terminal objects are related to Call objects via the TerminalConnection object. TerminalConnection objects are associated with Call indirectly via Connections. A Terminal may be associated with a Call only if one of its Addresses is associated with the Call. The TerminalConnection object has a state which describes the current relationship between the Connection and the Terminal. Each Terminal object may be part of more than one telephone call, and in each case, is represented by a separate TerminalConnection objet. The Terminal.getTerminalConnections() method returns all TerminalConnection object currently associated with the Terminal.

A Terminal object is associated with a Connection until the TerminalConnection moves into the TerminalConnection.DROPPED state. At that time, the TerminalConnection is no longer reported via the Terminal.getTerminalConnections() method. Therefore, the Terminal.getTerminalConnections() method never reports a TerminalConnection in the TerminalConnection.DROPPED state.

Existing Telephone Calls

The Java Telephony API specification states that the implementation is responsible for reporting all existing telephone calls when a Provider is first created. This implies that an Terminal object must report information regarding existing telephone calls to that Terminal. In other words, Terminal objects must report all TerminalConnection objects which represent existing telephone calls.

Terminal Listeners and Events

All changes in an Terminal object are reported via the TerminalListener interface. Applications instantiate an object which implements this interface and begins this delivery of events to this object using the Terminal.addTerminalListener() method. All Terminal-related events extend the TerminalEvent interface provided in the core package. Applications receive events on an listener until the listener is removed via the Terminal.removeTerminalListener() method or until the Terminal is no longer observable. In these instances, each TerminalListener receives a TERMINAL_EVENT_TRANSMISSION_ENDED as its final event.

Currently in the core package, the only Terminal-related event is TERMINAL_EVENT_TRANSMISSION_ENDED.

Call Listeners

At times, applications may want to monitor a particular Terminal for all Calls which come to that Terminal. For example, a desktop telephone application is only interested in telephone calls associated with a particular agent terminal. To achieve this sort of Terminal-based Call monitoring applications may add CallListeners to an Terminal via the Terminal.addCallListener() method.

When a CallListener is added to an Terminal, this listener instance is immediately added to all Calls at this Terminal and is added to all Calls which come to this Terminal in the future. These listeners remain on the telephone call as long as the Terminal is associated with the telephone call.

The specification of Terminal.addCallListener() contains more precise semantics.

See Also:
TerminalListener, CallListener

Method Summary
 void addCallListener(CallListener listener)
          Adds an listener to a Call object when this Terminal object first becomes part of that Call.
 void addCallObserver(CallObserver observer)
          Adds an observer to a Call object when this Terminal object first becomes part of that Call.
 void addObserver(TerminalObserver observer)
          Adds an observer to the Terminal.
 void addTerminalListener(TerminalListener listener)
          Adds an listener to the Terminal.
 Address[] getAddresses()
          Returns an array of Address objects associated with this Terminal object.
 CallListener[] getCallListeners()
          Returns a list of all CallListeners associated with this Terminal object.
 CallObserver[] getCallObservers()
          Returns a list of all CallObservers associated with this Terminal object.
 TerminalCapabilities getCapabilities()
          Returns the dynamic capabilities for the instance of the Terminal object.
 java.lang.String getName()
          Returns the name of the Terminal.
 TerminalObserver[] getObservers()
          Returns a list of all TerminalObservers associated with this Terminal object.
 Provider getProvider()
          Returns the Provider associated with this Terminal.
 TerminalCapabilities getTerminalCapabilities(Terminal terminal, Address address)
          Deprecated. Since JTAPI v1.2. This method has been replaced by the Terminal.getCapabilities() method.
 TerminalConnection[] getTerminalConnections()
          Returns an array of TerminalConnection objects associated with this Terminal.
 TerminalListener[] getTerminalListeners()
          Returns a list of all TerminalListeners associated with this Terminal object.
 void removeCallListener(CallListener listener)
          Removes the given CallListener from the Terminal.
 void removeCallObserver(CallObserver observer)
          Removes the given CallObserver from the Terminal.
 void removeObserver(TerminalObserver observer)
          Removes the given observer from the Terminal.
 void removeTerminalListener(TerminalListener listener)
          Removes the given listener from the Terminal.
 

Method Detail

getName

public java.lang.String getName()
Returns the name of the Terminal. Each Terminal possesses a unique name. This name is assigned by the implementation and may or may not carry a real-world interpretation.

Returns:
The name of the Terminal.

getProvider

public Provider getProvider()
Returns the Provider associated with this Terminal. This Provider object is valid throughout the lifetime of the Terminal and does not change once the Terminal is created.

Returns:
The Provider associated with this Terminal.

getAddresses

public Address[] getAddresses()
Returns an array of Address objects associated with this Terminal object. The Terminal object must have at least one Address object associated with it. This list does not change throughout the lifetime of the Terminal object.

Post-conditions:

  1. Let Address[] addrs = this.getAddresses()
  2. addrs.length >= 1
Returns:
An array of Address objects associated with this Terminal.

getTerminalConnections

public TerminalConnection[] getTerminalConnections()
Returns an array of TerminalConnection objects associated with this Terminal. Once a TerminalConnection is added to a Terminal, the Terminal maintains a reference until the TerminalConnection moves into the TerminalConnection.DROPPED state. Therefore, all TerminalConnections returned by this method will never be in the TerminalConnection.DROPPED state. If there are no TerminalConnections associated with this Terminal, this method returns null.

Post-conditions:

  1. Let TerminalConnection tc[] = this.getTerminalConnections()
  2. tc == null or tc.length >= 1
  3. For all i, tc[i].getState() != TerminalConnection.DROPPED
Returns:
An array of TerminalConnection objects associated with this Terminal.

addObserver

public void addObserver(TerminalObserver observer)
                 throws ResourceUnavailableException,
                        MethodNotSupportedException
Adds an observer to the Terminal. The TerminalObserver reports all Terminal-related state changes as events. The Terminal object will report events to this TerminalObserver object for the lifetime of the Terminal object or until the observer is removed with the Terminal.removeObserver() or until the Terminal is no longer observable. In these instances, a TermObservationEndedEv is delivered to the observer as its final event. The observer will receive no events after TermObservationEndedEv unless the observer is explicitly re-added via the Terminal.addObserver() method. Also, once an observer receives an TermObservationEndedEv, it will no longer be reported via the Terminal.getObservers().

If an application attempts to add an instance of an observer already present on this Terminal, this attempt will silently fail, i.e. multiple instances of an observer are not added and no exception will be thrown.

Currently, only the TermObservationEndedEv event is defined by the core package and delivered to the TerminalObserver.

Post-conditions:

  1. observer is an element of this.getObservers()
Parameters:
observer - The observer being added.
Throws:
MethodNotSupportedException - The observer cannot be added at this time
ResourceUnavailableException - The resource limit for the numbers of observers has been exceeded.

getObservers

public TerminalObserver[] getObservers()
Returns a list of all TerminalObservers associated with this Terminal object. If there are no observers associated with this Terminal, this method returns null.

Post-conditions:

  1. Let TerminalObserver[] obs = this.getObservers()
  2. obs == null or obs.length >= 1
Returns:
An array of TerminalObserver objects associated with this Terminal.

removeObserver

public void removeObserver(TerminalObserver observer)
Removes the given observer from the Terminal. If successful, the observer will no longer receive events generated by this Terminal object. As its final event, the TerminalObserver receives a TermObservationEndedEv.

If an observer is not part of the Terminal, then this method fails silently, i.e. no observer is removed an no exception is thrown.

Post-conditions:

  1. A TermObservationEndedEv event is reported to the observer as its final event.
  2. observer is not an element of this.getObservers()
Parameters:
observer - The observer which is being removed.

addCallObserver

public void addCallObserver(CallObserver observer)
                     throws ResourceUnavailableException,
                            MethodNotSupportedException
Adds an observer to a Call object when this Terminal object first becomes part of that Call. This method permits applications to select a Terminal object in which they are interested and automatically have the implementation attach an observer to all present and future Calls which come to this Terminal.
JTAPI v1.0 Semantics
In version 1.0 of the Java Telephony API specification, the application monitored the Terminal object for the TermCallAtTermEv event. This event indicated that a Call has come to this Terminal. Then, applications would manually add an observer to the Call. With this architecture, potentially dangerous race conditions existed while an application was adding an observer to the Call. As a result, this mechanism has been replaced in version 1.1.
JTAPI v1.1 Semantics
In version 1.1 of the specification, the TermCallAtTermEv event does not exist and this method replaces the functionality described above. Instead of monitoring for a TermCallAtTermEv event, the application simply uses the Terminal.addCallObserver() method, and observer will be added to new telephone calls at this Terminal automatically.

If an application attempts to add an instance of a call observer already present on this Terminal, these repeated attempts will silently fail, i.e. multiple instances of a call observer are not added and no exception will be thrown.

When a call observer is added to an Terminal with this method, the following behavior is exhibited by the implementation.

  1. It is immediately associated with any existing calls at the Terminal and a snapshot of those calls are reported to the call observer. For each of these calls, the observer is reported via Call.getObservers().
  2. It is associated with all future calls which come to this Terminal. For each new call, the observer is reported via Call.getObservers().

Note that the definition of the term ".. when a call is at a Terminal" means that the Call contains a Connection which contains a TerminalConnection with this Terminal as its Terminal.

Call Observer Lifetime
For all call observers which are present on Calls because of this method, the following behavior is exhibited with respect to the lifetime of the call.

  1. The call observer receives events until the Call is no longer at this Terminal. In this case, the call observer will be re-applied to the Call if the Call returns to this Terminal at some point in the future.
  2. The call observer is removed with Call.removeObserver(). Note that this only affects the instance of the call observer for that particular call. If the Call subsequently leaves and returns to the Terminal, the observer will be re-applied.
  3. The Call can no longer be monitored by the implementation.
  4. The Call moves into the Call.INVALID state.

When the CallObserver leaves the Call because of one of the reasons above, it receives a CallObservationEndedEv as its final event.

Call Observer on Multiple Addresses and Terminals
It is possible for an application to add CallObservers to more than one Address and Terminal (using Address.addCallObserver() and Terminal.addCallObserver(), respectively). The rules outlined above still apply, with the following additions:

  1. A CallObserver is not added to a Call more than once, even if it has been added to more than one Address/Terminal which are present on the Call.
  2. The CallObserver leaves the call only if ALL of the Addresses and Terminals on which the Call Observer was added leave the Call. If one of those Addresses/Terminals becomes part of the Call again, the call observer is re-applied to the Call.

Post-Conditions:

  1. observer is an element of this.getCallObservers()
  2. observer is an element of Call.getObservers() for each Call associated with the Connections from this.getConnections().
  3. An array of snapshot events are reported to the observer for existing calls associated with this Terminal.
Parameters:
observer - The observer being added.
Throws:
MethodNotSupportedException - The observer cannot be added at this time
ResourceUnavailableException - The resource limit for the numbers of observers has been exceeded.
See Also:
Call

getCallObservers

public CallObserver[] getCallObservers()
Returns a list of all CallObservers associated with this Terminal object. That is, it returns a list of CallObserver objects which have been added via the Terminal.addCallObserver() method. If there are no Call observers associated with this Terminal object, this method returns null.

Post-conditions:

  1. Let CallObserver[] obs = this.getCallObservers()
  2. obs == null or obs.length >= 1
Returns:
An array of CallObserver objects associated with this Address.

removeCallObserver

public void removeCallObserver(CallObserver observer)
Removes the given CallObserver from the Terminal. In other words, it removes a CallObserver which was added via the Terminal.addCallObserver() method. If successful, the observer will no longer be added to new Calls which are presented to this Terminal, however it does not affect CallObservers which have already been added at a Call.

Also, if the CallObserver is not part of the Terminal, then this method fails silently, i.e. no observer is removed and no exception is thrown.

Post-conditions:

  1. observer is not an element of this.getCallObservers()
Parameters:
observer - The CallObserver which is being removed.

getCapabilities

public TerminalCapabilities getCapabilities()
Returns the dynamic capabilities for the instance of the Terminal object. Dynamic capabilities tell the application which actions are possible at the time this method is invoked based upon the implementation's knowledge of its ability to successfully perform the action. This determination may be based upon argument passed to this method, the current state of the call model, or some implementation-specific knowledge. These indications do not guarantee that a particular method will be successful when invoked, however.

The dynamic Terminal capabilities require no additional arguments.

Returns:
The dynamic Terminal capabilities.

getTerminalCapabilities

public TerminalCapabilities getTerminalCapabilities(Terminal terminal,
                                                    Address address)
                                             throws InvalidArgumentException,
                                                    PlatformException
Deprecated. Since JTAPI v1.2. This method has been replaced by the Terminal.getCapabilities() method.

Gets the TerminalCapabilities object with respect to a Terminal and an Address. If null is passed as a Terminal parameter, the general/provider- wide Terminal capabilities are returned.

Note: This method has been replaced in JTAPI v1.2. The Terminal.getCapabilities() method returns the dynamic Terminal capabilities. This method now should simply invoke the Terminal.getCapabilities() method.

Parameters:
address - This argument is ignored in JTAPI v1.2 and later.
terminal - This argument is ignored in JTAPI v1.2 and later.
Throws:
InvalidArgumentException - This exception is never thrown in JTAPI v1.2 and later.
PlatformException - A platform-specific exception occurred.

addTerminalListener

public void addTerminalListener(TerminalListener listener)
                         throws ResourceUnavailableException,
                                MethodNotSupportedException
Adds an listener to the Terminal. The TerminalListener reports all Terminal-related state changes as events. The Terminal object will report events to this TerminalListener object for the lifetime of the Terminal object or until the listener is removed with the Terminal.removeTerminalListener() or until the Terminal is no longer observable. In these instances, a TERMINAL_EVENT_TRANSMISSION_ENDED is delivered to the listener as its final event. The listener will receive no events after TERMINAL_EVENT_TRANSMISSION_ENDED unless the listener is explicitly re-added via the Terminal.addTerminalListener() method. Also, once an listener receives an TERMINAL_EVENT_TRANSMISSION_ENDED, it will no longer be reported via the Terminal.getTerminalListeners().

If an application attempts to add an instance of an listener already present on this Terminal, this attempt will silently fail, i.e. multiple instances of an listener are not added and no exception will be thrown.

Currently, only the TERMINAL_EVENT_TRANSMISSION_ENDED event is defined by the core package and delivered to the TerminalListener.

Post-conditions:

  1. listener is an element of this.getTerminalListeners()
Parameters:
listener - The listener being added.
Throws:
MethodNotSupportedException - The listener cannot be added at this time
ResourceUnavailableException - The resource limit for the numbers of listeners has been exceeded.

getTerminalListeners

public TerminalListener[] getTerminalListeners()
Returns a list of all TerminalListeners associated with this Terminal object. If there are no listeners associated with this Terminal, this method returns null.

Post-conditions:

  1. Let TerminalListener[] obs = this.getTerminalListeners()
  2. obs == null or obs.length >= 1
Returns:
An array of TerminalListener objects associated with this Terminal.

removeTerminalListener

public void removeTerminalListener(TerminalListener listener)
Removes the given listener from the Terminal. If successful, the listener will no longer receive events generated by this Terminal object. As its final event, the TerminalListener receives a TERMINAL_EVENT_TRANSMISSION_ENDED.

If an listener is not part of the Terminal, then this method fails silently, i.e. no listener is removed an no exception is thrown.

Post-conditions:

  1. A TERMINAL_EVENT_TRANSMISSION_ENDED event is reported to the listener as its final event.
  2. listener is not an element of this.getTerminalListeners()
Parameters:
listener - The listener which is being removed.

addCallListener

public void addCallListener(CallListener listener)
                     throws ResourceUnavailableException,
                            MethodNotSupportedException
Adds an listener to a Call object when this Terminal object first becomes part of that Call. This method permits applications to select a Terminal object in which they are interested and automatically have the implementation attach an listener to all present and future Calls which come to this Terminal.
JTAPI v1.0 Semantics
In version 1.0 of the Java Telephony API specification, the application monitored the Terminal object for the TermCallAtTermEv event. This event indicated that a Call has come to this Terminal. Then, applications would manually add an listener to the Call. With this architecture, potentially dangerous race conditions existed while an application was adding an listener to the Call. As a result, this mechanism has been replaced in version 1.1.
JTAPI v1.1 Semantics
In version 1.1 of the specification, the TermCallAtTermEv event does not exist and this method replaces the functionality described above. Instead of monitoring for a TermCallAtTermEv event, the application simply uses the Terminal.addCallListener() method, and listener will be added to new telephone calls at this Terminal automatically.

If an application attempts to add an instance of a call listener already present on this Terminal, these repeated attempts will silently fail, i.e. multiple instances of a call listener are not added and no exception will be thrown.

When a call listener is added to an Terminal with this method, the following behavior is exhibited by the implementation.

  1. It is immediately associated with any existing calls at the Terminal and a snapshot of those calls are reported to the call listener. For each of these calls, the listener is reported via Call.getTerminalListeners().
  2. It is associated with all future calls which come to this Terminal. For each new call, the listener is reported via Call.getTerminalListeners().

Note that the definition of the term ".. when a call is at a Terminal" means that the Call contains a Connection which contains a TerminalConnection with this Terminal as its Terminal.

Call Listener Lifetime
For all call listeners which are present on Calls because of this method, the following behavior is exhibited with respect to the lifetime of the call.

  1. The call listener receives events until the Call is no longer at this Terminal. In this case, the call listener will be re-applied to the Call if the Call returns to this Terminal at some point in the future.
  2. The call listener is removed with Call.removeTerminalListener(). Note that this only affects the instance of the call listener for that particular call. If the Call subsequently leaves and returns to the Terminal, the listener will be re-applied.
  3. The Call can no longer be monitored by the implementation.
  4. The Call moves into the Call.INVALID state.

When the CallListener leaves the Call because of one of the reasons above, it receives a CALL_EVENT_TRANSMISSION_ENDED as its final event.

Call Listener on Multiple Addresses and Terminals
It is possible for an application to add CallListeners to more than one Address and Terminal (using Address.addCallListener() and Terminal.addCallListener(), respectively). The rules outlined above still apply, with the following additions:

  1. A CallListener is not added to a Call more than once, even if it has been added to more than one Address/Terminal which are present on the Call.
  2. The CallListener leaves the call only if ALL of the Addresses and Terminals on which the Call Listener was added leave the Call. If one of those Addresses/Terminals becomes part of the Call again, the call listener is re-applied to the Call.

Call Listener Event level of Granularity

The application shall receive the event reports associated with the methods which are defined in the CallListener interface that the application implements - either the CallListener, ConnectionListener or TerminalConnectionListener interface. Note that the CallListener, ConnectionListener and TerminalConnectionListener form a hierarchy of interfaces, and so provide successively increasing amounts of call information and successively finer-grained event granularity.

Post-Conditions:

  1. listener is an element of this.getCallListeners()
  2. listener is an element of Call.getTerminalListeners() for each Call associated with the Connections from this.getConnections().
  3. An array of snapshot events are reported to the listener for existing calls associated with this Terminal.
Parameters:
listener - The listener being added.
Throws:
MethodNotSupportedException - The listener cannot be added at this time
ResourceUnavailableException - The resource limit for the numbers of listeners has been exceeded.
See Also:
Call

getCallListeners

public CallListener[] getCallListeners()
Returns a list of all CallListeners associated with this Terminal object. That is, it returns a list of CallListener objects which have been added via the Terminal.addCallListener() method. If there are no Call listeners associated with this Terminal object, this method returns null.

Post-conditions:

  1. Let CallListener[] obs = this.getCallListeners()
  2. obs == null or obs.length >= 1
Returns:
An array of CallListener objects associated with this Terminal.

removeCallListener

public void removeCallListener(CallListener listener)
Removes the given CallListener from the Terminal. In other words, it removes a CallListener which was added via the Terminal.addCallListener() method. If successful, the listener will no longer be added to new Calls which are presented to this Terminal, however it does not affect CallListeners which have already been added at a Call.

Also, if the CallListener is not part of the Terminal, then this method fails silently, i.e. no listener is removed and no exception is thrown.

Post-conditions:

  1. listener is not an element of this.getCallListeners()
Parameters:
listener - The CallListener which is being removed.

JSR-043: JTAPI-1.4

Send comments to: JSR-43@ectf.org