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.
 
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 Address object which corresponds to the (telephone) number string provided.
 java.lang.String getName()
          Returns the unique string name of this Provider.
 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

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.
Method Detail

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:

  1. 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:

  1. Let addres = this.getAddress(addr);
  2. 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:

  1. 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