javax.telephony
Interface Provider

All Known Subinterfaces:

CallCenterProvider, MobileProvider, NetworkSelection

public interface Provider

A Provider represents the telephony software-entity that interfaces with a telephony subsystem.

Introduction

The telephony subsystem could be a PBX connected to a server machine, a telephony/fax card in a desktop machine or a networking technology such as IP or ATM.

Provider States

The Provider may either be in one of the following states: Provider.IN_SERVICE, Provider.OUT_OF_SERVICE, or Provider.SHUTDOWN. The Provider state represents whether any action on that Provider may be valid. The following tables describes each state:

Provider.IN_SERVICE	This state indicates that the Provider is currently alive and available for use.
Provider.OUT_OF_SERVICE	This state indicates that a Provider is temporarily not available for use. Many 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.
Provider.SHUTDOWN:	This state indicates that a Provider is permanently no longer available for use. Most methods in the Java Telephony API are invalid when the Provider is in this state. Applications may use the Provider.shutdown() method on this interface to cause a Provider to move into the Provider.SHUTDOWN state.

The following diagram shows the allowable state transitions for the Provider as defined by the core package.

Obtaining a Provider

A Provider is created and returned by the JtapiPeer.getProvider() method which is given a string to describe the desired Provider. This method sets up any needed communication paths between the application and the Provider. The string given is one of the services listed in the JtapiPeer.getServices(). JtapiPeers particular implementation on a system and may be obtained via the JtapiPeerFactory class.

Listeners and Events

Each time a state changes occurs on a Provider, the application is notified via an event. This event is reported via the ProviderListener interface. Applications instantiate objects which implement this interface and use the Provider.addProviderListener() method to begin the delivery of events. All Provider events reported via this interface extend the ProviderEvent interface. Therefore, applications may then query the event object returned for the specific state change, via the Event.getID() method. In the core package API, when the Provider changes state, a ProviderEvent is sent to the ProviderListener, having one of the following event ids: PROVIDER_IN_SERVICE, PROVIDER_OUT_OF_SERVICE, and PROVIDER_SHUTDOWN. A ProviderEvent with event id The PROVIDER_EVENT_TRANSMISSION_ENDED is delivered to all ProviderListeners when the Provider becomes unobservable and is the final event delivered to the listener.

Call Objects and Providers

The Provider maintains knowledge of the calls currently associated with it. Applications may obtain an array of these Calls via the Provider.getCalls() method. A Provider may have Calls associated with it which were created before it came into existence. It is the responsibility of the implementation of the Provider to model and report all existing telephone calls which were created prior to the Provider's lifetime. The Provider maintains references to all calls until they move into the Call.INVALID state.

Applications may create new Calls using the Provider.createCall() method. A new Call is returned in the Call.IDLE state. Applications may then use this idle Call to place new telephone calls. Once created, this new Call object is returned via the Provider.getCalls() method.

The Provider's domain

The term Provider's domain refers to the collection of Address and Terminal objects which are local to the Provider, and typically, can be controlled by the Provider. For example, the domain of a Provider of a desktop system with an ISDN card are the Address(es) and Terminal(s) which represent that ISDN endpoint. The domain of a Provider for a PBX may be the Addresses and Terminals in that PBX. The Provider implementation controls access to Addresses and Terminals by limiting the domain it presents to the application.

Address and Terminal Objects

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, such as an IP address. Regardless, it represents a logical endpoint of a telephone call. A Terminal represents a physical hardware endpoint connected to the telephone network. An example of a Terminal is a telephone set, but a Terminal does not have to take the form of this limited and traditional example. Addresses and Terminals are in a many-to-many relationship. An Address may contain multiple Terminals, and Terminals may contain multiple Addresses. See the specifications for the Address and Terminal objects for more information.

Unlike Call objects, applications may not create Terminal or Address objects. The Provider begins with knowledge of certain Terminal and Address objects defined as its local domain. This list is static once the Provider is created. The Addresses and Terminals in the Provider's domain are reported via the Provider.getAddresses() and Provider.getTerminals() methods, 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 objects, 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 Provider.getTerminals() and Provider.getAddresses() methods. Address and Terminal objects outside of the Provider's domain are referred to as remote.

Capabilities: Static and Dynamic

The Provider interface supports methods to return static capabilities for each of the Java Telephony call model objects. Static capabilities provide applications with information concerning the ability of the implementation to perform certain methods. These static capabilities indicate whether a method is implemented for a particular type of object and does not depend upon the particular instance of the object nor the current state of the call model. Those methods for which the static capability returns false will throw a MethodNotSupportedException when invoked. The static capability methods supported on this interface are: Provider.getProviderCapabilities(), Provider.getCallCapabilities(), Provider.getAddressCapabilities(), Provider.getTerminalCapabilities(), Provider.getConnectionCapabilities(), and Provider.getTerminalConnectionCapabilities().

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 arguments 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 can be successfully invoked, however. This interface returns the dynamic capabilities for a Provider object via the Provider.getCapabilities() method. Note that this method is distinct from the static capability method Provider.getProviderCapabilities().

Multiple Providers and Multiple Applications

It is not guaranteed or expected that objects (Call, Terminal, etc.) instantiated through one Provider will be usable with another Provider. Therefore, an application that uses two providers must keep all the objects relating to these providers separate. In the future, there may be a mechanism whereby a Provider may share objects with another Provider if they are speaking to the same telephony hardware, however, such capabilities are not available in this release.

Also, multiple applications may request and communicate with the same Provider implementation. Typically, since each application executes in its own object space, each will have its own instance of the Provider object. These two different Provider objects may, in fact, be proxies for a centralized Provider instance. Certain methods in JTAPI are specified to affect only the invoking applications and have no affect on others. The only example in the core package is the Provider.shutdown() method.

See Also:

JtapiPeer, JtapiPeerFactory, ProviderListener

Field Summary

static int	IN_SERVICE This state indicates that a Provider is currently available for use.
static int	OUT_OF_SERVICE This state indicates that a Provider is currently not available for use.
static int	SHUTDOWN This state indicates that a Provider is permanently no longer available for use.

Method Summary

void	addObserver(ProviderObserver observer) Adds an observer to the Provider.
void	addProviderListener(ProviderListener listener) Adds an listener to the Provider.
Call	createCall() Creates and returns a new instance of the Call object.
Address	getAddress(java.lang.String number) Returns an Address object which corresponds to the telephone number string provided.
AddressCapabilities	getAddressCapabilities() Returns the static capabilities of the Address object.
AddressCapabilities	getAddressCapabilities(Terminal terminal) Deprecated. Since JTAPI v1.2. This method has been replaced by the Provider.getAddressCapabilities() method.
Address[]	getAddresses() Returns an array of Addresses associated with the Provider and within the Provider's domain.
CallCapabilities	getCallCapabilities() Returns the static capabilities of the Call object.
CallCapabilities	getCallCapabilities(Terminal terminal, Address address) Deprecated. Since JTAPI v1.2. This method has been replaced by the Provider.getCallCapabilities() method.
Call[]	getCalls() Returns an array of Call objects currently associated with the Provider.
ProviderCapabilities	getCapabilities() Returns the dynamic capabilities for the instance of the Provider object.
ConnectionCapabilities	getConnectionCapabilities() Returns the static capabilities of the Connection object.
ConnectionCapabilities	getConnectionCapabilities(Terminal terminal, Address address) Deprecated. Since JTAPI v1.2. This method has been replaced by the Provider.getConnectionCapabilities() method.
java.lang.String	getName() Returns the unique string name of this Provider.
ProviderObserver[]	getObservers() Returns a list of all ProviderObservers associated with this Provider object.
ProviderCapabilities	getProviderCapabilities() Returns the static capabilities of the Provider object.
ProviderCapabilities	getProviderCapabilities(Terminal terminal) Deprecated. Since JTAPI v1.2. This method has been replaced by the Provider.getProviderCapabilities() method.
ProviderListener[]	getProviderListeners() Returns a list of all ProviderListeners associated with this Provider object.
int	getState() Returns the current state of this Provider.
Terminal	getTerminal(java.lang.String name) Returns an instance of the Terminal class which corresponds to the given name.
TerminalCapabilities	getTerminalCapabilities() Returns the static capabilities of the Terminal object.
TerminalCapabilities	getTerminalCapabilities(Terminal terminal) Deprecated. Since JTAPI v1.2. This method has been replaced by the Provider.getTerminalCapabilities() method.
TerminalConnectionCapabilities	getTerminalConnectionCapabilities() Returns the static capabilities of the TerminalConnection object.
TerminalConnectionCapabilities	getTerminalConnectionCapabilities(Terminal terminal) Deprecated. Since JTAPI v1.2. This method has been replaced by the Provider.getTerminalConnectionCapabilities() method.
Terminal[]	getTerminals() Returns an array of Terminals associated with the Provider and within the Provider's domain.
void	removeObserver(ProviderObserver observer) Removes the given observer from the Provider.
void	removeProviderListener(ProviderListener listener) Removes the given listener from the Provider.
void	shutdown() Instructs the Provider to shut itself down and perform all necessary cleanup.

