javax.telephony
Interface Address

All Known Subinterfaces:

ACDAddress, ACDManagerAddress, CallCenterAddress, CallControlAddress, MobileAddress, RouteAddress

public interface Address

An Address object represents what we commonly think of as a "telephone number".

Introduction

In implementations where the underlying network is not a telephone 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 string name which corresponds to this telephone address. The Address object does not attempt to interpret this string in any way. This name is first assigned when the Address object is created and does not change throughout the lifetime of the object. The method Address.getName() returns the name of the Address object.

Address objects may be classified into two categories: local and remote. Local Address objects are those addresses which are part of the Provider's local domain. These Address objects are created by the implementation of the Provider object when it is first instantiated. All of the Provider's local addresses are reported via the Provider.getAddresses() method. Remote Address 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 Addresses are not reported via the Provider.getAddresses() method. Note that applications never explicitly create new Address objects.

Address and Terminal Objects

Address and Terminal objects exist in a many-to-many relationship. An Address object may have zero or more Terminals associated with it. Each Terminal associated with an Address must reflect its association with the Address. Since the implementation creates Address (and Terminal) objects, it is responsible for insuring the correctness of these relationships. The Terminals associated with an Address is given by the Address.getTerminals() method.

An association between an Address and Terminal indicates that the Terminal is addressable via that Address. 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.

Address and Call Objects

Address objects represent the logical endpoints of a telephone call. A logical view of a telephone call views the call as originating from one Address endpoint and terminates at another Address endpoint.

Address objects are related to Call objects via the Connection object. The Connection object has a state which describes the current relationship between the Call and the Address. Each Address object may be part of more than one telephone call, and in each case, is represented by a separate Connection object. The Address.getConnections() method returns all Connection objects currently associated with the Call.

An Address is associated with a Call until the Connection moves into the Connection.DISCONNECTED state. At that time, the Connection is no longer reported via the Address.getConnections() method. Therefore, the Address.getConnections() method will never report a Connection in the Connection.DISCONNECTED state.

Existing Telephone Calls

The Java Telephony API specification states that the implementation is responsible for reporting all existing telephone calls when a Provider is first created. This implies that an Address object must report information regarding existing telephone calls to that Address. In other words, Address objects must reports all Connection objects which represent existing telephone calls.

Address Listeners and Events

All changes in an Address object are reported via the AddressListener interface. Applications instantiate an object which implements this interface and begins this delivery of events to this object using the Address.addAddressListener() method. All Address-related events extend the AddressEvent interface provided in the core package. Applications receive events on an listener until the listener is removed via the Address.removeAddressListener() method or until the Address is no longer observable. In these instances, each AddressListener receives a ADDRESS_EVENT_TRANSMISSION_ENDED as its final event.

Currently in the core package, the only Address-related event is ADDRESS_EVENT_TRANSMISSION_ENDED.

Call Listeners

At times, applications may want to monitor a particular Address for all Calls which come to that Address. For example, a customer service agent application is only interested in telephone calls associated with a particular agent address. To achieve this sort of Address-based Call monitoring applications may add CallListeners to an Address via the Address.addCallListener() method.

When a CallListener is added to an Address, this listener instance is immediately added to all Calls at this Address and is added to all Calls which come to this Address in the future. These listeners remain on the telephone call as long as the Address is associated with the telephone call.

The specification of Address.addCallListener() contains more precise semantics.

See Also:

AddressListener, CallListener

Method Summary

void	addAddressListener(AddressListener listener) Adds an listener to the Address.
void	addCallListener(CallListener listener) Adds an listener to a Call object when this Address object first becomes part of that Call.
void	addCallObserver(CallObserver observer) Adds an observer to a Call object when this Address object first becomes part of that Call.
void	addObserver(AddressObserver observer) Adds an observer to the Address.
AddressCapabilities	getAddressCapabilities(Terminal terminal) Deprecated. Since JTAPI v1.2. This method has been replaced by the Address.getCapabilities() method.
AddressListener[]	getAddressListeners() Returns a list of all JAddressListeners associated with this Address object.
CallListener[]	getCallListeners() Returns a list of all CallListeners associated with this Address object.
CallObserver[]	getCallObservers() Returns a list of all CallObservers associated with this Address object.
AddressCapabilities	getCapabilities() Returns the dynamic capabilities for this instance of the Address object.
Connection[]	getConnections() Returns an array of Connection objects currently associated with this Address object at the instant the getConnections() method is called.
java.lang.String	getName() Returns the name of the Address.
AddressObserver[]	getObservers() Returns a list of all AddressObservers associated with this Address object.
Provider	getProvider() Returns the Provider associated with this Address.
Terminal[]	getTerminals() Returns an array of Terminals associated with this Address object.
void	removeAddressListener(AddressListener listener) Removes the given listener from the Address.
void	removeCallListener(CallListener listener) Removes the given CallListener from the Address.
void	removeCallObserver(CallObserver observer) Removes the given CallObserver from the Address.
void	removeObserver(AddressObserver observer) Removes the given observer from the Address.

Method Detail

getName

public java.lang.String getName()

Returns the name of the Address. Each Address possesses a unique name. This name is a way of referencing an endpoint in a telephone call.

Returns:

The name of this Address.

getProvider

public Provider getProvider()

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.

getTerminals

public Terminal[] getTerminals()

Returns an array of Terminals associated with this Address object. If no Terminals are associated with this Address, this method returns null. This list does not change throughout the lifetime of the Address object.

Returns:

An array of Terminal objects associated with this Address.

getConnections

public Connection[] getConnections()

Returns an array of Connection objects currently associated with this Address object at the instant the getConnections() method is called. When a Connection moves into the Connection.DISCONNECTED state, the Address object loses the reference to the Connection and the Connection no longer returned by this method. 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 null.

Post-conditions:

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.

addObserver

public void addObserver(AddressObserver observer)
                 throws ResourceUnavailableException,
                        MethodNotSupportedException

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 or until the Address is no longer observable. In these instances, a AddrObservationEndedEv is delivered to the observer as its final event. The observer will receive no events after AddrObservationEndedEv unless the observer is explicitly re-added via the Address.addObserver() method. Also, once an observer receives an AddrObservationEndedEv, it will no longer be reported via the Address.getObservers().

If an application attempts to add an instance of an observer already present on this Address, this attempt will silently fail, i.e. multiple instances of an observer are not added and no exception will be thrown.

Currently, only the AddrObservationEndedEv event is defined by the core package and delivered to the AddressObserver.

Post-conditions:

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

Parameters:

observer - The observer being added.

Throws:

MethodNotSupportedException - The observer cannot be added at this time

ResourceUnavailableException - The resource limit for the number of observers has been exceeded.

getObservers

public AddressObserver[] getObservers()

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.

Post-conditions:

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

Returns:

An array of AddressObserver objects associated with this Address.

removeObserver

public void removeObserver(AddressObserver observer)

Removes the given observer from the Address. If successful, the observer will no longer receive events generated by this Address object. As its final event, the AddressObserver receives is an AddrObservationEndedEv event.

If an observer is not part of the Address, then this method fails silently, i.e. no observer is removed and no exception is thrown.

Post-conditions:

1. An AddrObservationEndedEv event is reported to the observer as its final event.
2. observer is not an element of this.getObservers()

Parameters:

observer - The observer which is being removed.

addCallObserver

public void addCallObserver(CallObserver observer)
                     throws ResourceUnavailableException,
                            MethodNotSupportedException

Adds an observer to a Call object when this Address object first becomes part of that Call. This method permits applications to select an Address object in which they are interested and automatically have the implementation attach an observer to all present and future Calls which come to this Address.

JTAPI v1.0 Semantics

In version 1.0 of the Java Telephony API specification, the application monitored the Address object for the AddrCallAtAddrEv event. This event indicated that a Call has come to this Address. Then, applications would manually add an observer to the Call. With this architecture, potentially dangerous race conditions existed while an application was adding an observer to the Call. As a result, this mechanism has been replaced in version 1.1.

JTAPI v1.1 Semantics

In version 1.1 of the specification, the AddrCallAtAddrEv event 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 this Address automatically.

If an application attempts to add an instance of a call observer already present on this Address, 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 Address with this method, the following behavior is exhibited by the implementation.

1. It is immediately associated with any existing calls at the Address and a snapshot of those calls are reported to the call observer. For each of these calls, the observer is reported via Call.getObservers().
2. It is associated with all future calls which comes to this Address. For each new call, the observer is reported via Call.getObservers().

Note that the definition of the term ".. when a call is at an Address" means that the Call contains one Connection which has this Address as its Address.

Call Observer Lifetime

For all call observers which are present on Calls because of this method, the following behavior is exhibited with respect to the lifetime of the call.

1. The call observer receives events until the Call is no longer at this Address. In this case, the call observer will be re-applied to the Call if the Call returns to this Address at some point in the future.
2. The call observer is removed with 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 Address, the observer will be re-applied.
3. The Call can no longer be monitored by the implementation.
4. The Call moves into the Call.INVALID state.

When the CallObserver leaves the Call because of one of the reasons above, it receives a CallObservationEndedEv as its final event.

Call Observer on Multiple Addresses and Terminals

It is possible for an application to add CallObservers at more than one Address and Terminal (using Address.addCallObserver() and Terminal.addCallObserver(), respectively). The rules outlined above still apply, with the following additions:

1. A CallObserver is not added to a Call more than once, even if it has been added to more than one Address/Terminal which are present on the Call.
2. The CallObserver leaves the call only if all of the Addresses and Terminals on which the Call Observer was added leave the Call. If one of those Addresses/Terminals becomes part of the Call again, the call observer is re-applied to the Call.

Post-Conditions:

1. observer is an element of this.getCallObservers()
2. observer is an element of Call.getObservers() for each Call associated with the Connections from this.getConnections().
3. An array of snapshot events are reported to the observer for existing calls associated with this Address.

Parameters:

observer - The observer being added.

Throws:

MethodNotSupportedException - The observer cannot be added at this time.

ResourceUnavailableException - The resource limit for the numbers of observers has been exceeded.

See Also:

Call

getCallObservers

public CallObserver[] getCallObservers()

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 Address.addCallObserver() method. If there are no CallObservers associated with this Address object, this method returns null.

Post-conditions:

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

Returns:

An array of CallObserver objects associated with this Address.

removeCallObserver

public void removeCallObserver(CallObserver observer)

Removes the given CallObserver from the Address. In other words, it removes a CallObserver which was added via the Address.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 at a Call.

Also, if the CallObserver is not part of the Address, then this method fails silently, i.e. no observer is removed and no exception is thrown.

Post-conditions:

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

Parameters:

observer - The CallObserver which is being removed.

getCapabilities

public AddressCapabilities getCapabilities()

Returns the dynamic capabilities for this instance of the Address object. Dynamic capabilities tell the application which actions are possible at the time this method is invoked based upon the implementations knowledge of its ability to successfully perform the action. This determination may be based upon argument passed to this method, the current state of the call model, or some implementation-specific knowledge. These indications do not guarantee that a particular method will succeed when invoked, however.

The dynamic Address capabilities require no additional arguments.

Returns:

The dynamic Address capabilities.

getAddressCapabilities

public AddressCapabilities getAddressCapabilities(Terminal terminal)
                                           throws InvalidArgumentException,
                                                  PlatformException

Deprecated. Since JTAPI v1.2. This method has been replaced by the Address.getCapabilities() method.

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.

Note: This method has been replaced in JTAPI v1.2. The Address.getCapabilities() method returns the dynamic Address capabilities. This method now should simply invoke the Address.getCapabilities() method.

Parameters:

terminal - This argument is ignored in JTAPI v1.2 and later.

Throws:

InvalidArgumentException - This exception is never thrown in JTAPI v1.2 and later.

PlatformException - A platform-specific exception occurred.

addAddressListener

public void addAddressListener(AddressListener listener)
                        throws ResourceUnavailableException,
                               MethodNotSupportedException

Adds an listener to the Address. The AddressListener reports all Address- related state changes as events. The Address object will report events to this AddressListener object for the lifetime of the Address object or until the listener is removed with the Address.removeAddressListener() method or until the Address is no longer observable. In these instances, a ADDRESS_EVENT_TRANSMISSION_ENDED is delivered to the listener as its final event. The listener will receive no events after ADDRESS_EVENT_TRANSMISSION_ENDED unless the listener is explicitly re-added via the Address.addAddressListener() method. Also, once an listener receives an ADDRESS_EVENT_TRANSMISSION_ENDED, it will no longer be reported via the Address.getAddressListeners().

If an application attempts to add an instance of an listener already present on this Address, this attempt will silently fail, i.e. multiple instances of an listener are not added and no exception will be thrown.

Currently, only the ADDRESS_EVENT_TRANSMISSION_ENDED event is defined by the core package and delivered to the AddressListener.

Post-conditions:

1. listener is an element of this.getAddressListeners()

Parameters:

listener - The listener being added.

Throws:

MethodNotSupportedException - The listener cannot be added at this time

ResourceUnavailableException - The resource limit for the number of listeners has been exceeded.

getAddressListeners

public AddressListener[] getAddressListeners()

Returns a list of all JAddressListeners associated with this Address object. If there are no listeners associated with this Address object, this method returns null.

