jain.jcc
Interface JccProvider


public interface JccProvider
extends JcpProvider

Provider of JAIN Call Control services. Note also that the JccProvider acts as a Factory to create standard EventFilter objects. These standard EventFilter objects should be provided by the JCC platform implementation. It is hoped that these filters will meet the needs of many applications, thus sparing them of the need to implement them explicitly. It is also possible that by implementing these on the JCC platform (rather than on the application platform) that the cost of remote filter queries can be eliminated thereby addressing the performance problems.

Hence, three standard filters and two filter combiners are proposed. The effect of these three standard filters and two filter combiners is to allow for address ranges in combination with event "masks", an extension of the original event listener proposal. Using these methods, it is possible to create filters that return a given event disposition for address in specific ranges (with holes and overlaps), or for specific events, or a combination of both. It is also possible to make filters that combine standard and custom filters. This would make it possible to quickly determine the filter disposition in many common cases, using standard filters, and only call a custom filter is unusual cases. We later look at each of these standard filters individually.

Event Snapshots
It should also be pointed out that when a 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.


Fields inherited from interface jain.jcp.JcpProvider
IN_SERVICE, OUT_OF_SERVICE, SHUTDOWN
 
Method Summary
 void addCallListener(JcpCallListener calllistener)
          Add a call listener to all call objects that will be created under the domain of this provider.
 void addCallListener(JcpCallListener calllistener, EventFilter filter)
          Add a call listener to all call objects that will be created under the domain of this provider.
 void addCallLoadControlListener(CallLoadControlListener loadcontrollistener, EventFilter filter)
          Adds a listener to listen to load control related events.
 void addConnectionListener(JcpConnectionListener connectionlistener, EventFilter filter)
          Add a connection listener to all connections under this JcpProvider.
 void addProviderListener(JcpProviderListener providerlistener, EventFilter filter)
          Adds a listener to this provider.
 EventFilter createEventFilterAddressRange(JcpAddress lowAddress, JcpAddress highAddress, int matchDisposition, int nomatchDisposition)
          This method returns a standard EventFilter which is implemented by the JCC platform.
 EventFilter createEventFilterAddressRE(java.lang.String addressRE, int matchDisposition, int nomatchDisposition)
          This method returns a standard EventFilter which is implemented by the JCC platform.
 EventFilter createEventFilterAnd(EventFilter[] filters, int nomatchDisposition)
          This method returns a standard EventFilter which is implemented by the JCC platform.
 EventFilter createEventFilterEventSet(int[] blockEvents, int[] notifyEvents)
           This method returns a standard EventFilter which is implemented by the JCC platform.
 EventFilter createEventFilterOr(EventFilter[] filters, int nomatchDisposition)
          This method returns a standard EventFilter which is implemented by the JCC platform.
 void removeCallListener(JcpCallListener calllistener)
          Removes a call listener that was registered using JccProvider.addCallListener.
 void removeCallLoadControlListener(CallLoadControlListener loadcontrollistener)
          Deregisters the load control listener.
 void removeConnectionListener(JcpConnectionListener connectionlistener)
          Removes a connection listener that was registered using this.addConnectionListener.
 void setCallLoadControl(JcpAddress[] address, double duration, double[] mechanism, int[] treatment)
          This method imposes or removes load control on calls made to the specified addresses.
 
Methods inherited from interface jain.jcp.JcpProvider
addProviderListener, createCall, getAddress, getName, getState, removeProviderListener, shutdown
 

Method Detail

createEventFilterEventSet

public EventFilter createEventFilterEventSet(int[] blockEvents,
                                             int[] notifyEvents)

This method returns a standard EventFilter which is implemented by the JCC platform. This method takes two arrays of eventID integers (values returned from event.getID()). For event IDs in the blockEvents array, the filter returns EVENT_BLOCK. For event IDs in notifyEvents, the filter returns EVENT_NOTIFY. If any event ID is not listed in one of the three arrays, the filter returns EVENT_DISCARD. The application is supposed to ensure that an event ID is not listed in more than one array. If done, the filter may return any one of the listed event dispositions.

Returns:
EventFilter standard EventFilter provided by the JCC platform to enable filtering of events based on the application's requirements.

createEventFilterAddressRange

public EventFilter createEventFilterAddressRange(JcpAddress lowAddress,
                                                 JcpAddress highAddress,
                                                 int matchDisposition,
                                                 int nomatchDisposition)
This method returns a standard EventFilter which is implemented by the JCC platform. This requires a complete ordering of values in JCPAddress. The ordering is arranged by defining the order to be by JCPAddress.getName()'s string order. For each address in the call obtained by event.getCall(), apply the following. If the address is between lowAddress and highAddress (inclusive), the filter returns the value matchDisposition. If the address is not in the range specified, then return nomatchDisposition.
Parameters:
lowAddress - denotes the JcpAddress which corresponds to the low end of the range.
highAddress - denotes the JcpAddress which corresponds to the high end of the range.
matchDisposition - indicates the disposition of a JCC related event occurring on a JcpAddress which forms part of the range specified. This should be one of the legal dispositions namely, EVENT_BLOCK, EVENT_DISCARD or EVENT_NOTIFY.
nomatchDisposition - indicates the disposition of a JCC related event occurring on a JcpAddress which DOES not form part of the range specified. This should be one of the legal dispositions namely, EVENT_BLOCK, EVENT_DISCARD or EVENT_NOTIFY.
Returns:
EventFilter standard EventFilter provided by the JCC platform to enable filtering of events based on the application's requirements.

createEventFilterAddressRE

public EventFilter createEventFilterAddressRE(java.lang.String addressRE,
                                              int matchDisposition,
                                              int nomatchDisposition)
This method returns a standard EventFilter which is implemented by the JCC platform. This requires a complete ordering of values in JCPAddress. The ordering is arranged by defining the order to be by JCPAddress.getName()'s string order. For each address in the call obtained by event.getCall(), apply the following. Obtain a string using address.getName(). If this string matches the regular expression addressRE, the filter returns the value matchDisposition. If no such addresses are matched, then return nomatchDisposition.
Parameters:
addressRE - denotes the regular expression.
matchDisposition - indicates the disposition of a JCC related event if the name of the JcpAddress matches the regular expression. This should be one of the legal dispositions namely, EVENT_BLOCK, EVENT_DISCARD or EVENT_NOTIFY.
nomatchDisposition - indicates the disposition of a JCC related event if the name of the JcpAddress DOES not matche the regular expression. This should be one of the legal dispositions namely, EVENT_BLOCK, EVENT_DISCARD or EVENT_NOTIFY.
Returns:
EventFilter standard EventFilter provided by the JCC platform to enable filtering of events based on the application's requirements.

createEventFilterOr

public EventFilter createEventFilterOr(EventFilter[] filters,
                                       int nomatchDisposition)
This method returns a standard EventFilter which is implemented by the JCC platform. This filter takes as input an array of EventFilters. For a given event, it applies the filters in order. If a filter returns nomatchDisposition, then the next filter is tested. If a filter returns any other disposition, then the filter returns this value and does no further filter evaluation. This would normally be called with nomatchDisposition set to EVENT_DISCARD to process any event (either by notifying or blocking) that any filterwants to process (logical OR).
Parameters:
filters - is an array of EventFilters.
nomatchDisposition - indicates the disposition of a JCC related event. This should be one of the legal dispositions namely, EVENT_BLOCK, EVENT_DISCARD or EVENT_NOTIFY.
Returns:
EventFilter standard EventFilter provided by the JCC platform to enable filtering of events based on the application's requirements.

createEventFilterAnd

public EventFilter createEventFilterAnd(EventFilter[] filters,
                                        int nomatchDisposition)
This method returns a standard EventFilter which is implemented by the JCC platform. This filter takes as input an array of EventFilters. For a given event, it applies the filters in order. If the values returned from all filters are the same, then this value is returned as the filter value. Otherwise, the filter returns nomatchDisposition. This means that as soon as any filter returns nomatchDisposition, or as soon as two filters return different values, the filter can immediately return nomatchDisposition. This would normally be called with nomatchDisposition set to EVENT_DISCARD to discard any events that any filter wants to discard (logical AND).
Parameters:
filters - is an array of EventFilters.
nomatchDisposition - indicates the disposition of a JCC related event. This should be one of the legal dispositions namely, EVENT_BLOCK, EVENT_DISCARD or EVENT_NOTIFY.
Returns:
EventFilter standard EventFilter provided by the JCC platform to enable filtering of events based on the application's requirements.

addProviderListener