Field Detail

IN_SERVICE

public static final int IN_SERVICE

This state indicates that a Provider is currently available for use.

OUT_OF_SERVICE

public static final int OUT_OF_SERVICE

This state indicates that a Provider is currently not available for use. Many 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 static final int SHUTDOWN

This state indicates that a Provider is permanently no longer available for use. Most methods in the Java Telephony API are invalid when the Provider is in this state.

Method Detail

getState

public int getState()

Returns the current state of this Provider. The value is one of Provider.IN_SERVICE, Provider.OUT_OF_SERVICE, or Provider.SHUTDOWN.

Returns:

The current state of this Provider.

getName

public java.lang.String getName()

Returns the unique string name of this 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 unique String name of this Provider.

See Also:

JtapiPeer

getCalls

public Call[] getCalls()
                throws ResourceUnavailableException

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.

Post-conditions:

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

Returns:

An array of Call objects currently associated with this Provider.

Throws:

ResourceUnavailableException - Indicates the number of calls present in the Provider is too great to return as a static array.

getAddress

public Address getAddress(java.lang.String number)
                   throws InvalidArgumentException

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, InvalidArgumentException is thrown. In other words, the Address must appear in the list generated by Provider.getAddresses().

Pre-conditions:

1. Let Address address = this.getAddress(number);
2. address is an element of this.getAddresses();

Post-conditions:

1. Let Address address = this.getAddress(number);
2. address 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, e.g. telephone number of the Address does not correspond to the name of any Address object known to the Provider or within the Provider's domain.

getAddresses

public Address[] getAddresses()
                       throws ResourceUnavailableException

Returns an array 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. If no Address objects are associated with this Provider, then this method returns null.

Post-conditions:

1. Let Address[] addresses = this.getAddresses()
2. addresses == null or addresses.length >= 1

Returns:

An array of Addresses known by this provider.

Throws:

ResourceUnavailableException - Indicates the number of addresses present in the Provider is too great to return as a static array.

getTerminals

public Terminal[] getTerminals()
                        throws ResourceUnavailableException

Returns an array 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. If there are no Terminals associated with this Provider, then this method returns null.

Post-conditions:

1. Let Terminal[] terminals = this.getTerminals()
2. terminals == null or terminals.length >= 1

Returns:

An array of Terminals in the Provider's local domain.

Throws:

ResourceUnavailableException - Indicates the number of terminals present in the Provider is too great to return as a static array.

getTerminal

public Terminal getTerminal(java.lang.String name)
                     throws InvalidArgumentException

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

Pre-conditions:

1. Let Terminal terminal = this.getTerminal(name);
2. terminals is an element of this.getTerminals();

Post-conditions:

1. Let Terminal terminal = this.getTerminal(name);
2. terminal 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.

shutdown

public void shutdown()

Instructs the Provider to shut itself down and perform all necessary 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 necessary 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.

If the Provider is already in the Provider.SHUTDOWN state, this method does nothing. The invocation of this method should not affect other applications which are using the same implementation of the Provider object.

Post-conditions:

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

createCall

public Call createCall()
                throws ResourceUnavailableException,
                       InvalidStateException,
                       PrivilegeViolationException,
                       MethodNotSupportedException

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 for various reasons. This Provider must be in the Provider.IN_SERVICE state, otherwise an InvalidStateException is thrown.

Pre-conditions:

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

Post-conditions:

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 necessary to create a new Call object is unavailable.

InvalidStateException - The Provider is not in the Provider.IN_SERVICE state.

PrivilegeViolationException - The application does not have the proper authority to create a new telephone call object.

MethodNotSupportedException - The implementation does not support creating new Call objects.

addObserver

public void addObserver(ProviderObserver observer)
                 throws ResourceUnavailableException,
                        MethodNotSupportedException

Adds an observer to the Provider. Provider-related events are reported via the ProviderObserver interface. The Provider object will report events to this interface for the lifetime of the Provider object or until the observer is removed with the Provider.removeObserver() method or until the Provider is no longer observable.

If the Provider becomes unobservable, a ProvObservationEndedEv is delivered to the application as is final event. No further events are delivered to the observer unless it is explicitly re-added by the application. When an observer receives a ProvObservationEndedEv it is no longer reported via the Provider.getObservers() 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.

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 numbers of observers has been exceeded.

getObservers

public ProviderObserver[] getObservers()

Returns a list of all ProviderObservers associated with this Provider object. If no observers exist on this Provider, then this method returns null.

Post-conditions:

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

Returns:

An array of ProviderObserver objects associated with this Provider.

removeObserver

public void removeObserver(ProviderObserver observer)

Removes the given observer from the Provider. The given observer will no longer receive events generated by this Provider object. The final event will be the ProvObservationEndedEv event and will no longer be listed by the Provider.getObservers() method.

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.

Post-conditions:

1. observer is not an element of this.getObservers()
2. ProvObservationEndedEv is delivered to observer

Parameters:

observer - The observer which is being removed.

getProviderCapabilities

public ProviderCapabilities getProviderCapabilities()

Returns the static capabilities of the Provider object. The value of these capabilities will not change over the lifetime of the Provider. They represent the static abilities of the implementation to perform certain methods on the Provider object. For all capability methods which return false, the invocation of that method will always throw MethodNotSupportedException.

NOTE: This method is different from the Provider.getCapabilities(), method which returns the dynamic capabilities of a Provider object instance.

Returns:

The static capabilities of the Provider object.

getCallCapabilities

public CallCapabilities getCallCapabilities()

Returns the static capabilities of the Call object. The value of these capabilities will not change over the lifetime of the Provider. They represent the static abilities of the implementation to perform certain methods on the Call object. For all capability methods which return false, the invocation of that method will always throw MethodNotSupportedException.

Returns:

The static capabilities of the Call object.

getAddressCapabilities

public AddressCapabilities getAddressCapabilities()

Returns the static capabilities of the Address object. The value of these capabilities will not change over the lifetime of the Provider. They represent the static abilities of the implementation to perform certain methods on the Address object. For all capability methods which return false, the invocation of that method will always throw MethodNotSupportedException.

Returns:

The static capabilities of the Address object.

getTerminalCapabilities

public TerminalCapabilities getTerminalCapabilities()

Returns the static capabilities of the Terminal object. The value of these capabilities will not change over the lifetime of the Provider. They represent the static abilities of the implementation to perform certain methods on the Terminal object. For all capability methods which return false, the invocation of that method will always throw MethodNotSupportedException.

Returns:

The static capabilities of the Address object.

getConnectionCapabilities

public ConnectionCapabilities getConnectionCapabilities()

Returns the static capabilities of the Connection object. The value of these capabilities will not change over the lifetime of the Provider. They represent the static abilities of the implementation to perform certain methods on the Connection object. For all capability methods which return false, the invocation of that method will always throw MethodNotSupportedException.

Returns:

The static capabilities of the Connection object.

getTerminalConnectionCapabilities

public TerminalConnectionCapabilities getTerminalConnectionCapabilities()

Returns the static capabilities of the TerminalConnection object. The value of these capabilities will not change over the lifetime of the Provider. They represent the static abilities of the implementation to perform certain methods on the TerminalConnection object. For all capability methods which return false, the invocation of that method will always throw MethodNotSupportedException.

Returns:

The static capabilities of the TerminalConnection object.

getCapabilities

public ProviderCapabilities getCapabilities()

Returns the dynamic capabilities for the instance of the Provider 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 can be successfully invoked, however.

There are no arguments passed into this method for dynamic Provider capabilities

NOTE: This method is different from the Provider.getProviderCapabilities() method which returns the static capabilities for the Provider object.

Returns:

The dynamic Provider capabilities.

getProviderCapabilities

public ProviderCapabilities getProviderCapabilities(Terminal terminal)
                                             throws InvalidArgumentException,
                                                    PlatformException

Deprecated. Since JTAPI v1.2. This method has been replaced by the Provider.getProviderCapabilities() method.

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.

Note: This method has been replaced in JTAPI v1.2. The Provider.getProviderCapabilities() method returns the static Provider capabilities. This method now should simply invoke the Provider.getProviderCapabilities(void) method.

Parameters:

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

Returns:

The dynamic ProviderCapabilities capabilities.

Throws:

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

PlatformException - A platform-specific exception occurred.

getCallCapabilities

public CallCapabilities getCallCapabilities(Terminal terminal,
                                            Address address)
                                     throws InvalidArgumentException,
                                            PlatformException

Deprecated. Since JTAPI v1.2. This method has been replaced by the Provider.getCallCapabilities() method.

Gets the CallCapabilities object with respect to a Terminal and an Address. If null is passed as a Terminal/Address parameter, the general/provider-wide Call capabilities are returned.

Note: This method has been replaced in JTAPI v1.2. The Provider.getCallCapabilities() method returns the static Call capabilities. This method now should simply invoke the Provider.getCallCapabilities(void) method.

Parameters:

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

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

Returns:

The static CallCapabilities cpabilities.

Throws:

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

PlatformException - A platform-specific exception occurred.

getConnectionCapabilities

public ConnectionCapabilities getConnectionCapabilities(Terminal terminal,
                                                        Address address)
                                                 throws InvalidArgumentException,
                                                        PlatformException

Deprecated. Since JTAPI v1.2. This method has been replaced by the Provider.getConnectionCapabilities() method.

Gets the ConnectionCapabilities object with respect to a Terminal and an Address. If null is passed as a Terminal/Address parameter, the general/ provider-wide Connection capabilities are returned.

Note: This method has been replaced in JTAPI v1.2. The Provider.getConnectionCapabilities() method returns the static Connection capabilities. This method now should simply invoke the Provider.getConnectionCapabilities(void) method.

Parameters:

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

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

Returns:

The static ConnectionCapabilities capabilities

Throws:

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

PlatformException - A platform-specific exception occurred.

getAddressCapabilities

public AddressCapabilities getAddressCapabilities(Terminal terminal)
                                           throws InvalidArgumentException,
                                                  PlatformException

Deprecated. Since JTAPI v1.2. This method has been replaced by the Provider.getAddressCapabilities() 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 Provider.getAddressCapabilities() method returns the static Address capabilities. This method now should simply invoke the Provider.getAddressCapabilities(void) 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.

getTerminalConnectionCapabilities

public TerminalConnectionCapabilities getTerminalConnectionCapabilities(Terminal terminal)
                                                                 throws InvalidArgumentException,
                                                                        PlatformException

Deprecated. Since JTAPI v1.2. This method has been replaced by the Provider.getTerminalConnectionCapabilities() method.

Gets the TerminalConnectionCapabilities of a Terminal. If null is passed as a Terminal parameter, the general/provider-wide TerminalConnection capabilities are returned.

Note: This method has been replaced in JTAPI v1.2. The Provider.getTerminalConnectionCapabilities() method returns the static TerminalConnection capabilities. This method now should simply invoke the Provider.getTerminalConnectionCapabilities(void) method.

Parameters:

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

Throws:

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

PlatformException - A platform-specific exception occurred.

getTerminalCapabilities

public TerminalCapabilities getTerminalCapabilities(Terminal terminal)
                                             throws InvalidArgumentException,
                                                    PlatformException

Deprecated. Since JTAPI v1.2. This method has been replaced by the Provider.getTerminalCapabilities() method.

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.

Note: This method has been replaced in JTAPI v1.2. The Provider.getTerminalCapabilities() method returns the static Terminal capabilities. This method now should simply invoke the Provider.getTerminalCapabilities(void) 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.

addProviderListener

public void addProviderListener(ProviderListener listener)
                         throws ResourceUnavailableException,
                                MethodNotSupportedException

Adds an listener to the Provider. Provider-related events are reported via the ProviderListener interface. The Provider object will report events to this interface for the lifetime of the Provider object or until the listener is removed with the Provider.removeProviderListener() method or until the Provider is no longer observable.

If the Provider becomes unobservable, a ProviderEvent with id PROVIDER_EVENT_TRANSMISSION_ENDED is delivered to the application as is final event. No further events are delivered to the listener unless it is explicitly re-added by the application. When an listener receives PROVIDER_EVENT_TRANSMISSION_ENDED it is no longer reported via the Provider.getProviderListeners() method.

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

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

Post-conditions:

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

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.

getProviderListeners

public ProviderListener[] getProviderListeners()

Returns a list of all ProviderListeners associated with this Provider object. If no listeners exist on this Provider, then this method returns null.

Post-conditions:

1. Let ProviderListener[] listeners = this.getProviderListeners()
2. listeners == null or listeners.length >= 1

Returns:

An array of ProviderListener objects associated with this Provider.

removeProviderListener

public void removeProviderListener(ProviderListener listener)

Removes the given listener from the Provider. The given listener will no longer receive events generated by this Provider object. The final event will have id PROVIDER_EVENT_TRANSMISSION_ENDED; subsequently, the listener will no longer be listed by the Provider.getProviderListeners() method.

Also, if the listener is not currently registered with the Provider, then this method fails silently, i.e. no listener is removed an no exception is thrown.

Post-conditions:

1. listener is not an element of this.getProviderListeners()
2. ProviderEvent with id PROVIDER_EVENT_TRANSMISSION_ENDED is delivered to listener

Parameters:

listener - The listener which is being removed.