JCAT
v0.3.1

javax.csapi.cc.jcc
Interface JccCall

All Known Subinterfaces:
JcatCall

public interface JccCall

A JccCall is a transient association of (zero or more) addresses for the purposes of engaging in a real-time communications interchange. The call and its associated connection and address objects describe the control and media flows taking place in some underlying "real world" communication network. Other parties involved in the call may also exert control over it, thus the membership and state of the endpoints may change without explicit request by the Jcc application. The JccProvider adjusts the call, address and connection objects to reflect the results of these combined command actions.

Introduction

A JccCall can have zero or more JccConnections. A two-party call has two JccConnections, and a conference call has three or more JccConnections. Each JccConnection models the relationship between a JccCall and an JccAddress, where an JccAddress identifies a particular party or set of parties on a call.

Creating JccCall Objects

Applications create instances of a JccCall object with the JccProvider.createCall() method, which returns a JccCall object that has zero Connections and is in the IDLE state. The JccCall maintains a reference to its JccProvider for the life of that JccCall object. The JccProvider object instance does not change throughout the lifetime of the JccCall object. The JccProvider associated with a JccCall is obtained via the getProvider() method.

JccCall States

A JccCall has a state which is obtained via the getState() method. This state describes the current progress of a telephone call, where is it in its life cycle, and how many connections exist on the call. The JccCall state may be one of three values: IDLE, ACTIVE, or INVALID. The following is a description of each state:
IDLE This is the initial state for all calls. In this state, the JccCall has zero connections, that is getConnections() must return null.
ACTIVE A call with some current ongoing activity is in this state. JccCalls with one or more associated JccConnections must be in this state. If a JccCall is in this state, the getConnections() method must return an array of size at least one.
INVALID This is the final state for all calls. JccCall objects which lose all of their JccConnection objects (via a transition of the JccConnection object into the JccConnection.DISCONNECTED state) moves into this state. Calls in this state have zero JccConnections and these JccCall objects may not be used for any future action. In this state, the getConnections() must return null.

JccCall State Transitions

Consider the transitions given below as the ones that would be visible to the application developer in the package considered. This may be either because there is a method in that class/interface that provides that behavior (read transition) or because of events in the underlying platform. Note that we are not making any statements to the effect that the other transitions (ones not shown) are disallowed. The application developer would have to keep in mind the possibility that the "invisible" transitions can surface (become visible) in inherited classes/interfaces.

JccCall FSM

JccCall and JccConnection objects

A JccCall maintains a list of the JccConnections on that JccCall. Applications obtain an array of JccConnections associated with the JccCall via the getConnections() method. A JccCall retains a reference to a JccConnection only if it is not in the JccConnection.DISCONNECTED state. Therefore, if a JccCall has a reference to a JccConnection, then that JccConnection must not be in the JccConnection.DISCONNECTED state. When a JccConnection moves into the JccConnection.DISCONNECTED state (e.g. when a party hangs up), the JccCall loses its reference to that JccConnection which is no longer reported via the JccCall.getConnections() method.

Listeners and Events

The JccCallListener or JccConnectionListener interface reports all events pertaining to the JccCall object. Events delivered to this interface must implement or extend the JccCallEvent interface. Applications can add listeners to a JccCall object via the addCallListener(JccCallListener) method.

Connection-related events can be reported via the JccConnectionListener interface. These events include the creation of these objects and their state changes. Events which are reported via the JccConnectionListener interface pertaining to JccConnections or JccCalls extend the JccConnectionEvent interface.

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.
When Event Transmission Ends
At times it may become impossible for the implementation to report events to an application. In this case, a JccCallEvent.CALL_EVENT_TRANSMISSION_ENDED is delivered to an object registered as a JccCallListener (or an extension of that interface). This is the final event received by the Listener from the call.

Since:
1.0

Field Summary
static int ACTIVE
          JccCall.ACTIVE state indicates the Call has one or more Connections none of which is in the JccConnection.DISCONNECTED state.
static int IDLE
          JccCall.IDLE state indicates the Call has zero Connections.
static int INVALID
          The JccCall.INVALID state indicates that the Call has lost all of its connections, that is, all of its Connection objects have moved into the JccConnection.DISCONNECTED state and are no longer associated with the Call.
 
