JCC
v1.0

jain.application.services.jcc
Interface JccCall

All Superinterfaces:
JcpCall

public interface JccCall
extends JcpCall

The JccCall interface extends the JcpCall interface of JCP. This interface provides additional methods on a Call. Further, the state machine on the JccCall is also similar to the state machine of the JcpCall except for an extra transition as shown in the following figure.

JccCall FSM

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.


Fields inherited from interface jain.application.services.jcp.JcpCall
ACTIVE, IDLE, INVALID
 
Method Summary
 void addCallListener(JccCallListener calllistener, EventFilter filter)
          Add a listener to this call.
 void addConnectionListener(JccConnectionListener cl, EventFilter filter)
          Add a connection listener to all connections under this call.
 JccConnection createConnection(java.lang.String targetAddress, java.lang.String originatingAddress, java.lang.String originalCalledAddress, java.lang.String redirectingAddress)
          Creates (a) new JccConnection(s) and attaches it/them to this JccCall.
 void release()
          This method requests the release of the call object and associated connection objects.
 void removeConnectionListener(JccConnectionListener cl)
          Removes the connection listener from all connections under this call.
 JccConnection routeCall(java.lang.String targetAddress, java.lang.String originatingAddress, java.lang.String originalDestinationAddress, java.lang.String redirectingAddress)
          This method requests routing of a call to the targetAddress given as an input parameter.
 void superviseCall(JccCallListener calllistener, double time, int treatment, double bytes)
          The application calls this method to supervise a call.
 
Methods inherited from interface jain.application.services.jcp.JcpCall
addCallListener, getConnections, getProvider, getState, removeCallListener
 

Method Detail

addCallListener

public void addCallListener(JccCallListener calllistener,
                            EventFilter filter)
                     throws ResourceUnavailableException,
                            MethodNotSupportedException
Add a listener to this call. This also reports all state changes in the state of the JccCall and JccConnection objects. The listener added with this method will report events on the call for as long as the implementation can listen to the JccCall. In the case that
  1. the implementation can no longer observe the JccCall
  2. this listener has been removed from this JccCall
  3. the JccCall has completed and moved to the JcpCall.INVALID state the application receives a JcpCallEvent.CALL_EVENT_TRANSMISSION_ENDED event.
Connection Events
A JccConnectionEvent extends JccCallEvent and a JccConnectionListener extends JccCallListener. Hence, a JccConnectionListener can also be added using this method. In such a case, events on the JccConnection objects associated with this JccCall object might have to be reported to the registered listener after consulting with the EventFilter. In summary the implementation must distinguish between JccCallListener, and JccConnectionListener in order to determine the events for which the implementation must consult the corresponding EventFilter.
Multiple Invocations
Registering a single listener twice will result in the application being notified of the events specified in the filter implementation used in the last registration. Note that, because of this, registering for the same event multiple times should not result in multiple notifications being sent to an application for the same event.

Post-Conditions:

  1. A snapshot of events is delivered to the listener, if appropriate.
Parameters:
calllistener - JccCallListener object that receives the specified events.
filter - EventFilter which determines if the event 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.

addConnectionListener

public void addConnectionListener(JccConnectionListener cl,
                                  EventFilter filter)
                           throws ResourceUnavailableException,
                                  MethodNotSupportedException
Add a connection listener to all connections under this call. This method applies to any JcpConnection that already exists when the method is called as well as any JcpConnections that will be added in the future to this JccCall object. This method behaves similar to the addCallListener(conListener, filter) method on this interface where conListener is in fact a JccConnectionListener. When conListener is not a JccConnectionListener but is only a JccCallListener, a similar behavior as addCallListener(conListener, newfilter) can be obtained with this method using a JccConnectionListener and a different EventFilter which filters all the JccConnection related events in addition to the events being filtered by newfilter. Note though that using this method only JccConnectionListeners can be added.

Registering a single listener twice will result in the last filter being used for the purposes of consultation to determine the events that the application is interested in. Note that registering for the same event multiple times should not result in multiple notifications being sent to an application for the same event.

