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
-
addCallObserver(CallObserver)
- Adds an observer to a Call object when this Terminal object first becomes
part of that Call.
-
addObserver(TerminalObserver)
- Adds an observer to the Terminal.
-
getAddresses()
- Returns an array of Address objects associated with this Terminal object.
-
getCallObservers()
- Returns a list of all CallObservers associated with this Terminal
object.
-
getName()
- Returns the name of the Terminal.
-
getObservers()
- Returns a list of all TerminalObservers associated with this Terminal object.
-
getProvider()
- Returns the Provider associated with this Terminal.
-
getTerminalCapabilities(Terminal, Address)
- Gets the TerminalConnectionCapabilities object with respect to a Terminal and an
Address.
-
getTerminalConnections()
- Returns an array of TerminalConnection objects associated with this
Terminal.
-
removeCallObserver(CallObserver)
- Removes the given CallObserver from the Terminal.
-
removeObserver(TerminalObserver)
- Removes the given observer from the Terminal.
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.
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.
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:
- (this.getProvider()).getState() == Provider.IN_SERVICE.
The post-conditions for this method are:
- (this.getProvider()).getState() == Provider.IN_SERVICE
- Let Address[] addrs = this.getAddresses()
- 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.
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:
- (this.getProvider()).getState() == Provider.IN_SERVICE
The post-conditions for this method are:
- (this.getProvider()).getState() == Provider.IN_SERVICE
- Let TerminalConnection tc[] = this.getTerminalConnections()
- tc == null or tc.length >= 1
- 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.
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:
- 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.
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:
- Let TerminalObserver[] obs = this.getObservers()
- obs == null or obs.length >= 1
- Returns:
- An array of TerminalObserver objects associated with this
Terminal.
- Throws: PlatformException
- A platform-specific exception occurred.
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:
- observer is not an element of this.getObservers()
- Parameters:
- observer - The observer which is being removed.
- Throws: PlatformException
- A platform-specific exception occurred.
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()
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:
- Let CallObserver[] obs = this.getCallObservers()
- obs == null or obs.length >= 1
- Returns:
- An array of CallObserver objects associated with this
Terminal.
- Throws: PlatformException
- A platform-specific exception occurred.
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:
- observer is not an element of this.getCallObservers()
- Parameters:
- observer - The CallObserver which is being removed.
- Throws: PlatformException
- A platform-specific exception occurred.
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