Method Summary
 void addCallListener(JccCallListener calllistener)
          Add a listener to this call.
 void addConnectionListener(JccConnectionListener cl, EventFilter filter)
          Add a connection listener to all connections under this call.
 JccConnection[] connect(JccAddress origaddr, java.lang.String dialedDigits)
          Places a call from an originating address to a destination address string.
 JccConnection 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.
 JccConnection[] getConnections()
          Retrieves an array of connections asssociated with this call.
 JccProvider getProvider()
          Retrieves the provider handling this call object.
 int getState()
          Retrieves the state of the call.
 void release(int causeCode)
          This method requests the release of the call object and associated connection objects.
 void removeCallListener(JccCallListener calllistener)
          Removes a listener from this call.
 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)
          The application calls this method to supervise a call.
 

Field Detail

IDLE

public static final int IDLE
JccCall.IDLE state indicates the Call has zero Connections. This is the initial state of all Call objects.

See Also:
Constant Field Values

ACTIVE

public static final int ACTIVE
JccCall.ACTIVE state indicates the Call has one or more Connections none of which is in the JccConnection.DISCONNECTED state. The Call object transitions into this state from the IDLE state only.

See Also:
Constant Field Values

INVALID

public static final int INVALID
The JccCall.INVALID state indicates that the Call has lost all of its connections, that is, all of its Connection objects have moved into the JccConnection.DISCONNECTED state and are no longer associated with the Call. A Call in this state cannot be used for future actions.

See Also:
Constant Field Values
Method Detail

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 JccConnection that already exists when the method is called as well as any JccConnections 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.

Parameters:
cl - JccConnectionListener object that was registered using a corresponding addConnectionListener method.

release

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

Valid cause codes (prefixed by CAUSE_) for the integer that is named causeCode are defined in JccEvent and JccCallEvent.

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.

Parameters:
causeCode - an integer that represents a cause code. Valid values are defined in JccEvent and JccCallEvent, they are typically prefixed by CAUSE_.
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.
InvalidArgumentException - The given release cause code is invalid.
Since:
1.0a

superviseCall

public void superviseCall(JccCallListener calllistener,
                          double time,
                          int treatment)
                   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. A call supervision event is also sent if the call is terminated before the supervision event occurs.

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.
Throws:
MethodNotSupportedException - if the implementation does not support this method.
Since:
1.0b

connect

public JccConnection[] connect(JccAddress origaddr,
                               java.lang.String dialedDigits)
                        throws ResourceUnavailableException,
                               PrivilegeViolationException,
                               InvalidPartyException,
                               InvalidStateException,
                               MethodNotSupportedException
Places a call from an originating address to a destination address string.

The Call must be in the IDLE state (and therefore have no existing associated JccConnections and the Provider must be in the JccProvider.IN_SERVICE state. The successful effect of this method is to place the call and create and return two JccConnections associated with this Call.

Method Arguments
This method has two arguments. The first argument is the originating Address for the Call. The second argument is a destination string whose value represents the address to which the call is placed. This destination address must be valid and complete.
Method Post-conditions
This method returns successfully when the Provider can successfully initiate the placing of the call. As a result, when the JccCall.connect() method returns, the JccCall will be in the ACTIVE state and exactly two JccConnections will be created and returned. The JccConnection associated with the originating endpoint is the first JccConnection in the returned array. This JccConnection will execute the originating JccConnection's Final State Diagram (see table 3). The JccConnection associated with the destination endpoint is the second JccConnection in the returned array and will execute the terminating JccConnection's Final State Diagram. These two JccConnections must at least be in the JccConnection.IDLE state. That is, if one of the Connections progresses beyond the IDLE state while this method is completing, this Connection may be in a state other than the IDLE. This state must be reflected by an event sent to the application.

Pre-Conditions:

  1. (this.getProvider()).getState() == JccProvider.IN_SERVICE
  2. this.getState() == JccCall.IDLE
Post-Conditions:
  1. (this.getProvider()).getState() == JccProvider.IN_SERVICE
  2. this.getState() == JccCall.ACTIVE
  3. Let Connection c[] = this.getConnections()
  4. c.length == 2
  5. c[0].getState() == JccConnection.IDLE (at least)
  6. c[1].getState() == JccConnection.IDLE (at least)

Parameters:
origaddr - The originating Address for this call.
dialedDigits - The destination address string for this call.
Returns:
array of Connections
Throws:
ResourceUnavailableException - An internal resource necessary for placing the call is unavailable.
PrivilegeViolationException - The application does not have the proper authority to place a call.
InvalidPartyException - Either the originator or the destination does not represent a valid party required to place a call.
InvalidStateException - Some object required by this method is not in a valid state as designated by the pre-conditions for this method.
MethodNotSupportedException - The implementation does not support this method.
Since:
1.0a

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 and attaches it to this JccCall. The JccConnection object is associated with an JccAddress object corresponding to the string given as an input parameter. Note that following this operation the returned JccConnection object must still be routed to the JccAddress which can be accomplished using the JccConnection.routeConnection(boolean).
Examples

Pre-conditions:

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

Post-conditions:

  1. let conn = createConnection(..);
  2. conn.getState() == IDLE
  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. This is optional and can be set to null.
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:
the created JccConnection object
Throws:
InvalidArgumentException - An InvalidArgumentException indicates an argument passed to the method is invalid.
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 is 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. Creates a new JccConnection and attaches it to this JccCall. The JccConnection object is associated with an JccAddress object corresponding to the string given as an input parameter. 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).
Examples

