|
JSR-043: JTAPI-1.4 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
A Terminal
represents a physical hardware endpoint connected to the
telephony domain.
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.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.
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.
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.
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.
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 |
public java.lang.String getName()
public Provider getProvider()
public Address[] getAddresses()
Post-conditions:
public TerminalConnection[] getTerminalConnections()
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:
public void addObserver(TerminalObserver observer) throws ResourceUnavailableException, MethodNotSupportedException
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:
observer
- The observer being added.MethodNotSupportedException
- The observer cannot be added at this timeResourceUnavailableException
- The resource limit for the
numbers of observers has been exceeded.public TerminalObserver[] getObservers()
Post-conditions:
public void removeObserver(TerminalObserver observer)
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:
observer
- The observer which is being removed.public void addCallObserver(CallObserver observer) throws ResourceUnavailableException, MethodNotSupportedException
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.
Call.getObservers()
.
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.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.
Call.INVALID
state.
When the CallObserver leaves the Call because of one of the reasons above, it receives a CallObservationEndedEv as its final event.
Address.addCallObserver()
and
Terminal.addCallObserver()
, respectively). The rules outlined
above still apply, with the following additions:
Post-Conditions:
observer
- The observer being added.MethodNotSupportedException
- The observer cannot be added at this timeResourceUnavailableException
- The resource limit for the
numbers of observers has been exceeded.Call
public CallObserver[] getCallObservers()
Terminal.addCallObserver()
method. If
there are no Call observers associated with this Terminal object, this
method returns null.
Post-conditions:
public void removeCallObserver(CallObserver observer)
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:
observer
- The CallObserver which is being removed.public TerminalCapabilities getCapabilities()
The dynamic Terminal capabilities require no additional arguments.
public TerminalCapabilities getTerminalCapabilities(Terminal terminal, Address address) throws InvalidArgumentException, PlatformException
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.
address
- This argument is ignored in JTAPI v1.2 and later.terminal
- This argument is ignored in JTAPI v1.2 and later.InvalidArgumentException
- This exception is never thrown in
JTAPI v1.2 and later.PlatformException
- A platform-specific exception occurred.public void addTerminalListener(TerminalListener listener) throws ResourceUnavailableException, MethodNotSupportedException
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:
listener
- The listener being added.MethodNotSupportedException
- The listener cannot be added at this timeResourceUnavailableException
- The resource limit for the
numbers of listeners has been exceeded.public TerminalListener[] getTerminalListeners()
Post-conditions:
public void removeTerminalListener(TerminalListener listener)
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:
listener
- The listener which is being removed.public void addCallListener(CallListener listener) throws ResourceUnavailableException, MethodNotSupportedException
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.
Call.getTerminalListeners()
.
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.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.
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.
Address.addCallListener()
and
Terminal.addCallListener()
, respectively). The rules outlined
above still apply, with the following additions:
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:
listener
- The listener being added.MethodNotSupportedException
- The listener cannot be added at this timeResourceUnavailableException
- The resource limit for the
numbers of listeners has been exceeded.Call
public CallListener[] getCallListeners()
Terminal.addCallListener()
method. If
there are no Call listeners associated with this Terminal object, this
method returns null.
Post-conditions:
public void removeCallListener(CallListener listener)
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:
listener
- The CallListener which is being removed.
|
JSR-043: JTAPI-1.4 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |