JCAT
v0.3.1

javax.jcat
Interface JcatConnection

All Superinterfaces:
JccConnection

public interface JcatConnection
extends JccConnection

The JcatConnection interface extends the JccConnection interface. While the JccConnection interface specified the relationship between the JccCall and JccAddress objects, JcatConnection is also associated additionally with a JcatTerminal (through the JcatTerminalConnection object). This is expected to enable advanced call control services which require multiple terminals per address or multiple addresses per terminal. These capabilities would be needed given the potential of devices today such as the PDA (considered as a terminal), which can handle voice calls as VOIP as well as using the mobile voice networks (each of which requires separate addresses).

Thus, each JcatConnection object is associated directly with a JcatCall, a JcatAddress and a JcatTerminalConnection object. The JcatConnection object has a finite state machine associated with it. A JcatConnection object maintains a state that reflects the relationship between a JcatCall and a JcatAddress as well as between the JcatCall and the JcatTerminal (through the JcatTerminalConnection object). The JcatConnection state is important to the application because it indicates a logical view to the application. The application can take specific actions on the JcatConnection object when it is in a specific state and specific events have been reported to the application.

In each state, the connection object can detect certain events, which can be reported to an application. As in the case of a JccConnection object, the same JcatConnection object may not be used in another call. The existence of a JcatConnection implies that its address is associated with its call in the manner described by the JcatConnection's state. In addition, this also implies that the JcatTerminalConnection is associated with the JcatCall object.

While a single FSM is specified for the JcatCall, the states traversed by a particular endpoint depends on the role of the endpoint --whether the endpoint originated the call or whether the endpoint is receiving a call. Based on this, we consider two types of connection objects, namely origintaing connection (O-Connection) and terminating connection (T-Connection) objects. An O-Connection object represents an association between a call object and an originating endpoint represented by a JcatAddress object. A T-Connection object represents an association between a call object and a terminating address object.

Connection object state transition diagram

The figure below illustrates the finite-state diagram for the JcatConnection object. The finite-states describe the allowable state transitions of an O-Connection or T-Connection object. The API must guarantee these state transitions.

Note that this state machine is a refinement of the JccConnection FSM. The CONNECTED state of JccConnection is divided into a CONNECTED state and a SUSPENDED state. Since the states defined in the JcatConnection interface provide more detail to the states defined in the JccConnection interface, each state in the JccConnection interface corresponds to a state defined in the JcatConnection interface. Conversely, each JcatConnection state corresponds to exactly one JccConnection state. This arrangement permits applications to view either the JccConnection state or the JcatConnection state and still see a consistent view.

JcatConnection FSM

Since:
1.0

Field Summary
static int SUSPENDED
          The SUSPENDED state implies that an JcatConnection object is suspended from the call, although its references to the call and address objects will still remain valid.
 
Fields inherited from interface javax.csapi.cc.jcc.JccConnection
ADDRESS_ANALYZE, ADDRESS_COLLECT, ALERTING, AUTHORIZE_CALL_ATTEMPT, CALL_DELIVERY, CONNECTED, DISCONNECTED, FAILED, IDLE
 
Method Summary
 java.util.Set getTerminalConnections()
          Returns a set of JcatTerminalConnection objects associated with this JcatConnection.
 JcatConnection park(java.lang.String destinationAddress)
          Parks a Connection at a destination telephone address.
 void reconnect()
          The application can use the reconnect method in the SUSPENDED state.
 void suspendConnection()
          This method suspends causes a transition to the SUSPENDED state.
 
Methods inherited from interface javax.csapi.cc.jcc.JccConnection
answer, attachMedia, continueProcessing, detachMedia, getAddress, getCall, getDestinationAddress, getLastAddress, getMidCallData, getOriginalAddress, getOriginatingAddress, getRedirectedAddress, getState, isBlocked, release, routeConnection, selectRoute
 

Field Detail

SUSPENDED

public static final int SUSPENDED
The SUSPENDED state implies that an JcatConnection object is suspended from the call, although its references to the call and address objects will still remain valid.

Entry criteria:

Function: The connections for the originating and terminating party are maintained and depending on the incoming network connection, appropriate backward signaling takes place.

According to the received indication the following applies:

In the following cases, the timer is started and the call waits for re-answer request from the terminating party: If re-answer request (e.g. off-hook, SS7 RESume message) is received from the terminating party before the timer expires, the originating and terminating parties are reconnected.

Exit criteria:

See Also:
Constant Field Values
Method Detail

getTerminalConnections

