|
JCC v1.0 |
|||||||||
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)
,
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 (future and current) call objects within the domain of this provider. |
void |
addCallListener(JcpCallListener calllistener)
Add a call listener to all (future and current) call objects within 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. |
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 |
createEventFilterAddressRegEx(java.lang.String addressRegex,
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 |
createEventFilterDestAddressRange(java.lang.String lowDestAddress,
java.lang.String highDestAddress,
int matchDisposition,
int nomatchDisposition)
This method returns a standard EventFilter which is implemented by the JCC platform. |
EventFilter |
createEventFilterDestAddressRegEx(java.lang.String destAddressRegex,
int matchDisposition,
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. |
EventFilter |
createEventFilterOrigAddressRange(java.lang.String lowOrigAddress,
java.lang.String highOrigAddress,
int matchDisposition,
int nomatchDisposition)
This method returns a standard EventFilter which is implemented by the JCC platform. |
EventFilter |
createEventFilterOrigAddressRegEx(java.lang.String origAddressRegex,
int matchDisposition,
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(JccAddress[] 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, InvalidArgumentException
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 two 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.ResourceUnavailableException
- An internal resource for completing this
call is unavailable.InvalidArgumentException
- One or more of the provided argument is not validpublic EventFilter createEventFilterAddressRange(java.lang.String lowAddress, java.lang.String highAddress, int matchDisposition, int nomatchDisposition) throws ResourceUnavailableException, InvalidArgumentException
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
.ResourceUnavailableException
- An internal resource for completing this
call is unavailable.InvalidArgumentException
- One or more of the provided argument is not validpublic EventFilter createEventFilterAddressRegEx(java.lang.String addressRegex, int matchDisposition, int nomatchDisposition) throws ResourceUnavailableException, InvalidArgumentException
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 addressRegex, 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.addressRegex
- 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
.ResourceUnavailableException
- An internal resource for completing this
call is unavailable.InvalidArgumentException
- One or more of the provided argument is not validpublic EventFilter createEventFilterOr(EventFilter[] filters, int nomatchDisposition) throws ResourceUnavailableException, InvalidArgumentException
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
.ResourceUnavailableException
- An internal resource for completing this
call is unavailable.InvalidArgumentException
- One or more of the provided argument is not validpublic EventFilter createEventFilterAnd(EventFilter[] filters, int nomatchDisposition) throws ResourceUnavailableException, InvalidArgumentException
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
.ResourceUnavailableException
- An internal resource for completing this
call is unavailable.InvalidArgumentException
- One or more of the provided argument is not validpublic EventFilter createEventFilterDestAddressRange(java.lang.String lowDestAddress, java.lang.String highDestAddress, int matchDisposition, int nomatchDisposition) throws ResourceUnavailableException, InvalidArgumentException
JcpAddress.getName()
's string order.
For each originating connection, apply the following.
Obtain a string using getDestinationAddress().
If the destination
address is between lowDestAddress and highDestAddress (inclusive), the filter returns the value matchDisposition.
If the address is not in the specified range or the filter is not operating on an originating connection, then return nomatchDisposition.lowDestAddress
- denotes the destination JcpAddress which corresponds to the low end of the
range.highDestAddress
- denotes the destination 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
.ResourceUnavailableException
- An internal resource for completing this
call is unavailable.InvalidArgumentException
- One or more of the provided argument is not validpublic EventFilter createEventFilterDestAddressRegEx(java.lang.String destAddressRegex, int matchDisposition, int nomatchDisposition) throws ResourceUnavailableException, InvalidArgumentException
JcpAddress.getName()
's string order.
For each originating connection, apply the following.
Obtain a string using getDestinationAddress():
If this string matches the regular expression destAddressRegex, 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 or the filter is not operating on an originating connection, then return nomatchDisposition.destAddressRegex
- denotes the regular expression for the destination address.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
.ResourceUnavailableException
- An internal resource for completing this
call is unavailable.InvalidArgumentException
- One or more of the provided argument is not validpublic EventFilter createEventFilterOrigAddressRange(java.lang.String lowOrigAddress, java.lang.String highOrigAddress, int matchDisposition, int nomatchDisposition) throws ResourceUnavailableException, InvalidArgumentException
JcpAddress.getName()
's string order.
For each destination connection, apply the following.
Obtain a string using getOriginatingAddress().getName().
If the destination
address is between lowOrigAddress and highOrigAddress (inclusive), the filter returns the value matchDisposition.
If the address is not in the specified range or the filter is not operating on a terminating connection, then return nomatchDisposition.lowOrigAddress
- denotes the originating JcpAddress which corresponds to the low end of the
range.highOrigAddress
- denotes the originating 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
.ResourceUnavailableException
- An internal resource for completing this
call is unavailable.InvalidArgumentException
- One or more of the provided argument is not validpublic EventFilter createEventFilterOrigAddressRegEx(java.lang.String origAddressRegex, int matchDisposition, int nomatchDisposition) throws ResourceUnavailableException, InvalidArgumentException
JcpAddress.getName()
's string order.
For each originating connection, apply the following.
Obtain a string using getOriginatingAddress().getName():
If this string matches the regular expression origAddressRegex, 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 or the filter is not operating on a terminating connection, then return nomatchDisposition.origAddressRegex
- denotes the regular expression for the originating address.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
.ResourceUnavailableException
- An internal resource for completing this
call is unavailable.InvalidArgumentException
- One or more of the provided argument is not validpublic 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.
JcpConnectionListener
inherits from the JcpCallListener, it is also
possible to add a JcpConnectionListener using this method. In such a case,
connection events would also have to be reported to the
registered listener in addition to the call events.
Hence, it is expected that the JCC implementation uses instanceof checks
in order to decide if only call events or both call and connection events
have to be delivered to the listener. Note that a listener added by this
method is expecting all the events without any filtering involved.
calllistener
- JcpCallListener object that receives the specified events.MethodNotSupportedException
- The method is not supported.ResourceUnavailableException
- The resource limit for the number of
listeners has been exceeded.
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
- JccCallListener object that receives the specified events.filter
- EventFilter that determines if an event should be delivered
to the registered JcpCallListener.MethodNotSupportedException
- The method is not supported.ResourceUnavailableException
- The resource limit for the number of
listeners has been exceeded.
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(JccConnectionListener,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
- JccConnectionListener object that receives the specified events.filter
- EventFilter determines if the ConnectionEvent is
to be delivered to the specified listener.MethodNotSupportedException
- The listener cannot be added at this time.ResourceUnavailableException
- The resource limit for the number of
listeners has been exceeded.public void removeConnectionListener(JcpConnectionListener connectionlistener)
Post-Conditions:
connectionlistener
- JcpConnectionListener object used in the call to addConnectionListener method.public void setCallLoadControl(JccAddress[] 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.MethodNotSupportedException
- If the implementation does not
have load control functionality.public void addCallLoadControlListener(CallLoadControlListener loadcontrollistener, EventFilter filter) throws MethodNotSupportedException, ResourceUnavailableException
setCallLoadControl(JccAddress[],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.MethodNotSupportedException
- The listener cannot be added at this time.ResourceUnavailableException
- The resource limit for the number of
listeners has been exceeded.public void removeCallLoadControlListener(CallLoadControlListener loadcontrollistener)
setCallLoadControl(JccAddress[],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 v1.0 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |