|
JCC v0.9.2 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
A JcpProvider
represents the telephony software-entity that
interfaces with a
telephony subsystem.
IN_SERVICE
, OUT_OF_SERVICE
, or
SHUTDOWN
. The JcpProvider state represents whether any
action on that JcpProvider may be valid. The following tables describes each
state:
IN_SERVICE
|
This state indicates that the JcpProvider is currently alive and available for use. |
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. |
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 shutdown()
method on this interface to cause a JcpProvider to move into the
SHUTDOWN state.
|
The following diagram shows the allowable state transitions for the JcpProvider.
JcpPeer.getProvider(String)
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()
.
JcpProviderListener
interface. Applications instantiate objects
which implement this interface and use the
addProviderListener(JcpProviderListener)
method to begin the delivery of
events.
Applications may then query the event object
returned for the specific state change, via the JcpEvent.getID()
method.
When the JcpProvider changes state,
a JcpProviderEvent
is sent to the JcpProviderListener, having one of the following event ids:
JcpProviderEvent.PROVIDER_IN_SERVICE
, JcpProviderEvent.PROVIDER_OUT_OF_SERVICE
,
and JcpProviderEvent.PROVIDER_SHUTDOWN
.
A JcpProviderEvent
with event id
The JcpProviderEvent.PROVIDER_EVENT_TRANSMISSION_ENDED
is delivered to all
JcpProviderListeners
when the JcpProvider
becomes unobservable and is the final event delivered to the listener.
JcpCall
object representing new calls using the
createCall()
method. A new JcpCall is returned in the
JcpCall.IDLE
state. Applications may then use this idle JcpCall to
place new telephone calls.
JcpAddress
object represents what we
commonly think of as a "telephone number."
Unlike JcpCall objects, applications may not create JcpAddress
objects. An address is obtained through getAddress(String)
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 shutdown()
are specified to
affect only the invoking applications and have no affect on others.
JcpProviderListener
is added through addProviderListener(JcpProviderListener)
,
the first batch of events may be a "snapshot".
That is, if the listener was added after state changes in the Provider, the first batch of events will inform the
application of the current state of the Provider. Note that these snapshot events do NOT provide a history
of all events on the Provider, rather they provide the minimum necessary information to bring the application
up-to-date with the current state of the Provider.
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. |
Method Summary | |
void |
addProviderListener(JcpProviderListener providerlistener)
Adds a listener to this provider. |
JcpCall |
createCall()
Creates a new instance of the call with no connections. |
JcpAddress |
getAddress(java.lang.String address)
Returns an JcpAddress object which corresponds to the (telephone) number string
provided. |
java.lang.String |
getName()
Returns the unique string name of this JcpProvider instance. |
int |
getState()
Returns the state of the JcpProvider. |
void |
removeProviderListener(JcpProviderListener providerlistener)
Removes the given listener from the provider. |
void |
shutdown()
Instructs the JcpProvider to shut itself down and provide all necessary cleanup. |
Field Detail |
public static final int IN_SERVICE
public static final int OUT_OF_SERVICE
public static final int SHUTDOWN
Method Detail |
public int getState()
public JcpCall createCall() throws InvalidStateException, ResourceUnavailableException, PrivilegeViolationException, MethodNotSupportedException
JcpCall.IDLE
state. An exception is generated if a new call cannot be
created for various reasons. This JcpProvider must be in the IN_SERVICE
state, otherwise an InvalidStateException
is thrown.
Pre-conditions:
null
public void addProviderListener(JcpProviderListener providerlistener) throws ResourceUnavailableException, MethodNotSupportedException
removeProviderListener(JcpProviderListener)
method or until the
JcpProvider is no longer observable.
If the JcpProvider becomes unobservable, a JcpProviderEvent with id
JcpProviderEvent.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.
Post-Conditions:
providerlistener
- JcpProviderListener object that receives the specified events.JcpProviderListener
public void removeProviderListener(JcpProviderListener providerlistener)
JcpProviderEvent.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:
providerlistener
- JcpProviderListener object being removed.public java.lang.String getName()
JcpPeer.getProvider(String)
method to create this JcpProvider
instance.public JcpAddress getAddress(java.lang.String address) throws InvalidPartyException
JcpAddress
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:
address
- the address string which possibly represents a telephone number.InvalidPartyException.UNKNOWN_PARTY
,
is thrown if the given number does not correspond to a valid JcpAddress under this JcpProvider's domain.public void shutdown()
SHUTDOWN
state,
in which it will stay indefinitely.
If the JcpProvider is already in the 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:
|
JCC v0.9.2 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |