Interface java.telephony.Provider
All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface java.telephony.Provider

public interface Provider
extends Object
A Provider represents the telephony-software-entity that interfaces with a telephony subsystem. The telephony subsystem could be a PBX connected to a server machine, or a telephony/fax card in a desktop machine or a networking technology such as IP.

A Provider instance is created and returned by the JtapiPeer method getProvider() which is given a string to describe the desired Provider. This method sets up any needed communcation paths between the application and the Provider object instance.

The Provider has methods for creating Call objects and obtaining Terminal and Address objects. Applications cannot create their own instances of Call, Terminal, Address, Connection, and TerminalConnection objects with the "new" operator.

The Provider maintains lists of Call, Terminal, and Address objects it knows about. Applications may create new Call objects using the Provider.createCall() method. The Provider maintains a reference to this new Call object until the Call object moves into the Provider.INVALID state. Applications may obtain a list of all Call objects known by the Provider (which are either in the Provider.IDLE or Provider.ACTIVE state) using the Provider.getCalls() method.

There may have been telephone calls present in the Provider's domain before the Provider software object has been created by the application. The Provider is still responsible, however, for reporting the existence of these Calls when the application invokes the getCalls() method. This principle applies to other objects as well. For example, the Address object must report all Connections which are part of telephone calls even if these Calls came into existence before the Provider.

Unlike Call objects, applications may not create Terminal or Address objects. The Provider begins with knowledge of certain Terminal and Address objects defined in the system. This list of Terminals and Addresses represents those Terminals and Addresses within the Provider's domain. This list is static once the Provider is created. The getTerminals() and getAddresses() method returns these lists, respectively. Other Addresses and Terminals may be created sometime during the operation of the Provider when the Provider learns of new instances of these objects. These new object, however, represent Addresses and Terminals outside the Provider's domain. For example, if the Provider's domain is a PBX, the Provider will know about all Addresses and Terminals in this PBX when the Provider first starts. Any Addresses and Terminals it subsequently learns about are outside this PBX. These Address and Terminal objects outside this PBX are not reported via the getTerminals() and getAddresses() methods.

The Provider may either be in the Provider.IN_SERVICE state, the Provider.OUT_OF_SERVICE state, or the Provider.SHUTDOWN state. The Provider state represents whether any action on that Provider or the objects associated with the Provider are valid. The pre-condition that the Provider state must be Provider.IN_SERVICE exists on most Java Telephony API object methods and is noted in all instances. The Provider.OUT_OF_SERVICE state indicates that the Provider is not available because of a temporary condition not controlled by the application. The Provider.SHUTDOWN state indicates that the Provider is permanently unavailable. The application may use the Provider.shutdown() method to move the Provider into the Provider.SHUTDOWN state itself or an external condition may cuase the Provider to move into this state as well.

Each time a state changes occurs on a Provider object, the application is notified via an event. This event is reported via the ProviderObserver interface. Applications instantiate objects which implement the ProviderObject interface and use the Provider.addObserver() method to begin the delivery of events. All Provider events reported via this interface extend the ProviderEvent interface. Applications may then query the event object returned for the specific state change. In the core Provider API, the following generates events to the ProviderObserver: when the Provider state changes to either Provider.IN_SERVICE, Provider.OUT_OF_SERVICE, or Provider.SHUTDOWN.

It is not guaranteed or expected that objects (Call, Terminal, etc.) instantiated through one Provider will be usable with another Provider. Thus an application that uses two providers must keep all the objects relating to these providers separate.

See Also:
JtapiPeer, ProviderObserver

Variable Index

 o IN_SERVICE
The Provider.IN_SERVICE state indicates that a Provider is currentl available for use.
 o OUT_OF_SERVICE
The Provider.OUT_OF_SERVICE state indicates that a Provider is temporarily not available for use.
 o SHUTDOWN
The SHUTDOWN state indicates that a Provider is permanently no longer available for use.

Method Index

 o addObserver(ProviderObserver)
Adds an observer to the Provider.
 o createCall()
Creates and returns a new instance of the Call object.
 o getAddress(String)
Returns an Address object which corresponds to the telephone number string provided.
 o getAddressCapabilities(Terminal)
