JCC
v1.0

jain.application.services.jcc
Interface JccConnection

All Superinterfaces:
JcpConnection

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

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.

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. An example of a valid API method is selectRoute(String) on being blocked at the ADDRESS_ANALYZE state. Specifically those methods which do have pre and post conditions (which are normally different) are the ones that cause the "unsuspension" of call processing. The "informational" methods like isBlocked(), getXXX(), etc. do not cause the resumption of call processing if it had been suspended.

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.

EventFilters
Listeners can be added with and without the use of EventFilters. Listeners added without filters are expected to receive events in the notification mode. Listeners added with filters will receive only those events which are not "discarded" by the EventFilter.
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.
 java.lang.String getDestinationAddress()
          Returns the address of the destination party.
 int getJccState()
          Retrieves the state of the JccConnection object.
 java.lang.String getLastAddress()
          Returns the last redirected address associated with this JccConnection.
 java.lang.String getMoreDialedDigits()
          This method is used by the application to instruct the platform to collect further address information (which may be in the form of digits or letters) and return this to the application.
 java.lang.String getOriginalAddress()
          Returns the original address associated with this JccConnection.
 JccAddress getOriginatingAddress()
          Returns the address of the originating party.
 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 address)
          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: This state might 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 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
  2. this.getCall().getState() == ACTIVE
Post-Conditions:
  1. this.getJccState() != IDLE or AUTHORIZE_CALL_ATTEMPT or DISCONNECTED
  2. this.getCall().getState() == ACTIVE
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 address)
                 throws MethodNotSupportedException,
                        InvalidStateException,
                        ResourceUnavailableException,
                        PrivilegeViolationException,
                        InvalidPartyException
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.

Pre-Conditions:

  1. this.getJccState() == ADDRESS_COLLECT OR ADDRESS_ANALYZE
  2. this.getCall().getState() == ACTIVE
Post-Conditions:
  1. this.getJccState() == CALL_DELIVERY
  2. this.getCall().getState() == ACTIVE
Parameters:
address - indicates the String representation of the translated addresses.
Throws:
MethodNotSupportedException - The implementation does not support this method.
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.
InvalidPartyException - The given Addresses are not valid.

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() != IDLE or 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 or IDLE or SUSPENDED
  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 address information (which may be in the form of digits or letters) and return this to the application. The platform is then expected to return only the additional information collected as a String. The extra information will not be added to the destinationAddress. The application might do this through calling connection.selectRoute(connection.getDestinationAddress() + connection.getMoreDialedDigits()).

Pre-conditions:

  1. ((this.getCall()).getProvider()).getState() == IN_SERVICE
  2. (this.getCall()).getState() == ACTIVE
  3. this.getState() == ADDRESS_COLLECT or ADDRESS_ANALYZE

Post-conditions:

  1. ((this.getCall()).getProvider()).getState() == IN_SERVICE
  2. (this.getCall()).getState() == ACTIVE
  3. this.getState() == ADDRESS_ANALYZE
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.

getLastAddress

public java.lang.String getLastAddress()
Returns the last redirected address associated with this JccConnection. The last redirected address is the address at which the current JccCall was placed immediately before the current address. This is common if a JccCall is forwarded to several addresses before being answered. If the last redirected address is unknown or not yet known, this method returns null.
Returns:
the address 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 java.lang.String getOriginalAddress()
Returns the original address associated with this JccConnection. This would be the first address to which the call was placed. The current address might be different from this due to multiple forwardings. If this address is unknown or not yet known, this method returns null.
Returns:
the address which was called initially.

getDestinationAddress

public java.lang.String getDestinationAddress()
Returns the address of the destination party. This method will return the address of the destination party when invoked upon an originating connection and only if the connections state (getJccState()) is either in ADDRESS_COLLECT, ADDRESS_ANALYZE, or CALL_DELIVERY. It will return null otherwise.
Returns:
the address of the destination party.

getOriginatingAddress

public JccAddress getOriginatingAddress()
Returns the address of the originating party. This method will return the address of the originating party when invoked upon an terminating connection. If there is no originating party the method will return null. If the method is invoked on an originating connection object, the method's return value will equal the return value of JcpConnection.getAddress().
Returns:
the address of the originating party (if any).

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