|
JCC v0.9.2 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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". 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.
JcpProviderListener
is added through JcpProvider.addProviderListener(JcpProviderListener)
or addProviderListener(JcpProviderListener,EventFilter)
,
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.
Fields inherited from interface jain.application.services.jcp.JcpProvider |
IN_SERVICE,
OUT_OF_SERVICE,
SHUTDOWN |
Method Summary | |
void |
addCallListener(JccCallListener calllistener,
EventFilter filter)
Add a call listener to all call objects that will be created under the domain of this provider. |
void |
addCallListener(JcpCallListener calllistener)
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(JccConnectionListener 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(java.lang.String lowAddress,
java.lang.String 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 previously registered. |
void |
removeCallLoadControlListener(CallLoadControlListener loadcontrollistener)
Deregisters the load control listener. |
void |
removeConnectionListener(JcpConnectionListener connectionlistener)
Removes a connection listener that was registered previously. |
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.application.services.jcp.JcpProvider |
addProviderListener,
createCall,
getAddress,
getName,
getState,
removeProviderListener,
shutdown |
Method Detail |
public EventFilter createEventFilterEventSet(int[] blockEvents, int[] notifyEvents) throws ResourceUnavailableException
JcpEvent.getID()
).
For event IDs in the blockEvents array, the filter returns EventFilter.EVENT_BLOCK
.
For event IDs in notifyEvents, the filter returns EventFilter.EVENT_NOTIFY
.
If any event ID is not listed in one of the three arrays, the filter returns
EventFilter.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.public EventFilter createEventFilterAddressRange(java.lang.String lowAddress, java.lang.String highAddress, int matchDisposition, int nomatchDisposition) throws ResourceUnavailableException
JcpAddress.getName()
's string order.
For each address in the call obtained by JcpCallEvent.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.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, EventFilter.EVENT_BLOCK
, EventFilter.EVENT_DISCARD
or EventFilter.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, EventFilter.EVENT_BLOCK
, EventFilter.EVENT_DISCARD
or EventFilter.EVENT_NOTIFY
.public EventFilter createEventFilterAddressRE(java.lang.String addressRE, int matchDisposition, int nomatchDisposition) throws ResourceUnavailableException
JcpAddress.getName()
's string order.
For each address in the call obtained by JcpCallEvent.getCall()
, apply the following.
Obtain a string using address.getName().
If this string matches the regular expression addressRE, the filter returns
the value matchDisposition. For the purpose of this specification, the platform
will use the Perl5 regular expressions.
If no such addresses are matched, then return nomatchDisposition.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, EventFilter.EVENT_BLOCK
, EventFilter.EVENT_DISCARD
or EventFilter.EVENT_NOTIFY
.nomatchDisposition
- indicates the disposition of a JCC related event if the
name of the JcpAddress DOES not match the regular expression. This should be one of the
legal dispositions namely, EventFilter.EVENT_BLOCK
, EventFilter.EVENT_DISCARD
or EventFilter.EVENT_NOTIFY
.public EventFilter createEventFilterOr(EventFilter[] filters, int nomatchDisposition) throws ResourceUnavailableException
EventFilter.EVENT_DISCARD
to
process any event (either by notifying or blocking) that any filter wants to
process (logical OR).filters
- is an array of EventFilters.nomatchDisposition
- indicates the disposition of a JCC related event.
This should be one of the
legal dispositions namely, EventFilter.EVENT_BLOCK
, EventFilter.EVENT_DISCARD
or EventFilter.EVENT_NOTIFY
.public EventFilter createEventFilterAnd(EventFilter[] filters, int nomatchDisposition) throws ResourceUnavailableException
EventFilter.EVENT_DISCARD
to
discard any events that any filter wants to discard (logical AND).filters
- is an array of EventFilters.nomatchDisposition
- indicates the disposition of a JCC related event.
This should be one of the
legal dispositions namely, EventFilter.EVENT_BLOCK
, EventFilter.EVENT_DISCARD
or EventFilter.EVENT_NOTIFY
.public void addProviderListener(JcpProviderListener providerlistener, EventFilter filter) throws ResourceUnavailableException, MethodNotSupportedException
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 JcpProvider.removeProviderListener(JcpProviderListener)
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
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 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.
Post-Conditions:
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.public void addCallListener(JcpCallListener calllistener) throws MethodNotSupportedException, ResourceUnavailableException
JcpCallEvent.CALL_EVENT_TRANSMISSION_ENDED
.
The listener receives
no more events after it receives the JcpCallEvent.CALL_EVENT_TRANSMISSION_ENDED
.
JcpCallListener
will
receive events until one of the following occurs, whereupon the
listener receives a JcpCallEvent.CALL_EVENT_TRANSMISSION_ENDED
.
JcpCall.INVALID
state. calllistener
- JcpCallListener object that receives the specified events.public void addCallListener(JccCallListener calllistener, EventFilter filter) throws ResourceUnavailableException, MethodNotSupportedException
JcpCallEvent.CALL_EVENT_TRANSMISSION_ENDED
.
The listener receives
no more events after it receives the JcpCallEvent.CALL_EVENT_TRANSMISSION_ENDED
.
This method behaves identically to the method
addCallListener( JcpCallListener)
when the filter returns
a EventFilter.EVENT_NOTIFY
for all the events of interest.
CallListener
will
receive events until one of the following occurs, whereupon the
listener receives a JcpCallEvent.CALL_EVENT_TRANSMISSION_ENDED
.
JcpCall.INVALID
state. calllistener
- JcpCallListener object that receives the specified events.filter
- EventFilter that determines if an event should be delivered
to the registered JcpCallListener.public void removeCallListener(JcpCallListener calllistener)
Post-Conditions:
calllistener
- JcpCallListener object to be removed.public void addConnectionListener(JccConnectionListener connectionlistener, EventFilter filter) throws ResourceUnavailableException, MethodNotSupportedException
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 addCallListener(JcpConnectionListener,EventFilter). since parameter JcpConnectionListener is also a JcpCallListener. However note that JcpCallListeners which are not JcpConnectionListeners cannot be used as a parameter to this method.
connectionlistener
- JcpConnectionListener object that receives the specified events.filter
- EventFilter determines if the ConnectionEvent is
to be delivered to the specified listener.public void removeConnectionListener(JcpConnectionListener connectionlistener)
Post-Conditions:
connectionlistener
- JcpConnectionListener object used in the call to addConnectionListener method.public void setCallLoadControl(JcpAddress[] address, double duration, double[] mechanism, int[] treatment) throws MethodNotSupportedException
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.
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.public void addCallLoadControlListener(CallLoadControlListener loadcontrollistener, EventFilter filter) throws MethodNotSupportedException, ResourceUnavailableException
setCallLoadControl(JcpAddress[],double,double[],int[])
method.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.public void removeCallLoadControlListener(CallLoadControlListener loadcontrollistener)
setCallLoadControl(JcpAddress[],double,double[],int[])
method then this method
fails silently.loadcontrollistener
- The listener implementing the CallLoadControlListener interface which will
receive all load control related events
|
JCC v0.9.2 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |