Interface java.telephony.Address
All Packages Class Hierarchy This Package Previous Next Index
Interface java.telephony.Address
- public interface Address
- extends Object
An Address object represents what we commonly think of as a "telephone
number." In more rare implementations where the underlying network is not
a telephony network, this address may represent something else. For example,
if the underlying network is IP, this address might represent an IP
address (e.g. 18.203.0.49). An Address object has a "name" which corresponds
to this telephony address which does not change throughout the lifetime of
the object.
An Address can be associated with a Call via a Connection object. The
Address object represents the logical endpoint of a telephone call. One the
most simplistic view, an application can see a telephone call as being from
one Address to another. When the Connection object moves into the
Connection.DISCONNECTED state, the Address object loses its reference to the
Connection object. This implies that the Connection object is no longer
reported via the Address.getConnection method.
Address objects are responsible for reporting information about telephone
calls which were created before the Provider. In other words, Address
object must report on all Connection 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.
Address objects may be associated with zero or many Terminal objects. An
Address which is associated with more than one Terminal object reflects the
fact that a telephone number may appear on more than one physical telephone
set.
All changes in an Address object are reported via the AddressObserver
interface. Applications instantiate an object which implements this
interface and begins this delivery of events to this object using the
Address.addObserver() method.
- See Also:
- AddressObserver
-
addCallObserver(CallObserver)
- Adds an observer to a Call object when this Address object first becomes
part of that Call.
-
addObserver(AddressObserver)
- Adds an observer to the Address.
-
getAddressCapabilities(Terminal)
- Gets the AddressCapabilities object with respect to a Terminal
If null is passed as a Terminal parameter, the general/provider-wide
Address capabilities are returned.
-
getCallObservers()
- Returns a list of all CallObservers associated with this Address
object.
-
getConnections()
- Returns an array of Connection object currently associated with this
Address object.
-
getName()
- Returns the name of the Address.
-
getObservers()
- Returns a list of all AddressObservers associated with this Address
object.
-
getProvider()
- Returns the Provider associated with this Address.
-
getTerminals()
- Returns an array of Terminals associated with this Address object.
-
removeCallObserver(CallObserver)
- Removes the given CallObserver from the Address.
-
removeObserver(AddressObserver)
- Removes the given observer from the Address.
getName
public abstract String getName() throws PlatformException
- Returns the name of the Address. Each Address possesses a unique
name. This name corresponds to its telephone number address string.
- Returns:
- The name of the Address.
- Throws: PlatformException
- A platform-specific exception occurred.
getProvider
public abstract Provider getProvider() throws PlatformException
- Returns the Provider associated with this Address. This Provider object
is valid throughout the lifetime of the Address and does not change
once the Address is created.
- Returns:
- The Provider associated with this Address.
- Throws: PlatformException
- A platform-specific exception occurred.
getTerminals
public abstract Terminal[] getTerminals() throws PlatformException
- Returns an array of Terminals associated with this Address object.
If no Terminals are associated with this Address getTerminals()
returns NULL.
- Returns:
- An array of Terminal objects associated with this Address.
- Throws: PlatformException
- A platform-specific exception occurred.
getConnections
public abstract Connection[] getConnections() throws InvalidStateException, PlatformException
- Returns an array of Connection object currently associated with this
Address object. When a Connection moves into the Connection.DISCONNECTED
state the Address object loses the reference. Therefore, all Connections
returned by this method will never be in the Connection.DISCONNECTED state.
If the Address has no Connections associated with it, this method
returns the null. The Provider must be in the Provider.IN_SERVICE state
in order for this method to be valid.
The pre-conditions for this method are:
- (this.getProvider()).getState() == Provider.IN_SERVICE
The following post-conditions apply:
- Let Connection c[] = this.getConnections()
- c == null or c.length >= 1
- For all i, c[i].getState != Connection.DISCONNECTED
- Returns:
- An array of Connection objects associated with this Address.
- Throws: InvalidStateException
- The Provider is not IN_SERVICE.
- Throws: PlatformException
- A platform-specific exception occurred.
addObserver
public abstract void addObserver(AddressObserver observer) throws ResourceUnavailableException, PlatformException
- Adds an observer to the Address. The AddressObserver reports all
Address-related state changes as events. The Address object will report
events to this AddressObserver object for the lifetime of the Address
object or until the observer is removed with the
Address.removeObserver() method.
If an application attempts to add an instance of an observer already
present on this Address, 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.
This method is valid anytime and has no pre-conditions.
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 AddressObserver[] getObservers() throws PlatformException
- Returns a list of all AddressObservers associated with this Address
object. If there are no observers associated with this Address object,
this method returns null.
There are no pre-conditions for this method.
The post-conditions for this method are:
- Let AddressObserver[] obs = this.getObservers()
- obs == null or obs.length >= 1
- Returns:
- An array of AddressObserver objects associated with this
Address.
- Throws: PlatformException
- A platform-specific exception occurred.
removeObserver
public abstract void removeObserver(AddressObserver observer) throws PlatformException
- Removes the given observer from the Address. If successful, the observer
will no longer receive events generated by this Address object.
Also, if an observer is not part of the Address, 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 Address object first becomes
part of that Call. This method permits applications to select a Address
object in which they are interested and automatically have the
implementation attach an observer to each Call in which this Address
is included.
For example, an application may want to monitor the telephone call
activity associated with a particular address. In version 1.0 of the
Java Telephony specification, the application must first monitor the
Address for the AddrCallAtAddrEv event and them manually add an observer
to the new Call object.
In version 1.1 of the specification, the AddrCallAtAddrEv does not exist
and this method replaces the functionality described above. Instead of
monitoring for a AddrCallAtAddrEv event, this application simply uses
the Address.addCallObserver() method, and observer will be added to
new telephone calls at the Address automatically.
The CallObserver is removed from the call when the Call leaves this
Address.
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 Address object behaves similarly to
a call observer added on a Call object, except that it provides
a snapshot of all calls active on that Address.
- 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 Address
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 Address 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
Address.
- Throws: PlatformException
- A platform-specific exception occurred.
removeCallObserver
public abstract void removeCallObserver(CallObserver observer) throws PlatformException
- Removes the given CallObserver from the Address. 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 Address, however it does not affect
CallObservers which have already been added to a Call.
Also, if a CallObserver is not part of the Address, 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.
getAddressCapabilities
public abstract AddressCapabilities getAddressCapabilities(Terminal terminal) throws InvalidArgumentException, PlatformException
- Gets the AddressCapabilities object with respect to a Terminal
If null is passed as a Terminal parameter, the general/provider-wide
Address capabilities are returned.
All Packages Class Hierarchy This Package Previous Next Index