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
-
IN_SERVICE
- The Provider.IN_SERVICE state indicates that a Provider is currentl
available for use.
-
OUT_OF_SERVICE
-
The Provider.OUT_OF_SERVICE state indicates that a Provider is temporarily
not available for use.
-
SHUTDOWN
- The SHUTDOWN state indicates that a Provider is permanently no longer
available for use.
-
addObserver(ProviderObserver)
- Adds an observer to the Provider.
-
createCall()
- Creates and returns a new instance of the Call object.
-
getAddress(String)
- Returns an Address object which corresponds to the telephone number
string provided.
-
getAddressCapabilities(Terminal)
- Gets the AddressCapabilities object with respect to a Terminal.
-
getAddresses()
- Returns a list of Addresses associated with the Provider and within the
Provider's domain.
-
getCallCapabilities(Terminal, Address)
- Gets the CallCapabilities object with respect to a Terminal.
-
getCalls()
- Returns an array of Call objects currently associated with the Provider.
-
getConnectionCapabilities(Terminal, Address)
- Gets the ConnectionCapabilities object with respect to a Terminal.
-
getName()
- Returns the unique string name of the Provider.
-
getObservers()
- Returns a list of all ProviderObservers associated with this call object.
-
getProviderCapabilities(Terminal)
- Returns the ProviderCapabilities object with respect to a Terminal.
-
getState()
- Returns the current state of the Provider, either Provider.IN_SERVICE,
Provider.OUT_OF_SERVICE, or Provider.SHUTDOWN.
-
getTerminal(String)
- Returns an instance of the Terminal class which corresponds to the
given name.
-
getTerminalCapabilities(Terminal)
- Gets the TerminalCapabilities object with respect to a Terminal.
-
getTerminalConnectionCapabilities(Terminal)
- Gets the TerminalConnectionCapabilities of a Terminal.
-
getTerminals()
- Returns a list of Terminals associated with the Provider and within the
Provider's domain.
-
removeObserver(ProviderObserver)
- Removes the given observer from the Provider.
-
shutdown()
- Instructs the Provider to shut itself down and perform all neccessary
cleanup.
IN_SERVICE
public final static int IN_SERVICE
- The Provider.IN_SERVICE state indicates that a Provider is currentl
available for use.
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.
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.
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.
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
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:
- this.getState() == Provider.IN_SERVICE
The post-conditions for this method are:
- this.getState() == Provider.IN_SERVICE
- Let Calls calls[] = Provider.getCalls()
- calls == null or calls.length >= 1
- 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.
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:
- this.getState() == Provider.IN_SERVICE
- Let Address addr = this.getAddress(number);
- addr is an element of this.getAddresses();
The post-conditions for this method are:
- this.getState() == Provider.IN_SERVICE
- Let Address addr = this.getAddress(number);
- 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.
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:
- this.getState() == Provider.IN_SERVICE
The post-condition predicates for this method is:
- this.getState() == Provider.IN_SERVICE
- Let Address[] addr = this.getAddresses()
- addr == null or addr.length >= 1
- Returns:
- An array of Addresses known by this provider.
- Throws: PlatformException
- A platform-specific exception occurred.
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:
- this.getState() == Provider.IN_SERVICE
The post-condition predicate for this method is:
- this.getState() == Provider.IN_SERVICE
- Let Terminal[] term = this.getTerminals()
- term == null or term.length >= 1
- Returns:
- An array of Terminals known by this provider.
- Throws: PlatformException
- A platform-specific exception occurred.
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:
- this.getState() == Provider.IN_SERVICE
- this.getTerminal(name) is an element of this.getTerminals()
The post-condition predicates for this method are:
- this.getState() == Provider.IN_SERVICE
- 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.
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:
- this.getState() == Provider.IN_SERVICE
The post-conditions for this method are:
- this.getState() == Provider.SHUTDOWN
- Throws: InvalidStateException
- This Provider object is not in the
Provider.IN_SERVICE state.
- Throws: PlatformException
- A platform-specific exception occurred.
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:
- this.getState() == Provider.IN_SERVICE
The post-condition predicates for this method are:
- this.getState() == Provider.IN_SERVICE
- Let Call call = this.createCall();
- call.getState() == Call.IDLE.
- call.getConnections() == null
- 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.
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:
- 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 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:
- Let ProviderObserver[] obs = this.getObservers()
- obs == null or obs.length >= 1
- Returns:
- An array of ProviderObserver objects associated with this
Provider.
- Throws: PlatformException
- A platform-specific exception occurred.
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:
- observer is not an element of this.getObservers()
- Parameters:
- observer - The observer which is being removed.
- Throws: PlatformException
- A platform-specific exception occurred.
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.
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.
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.
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.
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.
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