public java.util.Set getTerminalConnections()
Returns a set of JcatTerminalConnection objects associated with this JcatConnection. JcatTerminalConnection objects represent the relationship between a JcatConnection and a specific JcatTerminal endpoint. There may be zero JcatTerminalConnections associated with this JcatConnection. In that case, this method returns an empty set. JcatConnection objects lose their reference to a JcatTerminalConnection once the JcatTerminalConnection moves into the JcatTerminalConnection.DROPPED state.

Returns:
returns a set with JcatTerminalConnection objects

park

public JcatConnection park(java.lang.String destinationAddress)
                    throws InvalidPartyException,
                           InvalidStateException,
                           MethodNotSupportedException,
                           PrivilegeViolationException,
                           ResourceUnavailableException
Parks a Connection at a destination telephone address. This method is similar to the transfer feature, except the JcatConnection at the new destination Address is in the CALL_DELIVERY state or beyond. Parking a JcatConnection at a destination Address drops the JcatConnection from the JcatCall and creates and returns a new JcatConnection at the specified destination address.

The new destination telephone address string is given as an argument to this method and must be a valid and complete telephone address. The new JcatConnection must be in the CONNECTED state. If this method is successful, the old (this) JcatConnection moves to the DISCONNECTED state. All of its associated JcatTerminalConnections move to the DROPPED state.

Pre-Conditions:

  1. ((this.getCall()).getProvider()).getState() == JccProvider.IN_SERVICE
  2. this.getState() == JccConnection.CONNECTED
  3. destinationAddress must be a valid and complete telephone address.

Post-Conditions:

  1. Let newconnection be the new JccConnection created and returned
  2. ((this.getCall()).getProvider()).getState() == JccProvider.IN_SERVICE
  3. newconnection element of (this.getCall()).getConnections()
  4. newconnection.getState() == JcatConnection.SUSPENDED
  5. this.getState() == JccConnection.DISCONNECTED
  6. Let tc[] = this.getTerminalConnections() before this method is invoked
  7. tc[i].getState() == JcatTerminalConnection.DROPPED, for all i

Parameters:
destinationAddress - This parameter contains the destination telephone address at which to park a connection.
Returns:
The JcatConnection associated with the new incoming call.
Throws:
InvalidPartyException - - The specified destination address provided is not valid.
InvalidStateException - - .
MethodNotSupportedException - - This method is not supported by the implementation.
PrivilegeViolationException - - The application does not have the proper authority to invoke this method.
ResourceUnavailableException - - An internal resource necessary for the successful invocation of this method is not available.

reconnect

public void reconnect()
               throws InvalidArgumentException,
                      InvalidStateException,
                      MethodNotSupportedException,
                      PrivilegeViolationException,
                      ResourceUnavailableException
The application can use the reconnect method in the SUSPENDED state.

Pre-Conditions:

  1. ((this.getCall()).getProvider()).getState() == JccProvider.IN_SERVICE
  2. (this.getCall()).getState() == JccCall.ACTIVE
  3. this.getState() == JccConnection.SUSPENDED
  4. tc[0].getState == JcatTerminalConnection.HELD

Post-Conditions:

  1. ((this.getCall()).getProvider()).getState() == JccProvider.IN_SERVICE
  2. (this.getCall()).getState() == JccCall.ACTIVE
  3. this.getState() == JccConnection.CONNECTED
  4. tc[0].getState == JcatTerminalConnection.TALKING
  5. JcatTerminalConnectionEvent.TERMINALCONNECTION_TALKING is delivered for JcatTerminalConnection

Throws:
InvalidArgumentException - - The ReconnectParameters provided is not valid.
InvalidStateException - - Either the Provider was not "in service" or the Call was not "idle".
MethodNotSupportedException - - This method is not supported by the implementation.
PrivilegeViolationException - - The application does not have the proper authority to invoke this method.
ResourceUnavailableException - - An internal resource necessary for the successful invocation of this method is not available.

suspendConnection

public void suspendConnection()
                       throws InvalidStateException,
                              MethodNotSupportedException,
                              ResourceUnavailableException
This method suspends causes a transition to the SUSPENDED state.

Pre-Conditions:

  1. ((this.getCall()).getProvider()).getState() == JccProvider.IN_SERVICE
  2. (this.getCall()).getState() == JccCall.ACTIVE
  3. this.getState() == JccConnection.CONNECTED

Post-Conditions:

  1. ((this.getCall()).getProvider()).getState() == JccProvider.IN_SERVICE
  2. (this.getCall()).getState() == JccCall.ACTIVE
  3. this.getState() == JccConnection.SUSPENDED

Throws:
InvalidStateException - - Either the Provider is not "in service", the Call is not "active" or the Connection is not in the "select facility" state.
MethodNotSupportedException - - This method is not supported by the implementation.
ResourceUnavailableException - - An internal resource necessary for the successful invocation of this method is not available.

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