JCC
v0.9.2

jain.application.services.jcc
Interface JccConnection


public interface JccConnection
extends JcpConnection

A JccConnection object represents a link between a network endpoint (JccAddress) and a JccCall object.

Jcp vs. Jcc Package States

There is a strong relationship between the JccConnection states and the JcpConnection states. If an implementation supports the JCC package, it must ensure this relationship is properly maintained.

JccConnection State Transitions

The JccConnection class defines a finite-state diagram which describes the allowable JccConnection state transitions. This finite-state diagram must be guaranteed by the implementation. Each method which causes a change in a JccConnection state must be consistent with this state diagram. This finite state diagram is below:

JccConnection FSM

Since the states defined in the JccConnection interface provide more detail to the states defined in the JcpConnection interface, each state in the JcpConnection interface corresponds to a state defined in the JccConnection interface. Conversely, each JccConnection state corresponds to exactly one JcpConnection state. This arrangement permits applications to view either the core state or the JCC state and still see a consistent view.

The following table outlines the relationship between the JCP package Connection states and the JCC package Connection states.

If the JCC package state is... then the JCP state must be...
AUTHORIZE_CALL_ATTEMPT JcpConnection.INPROGRESS
ADDRESS_COLLECT JcpConnection.INPROGRESS
ADDRESS_ANALYZE JcpConnection.INPROGRESS
CALL_DELIVERY JcpConnection.INPROGRESS
SUSPENDED JcpConnection.CONNECTED

Events--Blocking and non-Blocking

An event is generated corresponding to every state change in the finite state machine. (FSM). The states of the JccConnection FSM map in a one to one fashion with the states of the JcpConnection FSM except for the INPROGRESS and CONNECTED states of the JcpConnection FSM. These two states are divided into further substates in the JccConnection FSM. Hence, it is expected that when the JccConnection object transitions from IDLE to AUTHORIZE_CALL_ATTEMPT, then two events are generated in the JCC platform corresponding to the INPROGRESS event and the AUTHORIZE_CALL_ATTEMPT. Similar would be the case when entering the CONNECTED state in the JccConnection FSM. On the other hand proceeding from one refined state to another refined state such as from the AUTHORIZE_CALL_ATTEMPT to the ADDRESS_COLLECT state results in only the event corresponding to the ADDRESS_COLLECT being generated.

All the events on the JccConnection are expected to be blockable. In other words, after sending each event to the listener the implementation can either suspend processing or continue with processing. The implementation suspends processing if the event is to be fired in a blocking mode and the implementation continues with processing if the event is to be fired in a non-blocking mode. When the implementation suspends processing, only the traversal of the finite state machine by the corresponding JccConnection object is suspended. All external events received for the blocked JccConnection object would have to be queued and handled. Thus, the finite state machine state of the corresponding JccConnection object does not change when processing is suspended. In case of a blocking event, the implementation is expected to suspend processing either until the application uses a valid API method call or until a timeout occurs.

The listeners are expected to specify the mode in which they are to be notified of the events. Note that the events are sent out only when the state is reached. Hence, when processing is suspended the connection is in some state. The order of event delivery, whether all the notifications to be done before the blocking events are reported to the listener etc, is undefined.

Multiple Listeners
Multiple listeners can also be added for the same event. In case there are multiple listeners registered for an event and all of them request just the notification of an event without suspension of call processing the JCC implementation informs all the registered listeners. On the other hand if some listeners have registered for event notification and the other listeners have requested blocking, the platform informs all listeners about the event while keeping the call processing suspended(without changing any state). In such a case, if one of the registered listeners invokes a valid API method, then this specification offers no restrictions on call processing resumption/suspension. In other words in such a case, the result is highly dependent on the platform.


Field Summary
static int ADDRESS_ANALYZE
          Represents the connection ADDRESS_ANALYZE state.
static int ADDRESS_COLLECT
          Represents the connection ADDRESS_COLLECT state.
static int AUTHORIZE_CALL_ATTEMPT
          Represents the connection AUTHORIZE_CALL_ATTEMPT state.
static int CALL_DELIVERY
          Represents the connection CALL_DELIVERY state.
static int SUSPENDED
          Represents the SUSPENDED state.
 
Fields inherited from interface jain.application.services.jcp.JcpConnection
ALERTING, CONNECTED, DISCONNECTED, FAILED, IDLE, INPROGRESS, UNKNOWN
 
Method Summary
 void answer()
          This method causes the call to be answered.
 void attachMedia()
          This method will allow transmission on all associated bearer connections or media channels to and from other parties in the call.
 void continueProcessing()
          This method requests the platform to continue processing.
 void detachMedia()
          This method will detach the JccConnection from the call, i.e., this will prevent transmission on any associated bearer connections or media channels to and from other parties in the call.
 JccAddress getDestinationAddress()
          Returns the JcpAddress which is the address to which this call leg is going to be routed.
 int getJccState()
          Retrieves the state of the JccConnection object.
 JccAddress getLastAddr()
          Returns the last redirected JcpAddress associated with this JcpCall.
 java.lang.String getMoreDialedDigits()
          This method is used by the application to instruct the platform to collect further digits and return them to the application.
 JccAddress getOriginalAddress()
          Returns the original JcpAddress associated with this JcpCall.
 boolean isBlocked()
          Returns a boolean value indicating if the JccConnection is currently blocked due to a blocking event having been fired to a listener registered for that blocking event.
 void release()
          Drops a JccConnection from an active telephone call.
 void routeConnection(boolean attachmedia)
          Routes this JccConnection to the target address associated with this JccConnection object.
 void selectRoute(java.lang.String[] addresses)
          Replaces address information onto an existing JccConnection.
 
Methods inherited from interface jain.application.services.jcp.JcpConnection
getAddress, getCall, getState
 

Field Detail

AUTHORIZE_CALL_ATTEMPT

public static final int AUTHORIZE_CALL_ATTEMPT
Represents the connection AUTHORIZE_CALL_ATTEMPT state. This state implies that the originating or terminating terminal needs to be authorized for the call.

Entry criteria An indication that the originating or terminating terminal needs to be authorized for the call.
Functions: The originating or terminating terminal characteristics should be verified using the calling party's identity and service profile. The authority/ability of the party to place the call with given properties is verified. The types of authorization may vary for different types of originating and terminating resources.
Exit criteria: The JccConnection object exits this state on receiving indication of the success or failure of the authorization process. The originating JccConnection might move to the ADDRESS_COLLECT state while the terminating JccConnection has to move to the CALL_DELIVERY state or beyond. Thus, the terminating JccConnection cannot be either in the ADDRESS_COLLECT or the ADDRESS_ANALYZE states.


ADDRESS_COLLECT

public static final int ADDRESS_COLLECT
Represents the connection ADDRESS_COLLECT state.

Entry criteria The JccConnection object enters this state with the originating party having been authorized for this call.
Functions: In this state the initial information package is collected from the originating party. Information is examined according to dialing plan to determine the end of collection. No further action may be required if en bloc signaling method is in use.
Exit criteria: This state is exited either because the complete initial information package or dialing string has been collected from the originating party or because of failure to collect information or even due to reception of invalid information from the caller. Timeout and abandon indications may also cause the exit from this state.


ADDRESS_ANALYZE

public static final int ADDRESS_ANALYZE
Represents the connection ADDRESS_ANALYZE state.

Entry criteria This state is entered on the availability of complete initial information package/dialing string from the originating party.
Functions: The information collected is analyzed and/or translated according to a dialing plan to determine routing address and call type (e.g. local exchange call, transit exchange call, international exchange call).
Exit criteria: This state is exited on the availability of routing address. Invalid information and Abandon indications also cause transition out of this state. Exception criteria such as network busy, abandon, route busy etc. will cause exit from this state.


CALL_DELIVERY

public static final int CALL_DELIVERY
Represents the connection CALL_DELIVERY state.

Entry criteria: This state is entered on the originating side when the routing address and call type are available. On the terminating side this state is entered when the termination attempt to the address is authorized. Function: On the originating side this state involves selecting of the route as well as sending an indication of the desire to set up a call to the specified called party. On the terminating side this state is involves checking the busy/idle status of the terminating access and also informing the terminating message of an incoming call. Exit criteria: This state is exited on the originating side when criteria such as receipt of an alerting indication or call accepted is received from the terminating call portion. This state is exited on the terminating side when the terminating party is being alerted or the call is accepted.


SUSPENDED

public static final int SUSPENDED
Represents the SUSPENDED state. This state implies that this JccConnection object is suspended from the call, although it's references to a JccCall and JccAddress objects will stil remain valid.

Entry criteria: A suspend indication is received that the terminating party has disconnected, but disconnect timing has not completed. This state might also be entered on cases like the flash hook. Function: The connections for the originating and terminating party are maintained and depending on the incoming network connection, appropriate backward signaling takes place. Exit criteria: Exception criteria such as disconnect cause exit from this state.

Method Detail

getJccState

public int getJccState()
Retrieves the state of the JccConnection object.
Returns:
Integer representing the state of the call. See static int's defined in this object.

routeConnection

public void routeConnection(boolean attachmedia)
                     throws InvalidStateException,
                            ResourceUnavailableException,
                            PrivilegeViolationException,
                            MethodNotSupportedException,
                            InvalidPartyException,
                            InvalidArgumentException
Routes this JccConnection to the target address associated with this JccConnection object.

Pre-Conditions:

  1. this.getJccState() == IDLE or AUTHORIZE_CALL_ATTEMPT
Post-Conditions:
  1. this.getJccState() != IDLE or AUTHORIZE_CALL_ATTEMPT

Parameters:
attachmedia - indicates if the media has to be attached after the connection is routed. TRUE causes the media to be attached, FALSE causes the media not to be attached in which case a separate call to attachMedia() must be made in order to attach the media to this connection.
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 for completing this call is unavailable.
PrivilegeViolationException - The application does not have the proper authority to call this method.
MethodNotSupportedException - The implementation does not support this method.
InvalidPartyException - The given Addresses are not valid.
InvalidArgumentException - The provided argument is not valid.

selectRoute

public void selectRoute(java.lang.String[] addresses)
                 throws MethodNotSupportedException
Replaces address information onto an existing JccConnection. The address replaced on a connection is what is normally thought of as the destination address. Note that the address (and hence JccAddress) associated with this JccConnection itself is not changed. This method is used when a telephone address string has been dialed and address translation is needed in order to place the telephone call. The translated addressing information is provided as the argument to this method. This method takes an array of string destination telephone address names, in priority order. The highest priority destination is the first element in the given array, and routing is attempted with this destination first. Successive given destination addresses are attempted until one is found which does not fail.

Pre-Conditions:

  1. this.getJccState() == ADDRESS_ANALYZE
  2. this.getCall().getState() == ACTIVE
Post-Conditions:
  1. this.getJccState() == CALL_DELIVERY
  2. this.getCall().getState() == ACTIVE

Parameters:
addresses - indicates the String array of translated addresses.
Throws:
MethodNotSupportedException - The implementation does not support this method.

release

public void release()
             throws PrivilegeViolationException,
                    ResourceUnavailableException,
                    InvalidStateException
Drops a JccConnection from an active telephone call. If successful, the associated JccAddress will be released from the call and the JccConnection moves to the JcpConnection.DISCONNECTED state following which it may be deleted. The JccConnection's JccAddress is no longer associated with the telephone call. This method does not necessarily drop the entire telephone call, only the particular JccConnection on the telephone call. This method provides the ability to disconnect a specific party from a telephone call, which is especially useful in telephone calls consisting of three or more parties. Invoking this method may result in the entire telephone call being dropped, which is a permitted outcome of this method. In that case, the appropriate events are delivered to the application, indicating that more than just a single JccConnection has been dropped from the telephone call. As a result of this method returning successfully, a JcpConnectionEvent.CONNECTION_DISCONNECTED event for this JccConnection is delivered to the registered listeners.
Dropping Additional Connections
Additional JccConnections may be dropped indirectly as a result of this method. For example, dropping the destination JccConnection of a two-party call may result in the entire telephone call being dropped. It is up to the implementation to determine which JccConnections are dropped as a result of this method. Implementations should not, however, drop additional JccConnections representing additional parties if it does not reflect the natural response of the underlying telephone hardware.

Pre-conditions:

  1. this.getState() != DISCONNECTED
  2. ((this.getCall()).getProvider()).getState() == IN_SERVICE
  3. (this.getCall()).getState() == ACTIVE

Post-conditions:

  1. this.getState() == DISCONNECTED
  2. ((this.getCall()).getProvider()).getState() == IN_SERVICE
  3. CONNECTION_DISCONNECTED event is delivered for to the registered listeners.
  4. CALL_INVALID event is also delivered if all the JccConnections are dropped indirectly as a result of this method.
Throws:
InvalidStateException - If either of the JccConnection, JccCall or JccProvider objects is not in the proper states as given by this method's precondition.
PrivilegeViolationException - The application does not have the authority or permission to disconnect the JccConnection. For example, the JccAddress associated with this JccConnection may not be controllable in the JccProvider's domain.
ResourceUnavailableException - An internal resource to drop the connection is not available.

answer

public void answer()
            throws PrivilegeViolationException,
                   ResourceUnavailableException,
                   InvalidStateException
This method causes the call to be answered.

Pre-conditions:

  1. this.getState() != CONNECTED or DISCONNECTED or FAILED
  2. ((this.getCall()).getProvider()).getState() == IN_SERVICE
  3. (this.getCall()).getState() == ACTIVE

Post-conditions:

  1. this.getState() == CONNECTED
  2. ((this.getCall()).getProvider()).getState() == IN_SERVICE
  3. CONNECTION_CONNECTED event is delivered for to the registered listeners.
  4. (this.getCall()).getState() == ACTIVE
Throws:
PrivilegeViolationException - This could include trying to answer an outgoing call leg in a case where it is leaving the domain of the local call control platform.
ResourceUnavailableException - An internal resource to answer the connection is not available.
InvalidStateException - If either of the JccConnection, JccCall or JccProvider objects is not in the proper states as given by this method's precondition.

continueProcessing

public void continueProcessing()
                        throws PrivilegeViolationException,
                               ResourceUnavailableException,
                               InvalidStateException
This method requests the platform to continue processing. The call processing has been suspended due to the firing of a blocking event (trigger) and this method causes the processing to continue.

Pre-conditions:

  1. this.isBlocked() == true
  2. this.getState() != CONNECTED or DISCONNECTED or FAILED
  3. ((this.getCall()).getProvider()).getState() == IN_SERVICE
  4. (this.getCall()).getState() == ACTIVE

Post-conditions:

  1. ((this.getCall()).getProvider()).getState() == IN_SERVICE
  2. (this.getCall()).getState() == ACTIVE
Throws:
PrivilegeViolationException - The application does not have the authority or permission to invoke this methods.
ResourceUnavailableException - An internal resource is not available.
InvalidStateException - If either of the JccConnection, JccCall or JccProvider objects is not in the proper states as given by this method's precondition.

attachMedia

public void attachMedia()
                 throws PrivilegeViolationException,
                        ResourceUnavailableException,
                        InvalidStateException
This method will allow transmission on all associated bearer connections or media channels to and from other parties in the call. The JccConnection object must be in the JcpConnection.CONNECTED state for this method to complete successfully.

Pre-conditions:

  1. this.getState() == CONNECTED
  2. ((this.getCall()).getProvider()).getState() == IN_SERVICE
  3. (this.getCall()).getState()} == ACTIVE

Post-conditions:

  1. this.getState() == CONNECTED
  2. ((this.getCall()).getProvider()).getState() == IN_SERVICE
  3. (this.getCall()).getState() == ACTIVE
Throws:
PrivilegeViolationException - The application does not have the authority or permission to invoke this methods.
ResourceUnavailableException - An internal resource is not available.
InvalidStateException - If either of the JccConnection, JccCall or JccProvider objects is not in the proper states as given by this method's precondition.

detachMedia

public void detachMedia()
                 throws PrivilegeViolationException,
                        ResourceUnavailableException,
                        InvalidStateException
This method will detach the JccConnection from the call, i.e., this will prevent transmission on any associated bearer connections or media channels to and from other parties in the call. The JccConnection object must be in the JcpConnection.CONNECTED state for this method to complete successfully.

Pre-conditions:

  1. this.getState() == CONNECTED
  2. ((this.getCall()).getProvider()).getState() == IN_SERVICE
  3. (this.getCall()).getState()} == ACTIVE

Post-conditions:

  1. this.getState() == CONNECTED
  2. ((this.getCall()).getProvider()).getState() == IN_SERVICE
  3. (this.getCall()).getState() == ACTIVE
Throws:
PrivilegeViolationException - The application does not have the authority or permission to invoke this methods.
ResourceUnavailableException - An internal resource is not available.
InvalidStateException - If either of the JccConnection, JccCall or JccProvider objects is not in the proper states as given by this method's precondition.

isBlocked

public boolean isBlocked()
Returns a boolean value indicating if the JccConnection is currently blocked due to a blocking event having been fired to a listener registered for that blocking event. The method returns false once a valid API call is made after the firing of a blocking event or until after the expiry of a timeout.
Returns:
boolean indicating if the connection is blocked due to a blocking event.

getMoreDialedDigits

public java.lang.String getMoreDialedDigits()
                                     throws PrivilegeViolationException,
                                            ResourceUnavailableException,
                                            InvalidStateException
This method is used by the application to instruct the platform to collect further digits and return them to the application. The platform is then expected to return the collected digits as a String.

Pre-conditions:

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

Post-conditions:

  1. ((this.getCall()).getProvider()).getState() == IN_SERVICE
  2. (this.getCall()).getState() == ACTIVE
Returns:
String representing the collected digits
Throws:
PrivilegeViolationException - The application does not have the authority or permission to invoke this methods.
ResourceUnavailableException - An internal resource is not available.
InvalidStateException - If either of the JccConnection, JccCall or JccProvider objects is not in the proper states as given by this method's precondition.

getLastAddr

public JccAddress getLastAddr()
Returns the last redirected JcpAddress associated with this JcpCall. The last redirected JcpAddress is the JcpAddress at which the current JcpCall was placed immediately before the current JcpAddress. This is common if a JcpCall is forwarded to several JcpAddresses before being answered. If the last redirected address is unknown or not yet known, this method returns null.
Returns:
the JcpAddress to which the call was last associated and redirection on which caused the current Address to be associated with the call through the connection.

getOriginalAddress

public JccAddress getOriginalAddress()
Returns the original JcpAddress associated with this JcpCall. This would be the first JcpAddress to which the call was placed. The current JcpAddress might be different from this due to multiple forwardings. If this JcpAddress is unknown or not yet known, this method returns null.
Returns:
the JcpAddress which was called initially.

getDestinationAddress

public JccAddress getDestinationAddress()
Returns the JcpAddress which is the address to which this call leg is going to be routed.
Returns:
the destination JcpAddress.

JCC
v0.9.2

29 Oct 2000
If you have any comments or queries, please mail them to jcc@research.telcordia.com


Copyright-2000 Sun Microsystems