jain.jcp
Interface JcpProvider
- All Known Subinterfaces:
- JccProvider
- public interface JcpProvider
A JcpProvider
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.
JcpProvider States
The JcpProvider may either be in one of the following states:
JcpProvider.IN_SERVICE
, JcpProvider.OUT_OF_SERVICE
, or
JcpProvider.SHUTDOWN
. The JcpProvider state represents whether any
action on that JcpProvider may be valid. The following tables describes each
state:
JcpProvider.IN_SERVICE
|
This state indicates that the JcpProvider is currently alive and available for
use.
|
JcpProvider.OUT_OF_SERVICE
|
This state indicates that a JcpProvider is temporarily not available for use.
Many methods in this API are invalid when the JcpProvider is in
this state. JcpProviders may come back in service at any time, however, the
application can take no direct action to cause this change.
|
JcpProvider.SHUTDOWN :
|
This state indicates that a JcpProvider is permanently no longer available for
use. Most methods in the API are invalid when the JcpProvider
is in this state. Applications may use the JcpProvider.shutdown()
method on this interface to cause a JcpProvider to move into the
JcpProvider.SHUTDOWN state.
|
The following diagram shows the allowable state transitions for the
JcpProvider.
Obtaining a JcpProvider
A JcpProvider is created and returned by the
JcpPeer.getProvider()
method which is given a string to
describe the desired JcpProvider. This method sets up any needed communication
paths between the application and the JcpProvider. The string given is one of
the services listed in the JcpPeer.getServices()
.
Listeners and Events
Each time a state changes occurs on a JcpProvider, the application is notified
via an event. This event is reported via the
JcpProviderListener
interface. Applications instantiate objects
which implement this interface and use the
JcpProvider.addProviderListener()
method to begin the delivery of
events.
Applications may then query the event object
returned for the specific state change, via the Event.getID()
method.
When the JcpProvider changes state,
a JcpProviderEvent
is sent to the JcpProviderListener, having one of the following event ids:
PROVIDER_IN_SERVICE
, PROVIDER_OUT_OF_SERVICE
,
and PROVIDER_SHUTDOWN
.
A JcpProviderEvent
with event id
The PROVIDER_EVENT_TRANSMISSION_ENDED
is delivered to all
JcpProviderListeners
when the JcpProvider
becomes unobservable and is the final event delivered to the listener.
Call Objects and Providers
Applications may create a JcpCall object representing new calls using the
Provider.createCall()
method. A new JcpCall is returned in the
JcpCall.IDLE
state. Applications may then use this idle JcpCall to
place new telephone calls.
Address Objects
A JcpAddress object represents what we
commonly think of as a "telephone number."
Unlike JcpCall objects, applications may not create JcpAddress
objects.
Multiple Providers and Multiple Applications
It is not guaranteed or expected that objects
instantiated through one JcpProvider will be usable with another JcpProvider.
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 JcpProvider may share objects with another JcpProvider 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
JcpProvider implementation. Typically, since each application executes in its
own object space, each will have its own instance of the JcpProvider object.
These two different JcpProvider objects may, in fact, be proxies for a
centralized JcpProvider instance. Methods in JCP like Provider.shutdown()
are specified to
affect only the invoking applications and have no affect on others. The
only example in the core package is the
method.
Event Snapshots
By default, when an listener is added
to a telephone call, the first batch of events may be a "snapshot".
That is, if the listener was added after state changes in the Call,
the first batch of events will inform the application of the
current state of the Call. Note that these snapshot events do NOT
provide a history of all events on the Call, rather they provide
the minimum necessary information to bring the application
up-to-date with the current state of the Call.
- See Also:
JcpPeer
,
JcpPeerFactory
,
JcpProviderListener
Field Summary |
static int |
IN_SERVICE
This state indicates that the JcpProvider is currently available for use. |
static int |
OUT_OF_SERVICE
This state indicates that the JcpProvider is currently not available for use. |
static int |
SHUTDOWN
This state indicates that the JcpProvider is permanently no longer available for use. |
IN_SERVICE
public static final int IN_SERVICE
- This state indicates that the JcpProvider is currently available for use.
OUT_OF_SERVICE
public static final int OUT_OF_SERVICE
- This state indicates that the JcpProvider is currently not available for use. 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 the JcpProvider is permanently no longer available for use.
getState
public int getState()
- Returns the state of the Jcpprovider.
- Returns:
- Integer representing the state of the provider. See static int's defined in this object.
createCall
public JcpCall createCall()
throws InvalidStateException,
ResourceUnavailableException,
PrivilegeViolationException,
MethodNotSupportedException
- Creates a new instance of the call with no connections. The new call object is
in the JcpCall.IDLE state. An exception is generated if a new call cannot be
created for various reasons. This JcpProvider must be in the JcpProvider.IN_SERVICE
state, otherwise an InvalidStateException is thrown.
Pre-condition:
1.this.getState() == JcpProvider.IN_SERVICE
Post-conditions:
1.this.getState() == JcpProvider.IN_SERVICE
2.Assume JcpCall call == createCall();
3.call.getState () == JcpCall.IDLE
4.call.getConnections() == null
- Returns:
- JcpCall object representing the new call.
- Throws:
- InvalidStateException - If the JcpProvider is not in the JcpProvider.IN_SERVICE state.
- ResourceUnavailableException - An internal resource necessary to create a new Call
object is unavailable.
- PrivilegeViolationException - If the application does not have the proper
authority to create a new telephone call object.
- MethodNotSupportedException - The implementation does not support creating
new JcpCall objects.
addProviderListener
public void addProviderListener(JcpProviderListener providerlistener)
throws ResourceUnavailableException,
MethodNotSupportedException
- Adds a listener to this provider. JcpProvider related events are reported via the
JcpProviderListener interface. The JcpProvider object will report events to this
interface for the lifetime of the JcpProvider object or until the listener is
removed with the JcpProvider.removeProviderListener() method or until the
JcpProvider is no longer observable.
If the JcpProvider becomes unobservable, a JcpProviderEvent with id
PROVIDER_EVENT_TRANSMISSION_ENDED is delivered to the application as a final
event. No further events are delivered to the listener unless it is explicitly
re-added by the application.
This method is valid anytime and has no pre-conditions. Application must have
the ability to add listeners to JcpProviders so they can monitor the changes in
state in the JcpProvider.
If an application attempts to add an instance of an listener already
present on this JcpProvider, 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.
- Parameters:
providerlistener
- JcpProviderListener object that receives the specified events.- Throws:
- MethodNotSupportedException - The listener cannot be added at this time.
- ResourceUnavailableException - The resource limit for the number of
listeners has been exceeded.
- See Also:
JcpProviderListener
removeProviderListener
public void removeProviderListener(JcpProviderListener providerlistener)
- Removes the given listener from the provider. The given listener will no longer
receive events generated by this JcpProvider object. The final event will have
id PROVIDER_EVENT_TRANSMISSION_ENDED.
Also, if the listener is not currently registered with the JcpProvider, then this
method fails silently, i.e. no listener is removed and no exception is thrown.
Post-Conditions:
- JcpProviderEvent with id PROVIDER_EVENT_TRANSMISSION_ENDED is delivered to listener.
- Parameters:
providerlistener
- JcpProviderListener object being removed.
getName
public java.lang.String getName()
- Returns the unique string name of this Provider. Each different JcpProvider must
have a unique string associated with it. This is the same string which the
application passed to the JcpPeer.getProvider() method to create this Provider
instance.
- Returns:
- The unique String name of this Provider.
getAddress
public JcpAddress getAddress(java.lang.String address)
throws InvalidArgumentException
- Returns an Address object which corresponds to the (telephone) number string
provided. If the provided name does not correspond to a JcpAddress known by the
JcpProvider and within the JcpProvider's domain, InvalidArgumentException is thrown.
Post-Conditions:
- Let addres = this.getAddress(addr);
- Then. (addres.getName()).equals(addr) returns true;
- Parameters:
address
- the address string which possibly represents a telephone number.- Returns:
- The JcpAddress object which corresponds to the given number.
- Throws:
- InvalidArgumentException - If the given number does not correspond to
a valid Address under this JcpProvider's domain.
shutdown
public void shutdown()
- Instructs the JcpProvider to shut itself down and provide all necessary cleanup.
Applications invoke this method when they no
longer intend to use the JcpProvider, most often right before they exit.
This method is intended to allow the JcpProvider to
perform any necessary cleanup which would not be taken care of when the
Java objects are garbage collected. This
method causes the JcpProvider to move into the JcpProvider.SHUTDOWN state,
in which it will stay indefinitely.
If the JcpProvider is already in the JcpProvider.SHUTDOWN state, this method does
nothing. The invocation of this method
should not affect other applications which are using the same
implementation of the JcpProvider object.
Post-Conditions:
- this.getState ==JcpProvider.SHUTDOWN
3 Oct 2000 If you have any comments or queries, please mail them to jcc@research.telcordia.com
Copyright-2000 Sun Microsystems