Pre-conditions:

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

Post-conditions:

  1. let conn = routeCall(..);
  2. conn.getState() == IDLE (at least)
  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. 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:
the created JccConnection object
Throws:
InvalidArgumentException - An InvalidArgumentException indicates an argument passed to the method is invalid.
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 is invalid.

getState

public int getState()
Retrieves the state of the call. The state will be either IDLE, ACTIVE or INVALID.

Returns:
Integer representing the state of the call.

addCallListener

public void addCallListener(JccCallListener calllistener)
                     throws ResourceUnavailableException,
                            MethodNotSupportedException
Add a listener to this call. This also reports all state changes in the state of the Call and Connection objects. 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 call becomes unobservable the listener receives a JccCallEvent.CALL_EVENT_TRANSMISSION_ENDED event.
CallListeners from Provider
There may be additional call listeners on the call which were not added by this method. These listeners may have become part of the call via the JccProvider.addCallListener(JccCallListener) or similar methods.
ConnectionListeners
Since JccConnectionListener inherits from the JccCallListener, it is also possible to add a JccConnectionListener 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.
Multiple Invocations
If an application attempts to add an instance of a listener already present on this Call, there are two possible outcomes:
  1. If the listener was added by the application using this method, then a repeated invocation will silently fail, i.e. multiple instances of an listener are not added and no exception will be thrown.
  2. If the listener is part of the call because an application invoked JccProvider.addCallListener() either of these methods modifies the behavior of that listener as if it were added via this method instead.

Post-Conditions:

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

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

removeCallListener

public void removeCallListener(JccCallListener calllistener)
Removes a listener from this call. If the listener is not part of the Call for the given address(es), then this method fails silently, i.e. no listener is removed and no exception is thrown. Note that the listeners will stop receiving events for existing calls also.

This method has different effects depending upon how the listener was added to the Call, as follows:

  1. If the listener was added via addCallListener(JccCallListener), this method removes the listener until it is re-applied by the application.
  2. If the listener was added via JccProvider.addCallListener(JccCallListener) or simular methods, this method removes the listener for this call only. It does not affect whether this listener will be added to future calls coming in to the JccProvider.

Parameters:
calllistener - JccCall Listener object.

getProvider

public JccProvider getProvider()
Retrieves the provider handling this call object. The Provider reference does not change once the Call object has been created, despite the state of the Call object.

Returns:
JccProvider object managing this call.

getConnections

public JccConnection[] getConnections()
Retrieves an array of connections asssociated with this call. None of the Connections returned will be in the JccConnection.DISCONNECTED state. Further, if the Call is in the IDLE or INVALID state, this method returns null.

Post-Conditions:

  1. JccConnection[] conn = getConnections()
  2. if this.getState() == IDLE then conn=null
  3. if this.getState() == INVALID then conn=null
  4. if this.getState() == ACTIVE then conn.length >=1
  5. For all i, conn[i].getState() != DISCONNECTED

Returns:
Array of Connections for this call.

JCAT
v0.3.1

August, 2003
If you have any comments or queries, please mail them to JSR-122-EG@JCP.ORG

Copyright - 2001, 2003 Sun Microsystems