Post-Conditions:

  1. A snapshot of events is delivered to the listener, if appropriate.
Parameters:
cl - JccConnectionListener object that receives the specified events.
filter - EventFilter determines if the event 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(JccConnectionListener cl)
Removes the connection listener from all connections under this call. Note that if the listener is currently not registered then this method fails silently.

Post-Conditions:

  1. CALL_EVENT_TRANSMISSION_ENDED is delivered to the application
Parameters:
cl - JccConnectionListener object that was registered using a corresponding addConnectionListener method.

release

public void release()
             throws PrivilegeViolationException,
                    ResourceUnavailableException,
                    InvalidStateException
This method requests the release of the call object and associated connection objects. Thus this method is equivalent to using the JccConnection.release() method on each JccConnection which is part of the Call. Typically each JccConnection associated with this call will move into the JcpConnection.DISCONNECTED state. The call will also be terminated in the network. If the application has registered as a listener then it receives the JcpCallEvent.CALL_EVENT_TRANSMISSION_ENDED event.

Pre-conditions:

  1. (this.getProvider()).getState() == IN_SERVICE
  2. this.getState() == ACTIVE

Post-conditions:

  1. (this.getProvider()).getState() == IN_SERVICE
  2. this.getState() == INVALID
  3. CALL_EVENT_TRANSMISSION_ENDED event delivered to the valid Calllisteners.
  4. Appropriate ConnectionEvents are also delivered to the ConnectionListeners.
Throws:
PrivilegeViolationException - The application does not have the authority or permission to disconnect the Call. For example, an Address associated with this Call may not be controllable in the Provider's domain.
ResourceUnavailableException - An internal resource required to drop a connection is not available.
InvalidStateException - Some object required for the successful invocation of this method is not in the proper state as given by this method's pre-conditions.

createConnection

public JccConnection createConnection(java.lang.String targetAddress,
                                      java.lang.String originatingAddress,
                                      java.lang.String originalCalledAddress,
                                      java.lang.String redirectingAddress)
                               throws InvalidStateException,
                                      ResourceUnavailableException,
                                      PrivilegeViolationException,
                                      MethodNotSupportedException,
                                      InvalidArgumentException,
                                      InvalidPartyException
Creates (a) new JccConnection(s) and attaches it/them to this JccCall. The JccConnection objects is/are associated with (an) JccAddress object(s) corresponding to the string(s) given as (an) input parameter(s). Note that following this operation the returned JccConnection object might have to be routed to the JccAddress which can be accomplished using the JccConnection.routeConnection(boolean).
Semantics
We recognize that these semantics are awkward. As the alignment process with other Call Control APIs continues, we might change these semantis in future versions of this API.

Consider party A calling party B in case of a first party call. In case of a third party call, consider party A and party B being connected. Below the behavior of this method is exemplified:

Pre-conditions:

  1. (this.getProvider()).getState() == IN_SERVICE
  2. this.getState() != INVALID

Post-conditions:

  1. let conn = createConnection(..);
  2. conn.getState() == IDLE state
  3. this.getState() == ACTIVE
  4. (this.getProvider()).getState() == IN_SERVICE
Parameters:
targetAddress - specifies the address to which the call should be routed.
originatingAddress - specifies the address of the originating (calling) party for this leg of the call.
originalCalledAddress - specifies the initial destination address to which this leg of the call was initiated. This is optional and can be set to null.
redirectingAddress - specifies the last address from which this leg of the call was redirected. This is optional and can be set to null.
Returns:
one of the JccConnection objects created.
Throws:
InvalidArgumentException - is case an either or both the targetAddress or the originatingAddress is set to null.
InvalidStateException - Some object required by this method is not in a valid state as designated by the pre-conditions for this method.
ResourceUnavailableException - An internal resource necessary for creating the Connection object is unavailable.
PrivilegeViolationException - The application does not have the proper authority to create the Connection.
MethodNotSupportedException - The implementation does not support this method
InvalidPartyException - In case one of the parties given in invalid.

routeCall

public JccConnection routeCall(java.lang.String targetAddress,
                               java.lang.String originatingAddress,
                               java.lang.String originalDestinationAddress,
                               java.lang.String redirectingAddress)
                        throws InvalidStateException,
                               ResourceUnavailableException,
                               PrivilegeViolationException,
                               MethodNotSupportedException,
                               InvalidPartyException,
                               InvalidArgumentException
This method requests routing of a call to the targetAddress given as an input parameter. This results in the creation of (a) JccConnection object(s) associated with this JccCall. The JccConnection object(s) is/are associated with an address object(s) passed as a parameter(s). Note that the addresses are passed as strings. The implementation is expected to find the JccAddress object corresponding to the string assuming that the JccAddress is local to the JccProvider. The given string may not correspond to any JccAddress object in the JccProvider's domain which would be the case for a call to a remote Address. This method is equivalent to the createConnection(String,String,String,String), JccConnection.routeConnection(FALSE) and JccConnection.attachMedia() or is also equivalent to createConnection(String,String,String,String) and JccConnection.routeConnection(TRUE).
Semantics
We recognize that these semantics are awkward. As the alignment process with other Call Control APIs continues, we might change these semantis in future versions of this API.

Consider party A calling party B in case of a first party call. In case of a third party call, consider party A and party B being connected. Below the behavior of this method is exemplified:

Pre-conditions:

  1. (this.getProvider()).getState() == IN_SERVICE
  2. this.getState() != INVALID

Post-conditions:

  1. conn.getState() != IDLE or AUTHORIZE_CALL_ATTEMPT or DISCONNECTED where conn is the object returned as a result of this method.
  2. this.getState() == ACTIVE
  3. (this.getProvider()).getState() == IN_SERVICE
Parameters:
targetAddress - specifies the address to which the call should be routed.
originatingAddress - specifies the address of the originating (calling) party for this leg of the call.
originalCalledAddress - specifies the initial destination address to which this leg of the call was initiated. This is optional and can be set to null.
redirectingAddress - specifies the last address from which this leg of the call was redirected. This is optional and can be set to null.
Returns:
one of the JccConnection objects created
Throws:
InvalidArgumentException - is case an either or both the targetAddress or the originatingAddress is set to null.
InvalidStateException - Some object required by this method is not in a valid state as designated by the pre-conditions for this method.
ResourceUnavailableException - An internal resource necessary for creating the Connection object is unavailable.
PrivilegeViolationException - The application does not have the proper authority to create the Connection.
MethodNotSupportedException - The implementation does not support this method
InvalidPartyException - In case one of the parties given in invalid.

superviseCall

public void superviseCall(JccCallListener calllistener,
                          double time,
                          int treatment,
                          double bytes)
                   throws MethodNotSupportedException
The application calls this method to supervise a call. The application can set a granted connection time for this call. If an application calls this function before it calls a routeCall(String,String,String,String), the timer measurement will start as soon as the call is answered by the called party.

The call supervision events are then reported to the listener registered using this method. The events related to call supervision are reported only to the listeners registered using this method.

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:
calllistener - JccCallListener object that receives the specified events.
time - specifies the granted time in milliseconds for the connection. When specified as 0, volume based supervision is applied. Either bytes(volume) or time should be specified.
treatment - defines the treatment of the call by the call control service when the call supervision timer expires. The values which may be combined using a logical OR function are:
  1. 0x01 to release the call when the call supervision timer expires.
  2. 0x02 to notify the application when the call supervision timer expires.
  3. 0x04 to send a warning tone to the controlling party when a call supervision timer expires. If call release is requested, then the call will be released following the tone after an administered time period.
bytes - specifies the granted number of bytes that can be transmitted for the connection. When the quantity is specified as 0, time based supervision is applied.
Throws:
MethodNotSupportedException - if the implementation does not support this method.

JCC
v1.0

January 19, 2001
If you have any comments or queries, please mail them to m-JAIN-JCC@notes.cc.telcordia.com

Copyright - 2001 Sun Microsystems