Gets the AddressCapabilities object with respect to a Terminal.
 o getAddresses()
Returns a list of Addresses associated with the Provider and within the Provider's domain.
 o getCallCapabilities(Terminal, Address)
Gets the CallCapabilities object with respect to a Terminal.
 o getCalls()
Returns an array of Call objects currently associated with the Provider.
 o getConnectionCapabilities(Terminal, Address)
Gets the ConnectionCapabilities object with respect to a Terminal.
 o getName()
Returns the unique string name of the Provider.
 o getObservers()
Returns a list of all ProviderObservers associated with this call object.
 o getProviderCapabilities(Terminal)
Returns the ProviderCapabilities object with respect to a Terminal.
 o getState()
Returns the current state of the Provider, either Provider.IN_SERVICE, Provider.OUT_OF_SERVICE, or Provider.SHUTDOWN.
 o getTerminal(String)
Returns an instance of the Terminal class which corresponds to the given name.
 o getTerminalCapabilities(Terminal)
Gets the TerminalCapabilities object with respect to a Terminal.
 o getTerminalConnectionCapabilities(Terminal)
Gets the TerminalConnectionCapabilities of a Terminal.
 o getTerminals()
Returns a list of Terminals associated with the Provider and within the Provider's domain.
 o removeObserver(ProviderObserver)
Removes the given observer from the Provider.
 o shutdown()
Instructs the Provider to shut itself down and perform all neccessary cleanup.

Variables

 o IN_SERVICE
  public final static int IN_SERVICE
The Provider.IN_SERVICE state indicates that a Provider is currentl available for use.
 o OUT_OF_SERVICE
  public final static int OUT_OF_SERVICE
The Provider.OUT_OF_SERVICE state indicates that a Provider is temporarily not available for use. Most methods in the Java Telephony API are invalid when the Provider is in this state. Providers may come back IN_SERVICE at any time, however, the application can take no direct action to cause this change.
 o SHUTDOWN
  public final static int SHUTDOWN
The SHUTDOWN state indicates that a Provider is permanently no longer available for use. Most methods in the Java TelephonyAPI are invalid when the Provider is in this state.

Methods

 o getState
  public abstract int getState() throws PlatformException
Returns the current state of the Provider, either Provider.IN_SERVICE, Provider.OUT_OF_SERVICE, or Provider.SHUTDOWN.

Returns:
The current state of the provider.
Throws: PlatformException
A platform-specific exception occurred.
 o getName
  public abstract String getName() throws PlatformException
Returns the unique string name of the Provider. Each different Provider must have a unique string associated with it. This is the same string which the application passed to the JtapiPeer.getProvider() method to create this Provider instance.

Returns:
The URL-string name of the Provider.
Throws: PlatformException
A platform-specific exception occurred.
See Also:
JtapiPeer

 o getCalls
  public abstract Call[] getCalls() throws PlatformException
Returns an array of Call objects currently associated with the Provider. When a Call moves into the Call.INVALID state, the Provider loses its reference to this Call. Therefore, all Calls returned by this method must either be in the Call.IDLE or Call.ACTIVE state. This method returns null if the Provider has zero calls associated with it.

The pre-conditions for this method are:

  1. this.getState() == Provider.IN_SERVICE
The post-conditions for this method are:

  1. this.getState() == Provider.IN_SERVICE
  2. Let Calls calls[] = Provider.getCalls()
  3. calls == null or calls.length >= 1
  4. For all i, calls[i].getState() == Call.IDLE or Call.ACTIVE

Returns:
An array of Call objects currently known by this Provider.
Throws: PlatformException
A platform-specific exception occurred.
 o getAddress
  public abstract Address getAddress(String number) throws InvalidArgumentException, PlatformException
Returns an Address object which corresponds to the telephone number string provided. If the provided name does not correspond to an Address known by the Provider and within the Provider's domain, the InvalidArgumentException is thrown. In other words, the Address must appear in the list generated by Provider.getAddresses().

The pre-conditions for this method are:

  1. this.getState() == Provider.IN_SERVICE
  2. Let Address addr = this.getAddress(number);
  3. addr is an element of this.getAddresses();

The post-conditions for this method are:

  1. this.getState() == Provider.IN_SERVICE
  2. Let Address addr = this.getAddress(number);
  3. addr is an element of this.getAddresses();

Parameters:
number - The telephone address string.
Returns:
The Address object corresponding to the given telephone number.
Throws: InvalidArgumentException
The name of the Address does not correspond to the name of any Address object known to the Provider or within the Provider's domain.
Throws: PlatformException
A platform-specific exception occurred.
 o getAddresses
  public abstract Address[] getAddresses() throws PlatformException
Returns a list of Addresses associated with the Provider and within the Provider's domain. This list is static (i.e. is does not change) after the Provider is first created. The Provider must be Provider.IN_SERVICE. If no Address objects are associated with this Provider, then this method returns null.

The pre-condition predicates for this method is:

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

The post-condition predicates for this method is:

  1. this.getState() == Provider.IN_SERVICE
  2. Let Address[] addr = this.getAddresses()
  3. addr == null or addr.length >= 1

Returns:
An array of Addresses known by this provider.
Throws: PlatformException
A platform-specific exception occurred.
 o getTerminals
  public abstract Terminal[] getTerminals() throws PlatformException
Returns a list of Terminals associated with the Provider and within the Provider's domain. Each Terminal possesses a unique name, which is assigned to it by the JTAPI implementation. The Provider must be Provider.IN_SERVICE. If there are no Terminals associated with this Provider, then this method returns null.

The pre-condition predicate for this method is:

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

The post-condition predicate for this method is:

  1. this.getState() == Provider.IN_SERVICE
  2. Let Terminal[] term = this.getTerminals()
  3. term == null or term.length >= 1

Returns:
An array of Terminals known by this provider.
Throws: PlatformException
A platform-specific exception occurred.
 o getTerminal
  public abstract Terminal getTerminal(String name) throws InvalidArgumentException, PlatformException
Returns an instance of the Terminal class which corresponds to the given name. Each Terminal has a unique name associated with it, which is assigned to it by the JTAPI implementation. If no Terminal is available for the given name within the Provider's domain, this method throws the InvalidArgumentException. This Terminal must be in the array generated by Provider.getTerminals().

The pre-condition predicates for this method is:

  1. this.getState() == Provider.IN_SERVICE
  2. this.getTerminal(name) is an element of this.getTerminals()

The post-condition predicates for this method are:

  1. this.getState() == Provider.IN_SERVICE
  2. this.getTerminal(name) is an element of this.getTerminals()

Parameters:
name - The name of desired Terminal object.
Returns:
The Terminal object associated with the given name.
Throws: InvalidArgumentException
The name provided does not correspond to a name of any Terminal known to the Provider or within the Provider's domain.
Throws: PlatformException
A platform-specific exception occurred.
 o shutdown
  public abstract void shutdown() throws InvalidStateException, PlatformException
Instructs the Provider to shut itself down and perform all neccessary cleanup. Applications invoke this method when they no longer intend to use the Provider, most often right before they exit. This method is intended to allow the Provider to perform any neccessary cleanup which would not be taken care of when the Java objects are garbage collected. This method causes the Provider to move into the Provider.SHUTDOWN state, in which it will stay indefinitely.

The pre-conditions for this method are:

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

The post-conditions for this method are:

  1. this.getState() == Provider.SHUTDOWN

Throws: InvalidStateException
This Provider object is not in the Provider.IN_SERVICE state.
Throws: PlatformException
A platform-specific exception occurred.
 o createCall
  public abstract Call createCall() throws ResourceUnavailableException, InvalidStateException, PrivilegeViolationException, MethodNotSupportedException, PlatformException
Creates and returns a new instance of the Call object. This new call object is in the Call.IDLE state and has no connections. An exception is generated if a new call cannot be created.

The pre-condition predicates for this method are:

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

The post-condition predicates for this method are:

  1. this.getState() == Provider.IN_SERVICE
  2. Let Call call = this.createCall();
  3. call.getState() == Call.IDLE.
  4. call.getConnections() == null
  5. call is an element of this.getCalls()

Returns:
The new Call object.
Throws: ResourceUnavailableException
An internal resource neccessary to create a new Call object is unavailable.
Throws: InvalidStateException
The Provider is not in the Provider.IN_SERVICE state.
Throws: PrivilegeViolationException
The application does not have the proper authority to create a new telephone call object.
Throws: MethodNotSupportedException
The implementation does not support creating new Call objects.
Throws: PlatformException
A platform-specific exception occurred.
 o addObserver
  public abstract void addObserver(ProviderObserver observer) throws ResourceUnavailableException, PlatformException
Adds an observer to the Provider. The ProviderObserver reports all Provider-related state changes as events. The Provider bject will report events to this ProviderObserver object for the lifetime of the Provider object or until the observer is removed with the Provider.removeObserver() method.

This method is valid anytime and has no pre-conditions. Application must have the ability to add observers to Providers so they can monitor the changes in state in the Provider.

If an application attempts to add an instance of an observer already present on this Provider, 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.

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 ProviderObserver[] getObservers() throws PlatformException
Returns a list of all ProviderObservers associated with this call object. If no observers exist on this Provider, then this method returns null.

There are no preconditions for this method. The application must be able to get the list of observers even when the Provider is not in the IN_SERVICE state.

The post-conditions for this method are:

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

Returns:
An array of ProviderObserver objects associated with this Provider.
Throws: PlatformException
A platform-specific exception occurred.
 o removeObserver
  public abstract void removeObserver(ProviderObserver observer) throws InvalidArgumentException
Removes the given observer from the Provider. If successful, the observer will no longer receive events generated by this call object.

There are no pre-conditions for this method. Application should be able to remove observers even if the Provider is not in the IN_SERVICE state.

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

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 getProviderCapabilities
  public abstract ProviderCapabilities getProviderCapabilities(Terminal term) throws InvalidArgumentException, PlatformException
Returns the ProviderCapabilities object with respect to a Terminal. If null is passed as a Terminal parameter, the general/provider-wide Provider capabilities are returned.

Throws: InvalidArgumentException
invalid argument exception occurred
Throws: PlatformException
A platform-specific exception occurred.
 o getCallCapabilities
  public abstract CallCapabilities getCallCapabilities(Terminal terminal,
                                                       Address address) throws InvalidArgumentException, PlatformException
Gets the CallCapabilities object with respect to a Terminal. If null is passed as a Terminal parameter, the general/provider-wide Call capabilities are returned.

Parameters:
terminal - the terminal whose call capabilities are being queried
Throws: InvalidArgumentException
invalid argument exception occurred
Throws: PlatformException
A platform-specific exception occurred.
 o getConnectionCapabilities
  public abstract ConnectionCapabilities getConnectionCapabilities(Terminal terminal,
                                                                   Address address) throws InvalidArgumentException, PlatformException
Gets the ConnectionCapabilities object with respect to a Terminal. If null is passed as a Terminal parameter, the general/provider-wide Connection capabilities are returned.

Parameters:
terminal - the terminal whose connection capabilities are being queried
Throws: InvalidArgumentException
invalid argument exception occurred
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.

Parameters:
terminal - the terminal whose address capabilities are being queried
Throws: InvalidArgumentException
invalid argument exception occurred
Throws: PlatformException
A platform-specific exception occurred.
 o getTerminalConnectionCapabilities
  public abstract TerminalConnectionCapabilities getTerminalConnectionCapabilities(Terminal terminal) throws InvalidArgumentException, PlatformException
Gets the TerminalConnectionCapabilities of a Terminal. If null is passed as a Terminal parameter, the general/provider-wide TerminalConnection capabilities are returned.

Parameters:
terminal - the terminal whose terminal connection capabilities are being queried
Throws: InvalidArgumentException
invalid argument exception occurred
Throws: PlatformException
A platform-specific exception occurred.
 o getTerminalCapabilities
  public abstract TerminalCapabilities getTerminalCapabilities(Terminal terminal) throws InvalidArgumentException, PlatformException
Gets the TerminalCapabilities object with respect to a Terminal. If null is passed as a Terminal parameter, the general/provider-wide Terminal capabilities are returned.

Parameters:
terminal - the terminal whose capabilities are being queried
Throws: InvalidArgumentException
invalid argument exception occurred
Throws: PlatformException
A platform-specific exception occurred.

All Packages  Class Hierarchy  This Package  Previous  Next  Index