jain.jcc
Interface JccCall

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.

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.jcp.JcpCall

ACTIVE, IDLE, INVALID

Method Summary

void	addCallListener(JcpCallListener calllistener, EventFilter filter) Add a listener to this call.
void	addConnectionListener(JcpConnectionListener cl, EventFilter filter) Add a connection listener to all connections under this call.
JcpConnection	createConnection(java.lang.String targetAddress, java.lang.String originatingAddress, java.lang.String originalCalledAddress, java.lang.String redirectingAddress) Creates a new JccConnection and attaches it to this JccCall.
void	release() This method requests the release of the call object and associated connection objects.
void	removeConnectionListener(JcpConnectionListener cl) Removes the connection listener from all connections under this call.
JcpConnection	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 given call party.
void	superviseCall(JccCallListener calllistener, double time, int treatment, double bytes) The application calls this method to supervise a call.

Methods inherited from interface jain.jcp.JcpCall

addCallListener, getConnections, getProvider, getState, removeCallListener

Method Detail

addCallListener

public void addCallListener(JcpCallListener 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 JccCall.INVALID state the application receives a CALL_EVENT_TRANSMISSION_ENDED event.

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.

Parameters:

calllistener - JcpCallListener 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(JcpConnectionListener cl,
                                  EventFilter filter)
                           throws ResourceUnavailableException,
                                  MethodNotSupportedException

Add a connection listener to all connections under this call.

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.

Parameters:

cl - JcpConnectionListener 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(JcpConnectionListener 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.

Parameters:

cl - JcpConnectionListener 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 DISCONNECTED state. The call will also be terminated in the network. If the application has registered as a listener then it receives the CallEvent.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. JcpCallEvent.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 JcpConnection createConnection(java.lang.String targetAddress,
                                      java.lang.String originatingAddress,
                                      java.lang.String originalCalledAddress,
                                      java.lang.String redirectingAddress)
                               throws InvalidStateException,
                                      ResourceUnavailableException,
                                      PrivilegeViolationException,
                                      MethodNotSupportedException

Creates a new JccConnection and attaches it to this JccCall. The JccConnection object is also associated with an JccAddress object corresponding to the targetAddress string given as an input parameter. Note that following this operation the JccConnection object might have to be routed to the JccAddress which can be accomplished using the JccConnection.routeConnection().

Pre-conditions:

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

Post-conditions:

1. let conn = createConnection(..);
   
2. conn.getState() == JcpConnection.IDLE state
   
3. this.getState() == JcpCall.ACTIVE
   
4. this.getProvider().getState ==JcpProvider.IN_SERVICE
   

Parameters:

targetAddress - specifies the JcpAddress with which the connection should be associated.

originatingAddress - specifies the address of the originating (calling) party for this leg of the call. This is optional and can be set to null.

originalCalledAddress - specifies the initial 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:

JccConnection object created.

Throws:

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

routeCall

public JcpConnection 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 given call party. This results in the creation of a JccConnection object associated with this JccCall. The JccConnection object is also associated with a JcpAddress passed as the parameter. Note that the address is passed as a string. The implementation is expected to find the JccAddress object corresponding to the string assuming that the JccAddress is local to the JcpProvider. The given string may not correspond to any JccAddress object in the JcpProvider's domain which would be the case for a call to a remote Address. This method is equivalent to the JccCall.createConnection(), JccConnection.routeConnection(FALSE)and JccConnection.attachMedia() or is also equivalent to JccCall.createConnection() and JccConnection.routeConnection(TRUE).

Pre-conditions:

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

Post-conditions:

1. conn.getState() != IDLE or AUTHORISE_CALL_ATTEMPT where conn is the object returned as a result of this method.
   
2. this.getState() ==JcpCall.ACTIVE
   
3. this.getProvider().getState == JcpProvider.IN_SERVICE
   

Parameters:

targetAddress - specifies the origination party to which the call should be routed.

originatingAddress - specifies the address of the originating (calling) party. This parameter is optional and hence can be set to null.

originalDestinationAddress - specifies the original destination Address of the call. This parameter is optional and hence can be set to null.

Returns:

JcpConnection object created

Throws:

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 - The originator does not represent a valid party required to place a call.

InvalidArgumentException - The provided argument is not valid

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(), the timer measurement will start as soon as the call is answered by the called party.
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.01 to release the call when the call supervision timer expires.
2.02 to notify the application when the call supervision timer expires.
3. 04 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.