Interface java.telephony.Terminal
All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface java.telephony.Terminal

public interface Terminal
extends Object
A Terminal represents a physical hardware endpoint connected to the telephony network. 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. A wide variety of hardware can act as Terminals.

Terminal objects are distinguished from one another by their names; each Terminal has a unique name. How Terminals are named within a Provider is up to the implementaion. Typically, when choosing a Terminal, applications simply obtain the names of the available Terminals. This list is presented to the user who will be able to identify the desired Terminal. Typically, the user will have no trouble identifying the desired Terminal. Therefore, the portability of applications is not affected by the lack of standardization of Terminal names. A common way to name Terminals is by a "primary" telephone number Address at that Terminal. This is only an example, however, and implementations need not name their Terminals in this manner.

There may be many Terminals associated with a Provider. The application obtains a list of these Terminals via the Provider.getTerminals() method. Applications may obtain a specific Terminal object given its name via the Provider.getTerminal(name) method. These two methods represent the manner in which applications obtain Terminal objects. Applications never create Terminal objects, either through the Provider or using the "new" constructor.

A Terminal may have one or more Address objects associated with it. In real-terms, this corresponds to telephones having multiple telephone numbers associated with a Terminal. Address objects are the logical endpoints of telephone calls, described by a Connection object between the Call and Address. Terminals act as the physical endpoint of a Call. A Connection object may have zero or more TerminalConnection objects. These TerminalConnection objects describe which Terminals act as the physical endpoint of the Call for that Connection's Address object.

Terminal objects are responsible for reporting information about telephone calls which were created before the Provider. In other words, Terminal object must report on all TerminalConnection objects which are part of all telephone calls in the Provider's domain--even if these telephone Calls were created before the Provider was created.

More than one Terminal object may share the same Address object. In real- terms, this corresponds to a telephone number appearing on more than one telephone terminal. Because each Terminal may be in a different state w.r.t the telephone call, Terminal objects are associated with Calls via the TerminalConnection object. The TerminalConnection object describes the specific state of the Terminal with respect to the Call.

All changes in a Terminal object are reported via the TerminalObserver interface. Applications instantiate an object which implements this interface and begins this delivery of events to this object using the Terminal.addObserver() method.

See Also:
TerminalObserver

Method Index

 o addCallObserver(CallObserver)
Adds an observer to a Call object when this Terminal object first becomes part of that Call.
 o addObserver(TerminalObserver)
Adds an observer to the Terminal.
 o getAddresses()
Returns an array of Address objects associated with this Terminal object.
 o getCallObservers()
Returns a list of all CallObservers associated with this Terminal object.
 o getName()
Returns the name of the Terminal.
 o getObservers()
Returns a list of all TerminalObservers associated with this Terminal object.
 o getProvider()
Returns the Provider associated with this Terminal.
 o getTerminalCapabilities(Terminal, Address)
Gets the TerminalConnectionCapabilities object with respect to a Terminal and an Address.
 o getTerminalConnections()
Returns an array of TerminalConnection objects associated with this Terminal.
 o removeCallObserver(CallObserver)
Removes the given CallObserver from the Terminal.
 o removeObserver(TerminalObserver)
Removes the given observer from the Terminal.

Methods

 o getName
  public abstract String getName() throws PlatformException
Returns the name of the Terminal. Each Terminal possesses a unique name, which is assigned to it by the JTAPI implementation.

Returns:
The name of the Terminal.
Throws: PlatformException
A platform-specific exception occurred.
 o getProvider
  public abstract Provider getProvider() throws PlatformException
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.
Throws: PlatformException
A platform-specific exception occurred.
 o getAddresses
  public abstract Address[] getAddresses() throws InvalidStateException, PlatformException
Returns an array of Address objects associated with this Terminal object. The Terminal object must have at least one Address object associated with it. The Provider must be in the Provider.IN_SERVICE state for this method to be valid.

The pre-conditions for this method are:

  1. (this.getProvider()).getState() == Provider.IN_SERVICE.

The post-conditions for this method are:

  1. (this.getProvider()).getState() == Provider.IN_SERVICE
  2. Let Address[] addrs = this.getAddresses()
  3. addrs.length >= 1

Returns:
An array of Address objects associated with this Terminal.
Throws: InvalidStateException
The Provider is not IN_SERVICE.
Throws: PlatformException
A platform-specific exception occurred.
 o getTerminalConnections
  public abstract TerminalConnection[] getTerminalConnections() throws InvalidStateException, PlatformException
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. The Provider must be IN_SERVICE for this method to be valid. If there are no TerminalConnections associated with this Terminal, then this method returns null.

The pre-conditions for this method are:

  1. (this.getProvider()).getState() == Provider.IN_SERVICE

The post-conditions for this method are:

  1. (this.getProvider()).getState() == Provider.IN_SERVICE
  2. Let TerminalConnection tc[] = this.getTerminalConnections()
  3. tc == null or tc.length >= 1
  4. For all i, tc[i].getState() != TerminalConnection.DROPPED

Returns:
An array of TerminalConnection objects associated with this Terminal.
Throws: InvalidStateException
The Provider is not IN_SERVICE.
Throws: PlatformException
A platform-specific exception occurred.
 o addObserver
  public abstract void addObserver(TerminalObserver observer) throws ResourceUnavailableException, PlatformException
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().

If an application attempts to add an instance of an observer already present on this Terminal, 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:

  1. observer is an element of this.getObservers()

Parameters:
observer - The observer being added.
Throws: ResourceUnavailableException
The resource limit for the numbers of observers has been exceeded.
Throws: PlatformException
A platform-specific exception occurred.
 o getObservers
  public abstract TerminalObserver[] getObservers() throws PlatformException
Returns a list of all TerminalObservers associated with this Terminal object. If there are no observers associated with this Terminal, this method returns null.

There are no pre-conditions for this method.

The post-conditions for this method are:

  1. Let TerminalObserver[] obs = this.getObservers()
  2. obs == null or obs.length >= 1

Returns:
An array of TerminalObserver objects associated with this Terminal.
Throws: PlatformException
A platform-specific exception occurred.
 o removeObserver
  public abstract void removeObserver(TerminalObserver observer) throws PlatformException
Removes the given observer from the Terminal. If successful, the observer will no longer receive events generated by this Terminal object.

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.

There are no pre-conditions for this method.

The post-condition predicates for this method are:

  1. observer is not an element of this.getObservers()

Parameters:
observer - The observer which is being removed.
Throws: PlatformException
A platform-specific exception occurred.
 o addCallObserver
  public abstract void addCallObserver(CallObserver observer) throws ResourceUnavailableException, PlatformException
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 each Call in which this Terminal is included.

For example, an application may want to monitor the telephony call activity associated with a particular terminal. In version 1.0 of the Java Telephony specification, the application must first monitor the Terminal for the TermCallAtTermEv event and them manually add an observer to the new Call object.

In version 1.1 of the specification, the TermCallAtTermEv does not exist and this method replaces the functionality described above. Instead of monitoring for a TermCallAtTermEv event, this application simply uses the Terminal.addCallObserver() method, and observer will be added to new telephone calls at the Terminal automatically.

The CallObserver is removed from the call when the Call leaves the Terminal.

If an application attempts to add an instance of an observer already present on the 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.

A call observer added on an Terminal object behaves similarly to A call observer added on a Call object, except that it provides a snapshot of all calls active on that Terminal.

Parameters:
observer - The observer being added.
Throws: ResourceUnavailableException
The resource limit for the numbers of observers has been exceeded.
Throws: PlatformException
A platform-specific exception occurred.
See Also:
getObservers()

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

There are no pre-conditions for this method.

The post-conditions for this method are:

  1. Let CallObserver[] obs = this.getCallObservers()
  2. obs == null or obs.length >= 1

Returns:
An array of CallObserver objects associated with this Terminal.
Throws: PlatformException
A platform-specific exception occurred.
 o removeCallObserver
  public abstract void removeCallObserver(CallObserver observer) throws PlatformException
Removes the given CallObserver from the Terminal. In other words, it removes a CallObserver which was added via the 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 to a Call.

Also, if a CallObserver is not part of the Terminal, 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:

  1. observer is not an element of this.getCallObservers()

Parameters:
observer - The CallObserver which is being removed.
Throws: PlatformException
A platform-specific exception occurred.
 o getTerminalCapabilities
  public abstract TerminalCapabilities getTerminalCapabilities(Terminal terminal,
                                                               Address address) throws InvalidArgumentException, PlatformException
Gets the TerminalConnectionCapabilities object with respect to a Terminal and an Address. If null is passed as a Terminal parameter, the general/provider-wide Terminal Connection capabilities are returned.


All Packages  Class Hierarchy  This Package  Previous  Next  Index