public void addProviderListener(JcpProviderListener providerlistener,
                                EventFilter filter)
                         throws ResourceUnavailableException,
                                MethodNotSupportedException
Adds a listener to this provider. Provider 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 this.removeProviderListener() method or until the JcpProvider is no longer observable.
Further, this method gives flexibility to the application developers to specify the filtering algorithm explicitly which they would do using the object implementing the filter interface. This way the filtering algorithm can be designed based on the needs of the application.
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 Providers so they can monitor the changes in state in the Provider. Note that, registering a single listener twice should not result in the listener possibly being notified twice. Instead this will result in replacement of the current filter with the filter specified in the latest addProviderXXX method.

Parameters:
providerlistener - JcpProviderListener object that receives the specified events.
filter - EventFilter object used to specify the filtering algorithm explicitly and which determines whether the event is to be sent to the specified listener.
Throws:
MethodNotSupportedException - The listener cannot be added at this time.
ResourceUnavailableException - The resource limit for the number of listeners has been exceeded.

addCallListener

public void addCallListener(JcpCallListener calllistener)
                     throws MethodNotSupportedException,
                            ResourceUnavailableException
Add a call listener to all call objects that will be created under the domain of this provider. This includes changes in the state of the JcpCall and all JcpConnection-related events. The listener added with this method will report events on the call for as long as the implementation can listen to the Call. In the case that the implementation can no longer observe the JcpCall, the applications receives a CALL_EVENT_TRANSMISSION_ENDED. The listener receives no more events after it receives the CALL_EVENT_TRANSMISSION_ENDED.

Listener Lifetime
The JcpCallListener will receive events until one of the following occurs, whereupon the listener receives a CALL_EVENT_TRANSMISSION_ENDED.

  1. The listener is removed by the application.
  2. The implementation can no longer monitor the call.
  3. The JcpCall has completed and moved into the JcpCall.INVALID state.
Multiple Invocations
If an application attempts to add an instance of an listener already present on this Call, then a repeated invocation will silently fail, i.e. multiple instances of an listener are not added and no exception will be thrown.
Post-Conditions:

  1. A snapshot of events is delivered to the listener, if appropriate.

Parameters:
calllistener - JcpCallListener 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.

addCallListener

public void addCallListener(JcpCallListener calllistener,
                            EventFilter filter)
                     throws ResourceUnavailableException,
                            MethodNotSupportedException
Add a call listener to all call objects that will be created under the domain of this provider. This includes changes in the state of the JcpCall and all JcpConnection-related events. The listener added with this method will report events on the call for as long as the implementation can listen to the Call. In the case that the implementation can no longer observe the Call, the applications receive a CALL_EVENT_TRANSMISSION_ENDED. The listener receives no more events after it receives the CALL_EVENT_TRANSMISSION_ENDED.

Listener Lifetime
The CallListener will receive events until one of the following occurs, whereupon the listener receives a CALL_EVENT_TRANSMISSION_ENDED.

  1. The listener is removed by the application.
  2. The implementation can no longer monitor the call.
  3. The Call has completed and moved into the JcpCall.INVALID state.
Multiple Invocations
If an application attempts to add an instance of an listener already present on this Call, then a repeated invocation will silently fail, i.e. multiple instances of an listener are not added and no exception will be thrown. This though results in the filter being added in the last invocation being used by the implementation to filter events.
Post-Conditions:

  1. A snapshot of events is delivered to the listener, if appropriate.

Parameters:
calllistener - JcpCallListener object that receives the specified events.
filter - EventFilter that determines if an event should be delivered to the registered JcpCallListener.
Throws:
MethodNotSupportedException - The listener cannot be added at this time.
ResourceUnavailableException - The resource limit for the number of listeners has been exceeded.

removeCallListener

public void removeCallListener(JcpCallListener calllistener)
Removes a call listener that was registered using JccProvider.addCallListener. The given listener will no longer receive events generated by the Call objects on this Provider. Also, if the listener is not currently registered with the Provider, then this method fails silently, i.e. no listener is removed and no exception is thrown.

Post-Conditions:

  1. CALL_EVENT_TRANSMISSION_ENDED is delivered to the application.

Parameters:
calllistener - JcpCallListener object to be removed.

addConnectionListener

public void addConnectionListener(JcpConnectionListener connectionlistener,
                                  EventFilter filter)
                           throws ResourceUnavailableException,
                                  MethodNotSupportedException
Add a connection listener to all connections under this JcpProvider.

Note that registering for the same event multiple times should not result in multiple notifications being sent to an application for the same event. Rather, this will result in the last event filter being used to determine if events have to be delivered to the specified ConnectionListener.
Note that this method is also equivalent to this.addCallListener(JcpConnectionListener, filter) since parameter JcpConnectionListener is also a JcpCallListener. However note that JcpCallListeners which are not JcpConnectionListeners cannot be used as a parameter to this method. Thus, this method can be used to add ONLY JcpConnectionListeners and not both JcpConnectionListeners and JcpCallListeners like this.addCallListener().
Post-Conditions:

  1. A snapshot of events is delivered to the listener, if appropriate.

Parameters:
connectionlistener - JcpConnectionListener object that receives the specified events.
filter - EventFilter determines if the ConnectionEvent is to be delivered to the specified listener.
Throws:
MethodNotSupportedException - The listener cannot be added at this time.
ResourceUnavailableException - The resource limit for the number of listeners has been exceeded.

removeConnectionListener

public void removeConnectionListener(JcpConnectionListener connectionlistener)
Removes a connection listener that was registered using this.addConnectionListener. The given listener will no longer receive events generated by the JcpConnection objects related to this JcpProvider object through a JcpCall object. 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.

Parameters:
connectionlistener - JcpConnectionListener object used in the call to addConnectionListener method.

setCallLoadControl

public void setCallLoadControl(JcpAddress[] address,
                               double duration,
                               double[] mechanism,
                               int[] treatment)
                        throws MethodNotSupportedException
This method imposes or removes load control on calls made to the specified addresses.

The implementation can throw the MethodNotSupportedException if the platform does not support the load control functionality. Note that a policy object may be designed to define the policy to be implemented by the platform as a result of this method instead of defining the policy through the given parameters. This might be designed in the future specifications.

Parameters:
address - An array of size at most 2. a1[0] denotes the lower address of the range while a1[1] denotes the uper address of the range. Specifying only one element of the array implies that only an individual address is no longer to be the subject of the listener's attention. This constrains the range of addresses added to be numerical addresses. For addresses containing non-numerals such as email addresses, we expect that the application would have to add each address individually. Note that it is expected that adding a range of non-numerical addresses efficiently will be addressed in a future version of this specification.
duration - specifies the duration in milliseconds for which the load control should be set. Duration of 0 indicates that the load control should be removed. Duration of -1 indicates an infinite duration (i.e until disabled by the application). Duration of -2 indicates network default duration.
mechanism - specifies the load control mechanism to use (such as admitting one call per interval) and any necessary parameters. The contents of this parameter are ignored if the load control duration is set to zero.mech[0] symbolises the call admission rate of the call load control mechanism used. mech[1] symbolises the type of call load control mechanism to use. Thus, mech[0] gives the number of calls to be admitted per interval and mech[1] denotes the interval (in milliseconds) between calls that are admitted.
treatment - specifies the treatment of the calls that are not admitted.The contents of this parameter are ignored if the load control duration is set to zero.
Throws:
MethodNotSupportedException - If the implementation does not have load control functionality.

addCallLoadControlListener

public void addCallLoadControlListener(CallLoadControlListener loadcontrollistener,
                                       EventFilter filter)
                                throws MethodNotSupportedException,
                                       ResourceUnavailableException
Adds a listener to listen to load control related events. Note that the load control functionality has to have been specified separately using this.setCallLoadControl(..) method.
Parameters:
loadcontrollistener - The listener implementing the CallLoadControlListener interface which will receive all load control related events.
filter - EventFilter which specifies if the CallLoadControlEvent is to be delivered to the specified CallLoadControlListener.
Throws:
MethodNotSupportedException - The listener cannot be added at this time.
ResourceUnavailableException - The resource limit for the number of listeners has been exceeded.

removeCallLoadControlListener

public void removeCallLoadControlListener(CallLoadControlListener loadcontrollistener)
Deregisters the load control listener. This results in the listener not receiving any load control related events in the future. Note that if loadcontrollistener is not already registered using the this.addCallLoadControlListener(..) method then this method fails silently.
Parameters:
loadcontrollistener - The listener implementing the CallLoadControlListener interface which will receive all load control related events


3 Oct 2000
If you have any comments or queries, please mail them to jcc@research.telcordia.com


Copyright-2000 Sun Microsystems