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

Method Index

 o addCallObserver(CallObserver)
Adds an observer to a Call object when this Address object first becomes part of that Call.
 o addObserver(AddressObserver)
Adds an observer to the Address.
 o 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.
 o getCallObservers()
Returns a list of all CallObservers associated with this Address object.
 o getConnections()
Returns an array of Connection object currently associated with this Address object.
 o getName()
Returns the name of the Address.
 o getObservers()
Returns a list of all AddressObservers associated with this Address object.
 o getProvider()
Returns the Provider associated with this Address.
 o getTerminals()
Returns an array of Terminals associated with this Address object.
 o removeCallObserver(CallObserver)
Removes the given CallObserver from the Address.
 o removeObserver(AddressObserver)
Removes the given observer from the Address.

Methods

 o 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.
 o 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.
 o 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.
 o 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:

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

The following post-conditions apply:

  1. Let Connection c[] = this.getConnections()
  2. c == null or c.length >= 1
  3. 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.
 o 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:

  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 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:

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

Returns:
An array of AddressObserver objects associated with this Address.
Throws: PlatformException
A platform-specific exception occurred.
 o 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:

  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 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()

 o 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:

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

Returns:
An array of CallObserver objects associated with this Address.
Throws: PlatformException
A platform-specific exception occurred.
 o 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:

  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 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