Post-conditions:

1. Let AddressListener[] obs = this.getAddressListeners()
2. obs == null or obs.length >= 1

Returns:

An array of AddressListener objects associated with this Address.

removeAddressListener

public void removeAddressListener(AddressListener listener)

Removes the given listener from the Address. If successful, the listener will no longer receive events generated by this Address object. As its final event, the AddressListener receives is an ADDRESS_EVENT_TRANSMISSION_ENDED event.

If an listener is not part of the Address, then this method fails silently, i.e. no listener is removed and no exception is thrown.

Post-conditions:

1. An ADDRESS_EVENT_TRANSMISSION_ENDED event is reported to the listener as its final event.
2. listener is not an element of this.getAddressListeners()

Parameters:

listener - The listener which is being removed.

addCallListener

public void addCallListener(CallListener listener)
                     throws ResourceUnavailableException,
                            MethodNotSupportedException

Adds an listener to a Call object when this Address object first becomes part of that Call. This method permits applications to select an Address object in which they are interested and automatically have the implementation attach an listener to all present and future Calls which come to this Address.

JTAPI v1.0 Semantics

In version 1.0 of the Java Telephony API specification, the application monitored the Address object for the AddrCallAtAddrEv event. This event indicated that a Call has come to this Address. Then, applications would manually add an listener to the Call. With this architecture, potentially dangerous race conditions existed while an application was adding an listener to the Call. As a result, this mechanism has been replaced in version 1.1.

JTAPI v1.1 Semantics

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

If an application attempts to add an instance of a call listener already present on this Address, 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 Address with this method, the following behavior is exhibited by the implementation.

1. It is immediately associated with any existing calls at the Address and a snapshot of those calls are reported to the call listener. For each of these calls, the listener is reported via Call.getAddressListeners().
2. It is associated with all future calls which comes to this Address. For each new call, the listener is reported via Call.getAddressListeners().

Note that the definition of the term ".. when a call is at an Address" means that the Call contains one Connection which has this Address as its Address.

Call Listener Lifetime

For all call listeners which are present on Calls because of this method, the following behavior is exhibited with respect to the lifetime of the call.

1. The call listener receives events until the Call is no longer at this Address. In this case, the call listener will be re-applied to the Call if the Call returns to this Address at some point in the future.
2. The call listener is removed with Call.removeCallListener(). Note that this only affects the instance of the call listener for that particular call. If the Call subsequently leaves and returns to the Address, the listener will be re-applied.
3. The Call can no longer be monitored by the implementation.
4. The Call moves into the 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.

Call Listener on Multiple Addresses and Terminals

It is possible for an application to add CallListeners at more than one Address and Terminal (using Address.addCallListener() and Terminal.addCallListener(), respectively). The rules outlined above still apply, with the following additions:

1. A CallListener is not added to a Call more than once, even if it has been added to more than one Address/Terminal which are present on the Call.
2. The CallListener leaves the call only if all of the Addresses and Terminals on which the Call Listener was added leave the Call. If one of those Addresses/Terminals becomes part of the Call again, the call listener is re-applied to the Call.

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:

1. listener is an element of this.getCallListeners()
2. listener is an element of Call.getCallListeners() for each Call associated with the Connections from this.getConnections().
3. An array of snapshot events are reported to the listener for existing calls associated with this Address.

Parameters:

listener - The listener being added.

Throws:

MethodNotSupportedException - The listener cannot be added at this time.

ResourceUnavailableException - The resource limit for the numbers of listeners has been exceeded.

See Also:

Call

getCallListeners

public CallListener[] getCallListeners()

Returns a list of all CallListeners associated with this Address object. That is, it returns a list of CallListener object which have been added via the Address.addCallListener() method. If there are no CallListeners associated with this Address object, this method returns null.

Post-conditions:

1. Let CallListener[] obs = this.getCallListeners()
2. obs == null or obs.length >= 1

Returns:

An array of CallListener objects associated with this Address.

removeCallListener

public void removeCallListener(CallListener listener)

Removes the given CallListener from the Address. In other words, it removes a CallListener which was added via the Address.addCallListener() method. If successful, the listener will no longer be added to new Calls which are presented to this Address, however it does not affect CallListeners which have already been added at a Call.

Also, if the CallListener is not part of the Address, then this method fails silently, i.e. no listener is removed and no exception is thrown.

Post-conditions:

1. listener is not an element of this.getCallListeners()

Parameters:

listener - The CallListener which is being removed.