jain.jcc
Interface JccConnection


public interface JccConnection
extends JcpConnection

A JccConnection object represents a link between a network endpoint (address) 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:

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...
JccConnection.IDLE JcpConnection.IDLE
JccConnection.AUTHORIZE_CALL_ATTEMPT JcpConnection.INPROGRESS
JccConnection.ADDRESS_COLLECT JcpConnection.INPROGRESS
JccConnection.ADDRESS_ADDRESS_ANALYZE JcpConnection.INPROGRESS
JccConnection.CALL_DELIVERY JcpConnection.INPROGRESS
JccConnection.ALERTING JcpConnection.ALERTING
JccConnection.CONNECTED JcpConnection.CONNECTED
JccConnection.SUSPENDED JcpConnection.CONNECTED
JccConnection.DISCONNECTED JcpConnection.DISCONNECTED
JccConnection.FAILED JcpConnection.FAILED
JccConnection.UNKNOWN JcpConnection.UNKNOWN

Events--Blocking and non-Blocking

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


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 SUSPEND state.
 
Fields inherited from interface jain.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.
 JcpAddress 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.
 JcpAddress 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.
 JcpAddress 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 specified target address.
 
Methods inherited from interface jain.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 SUSPEND 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 specified target address.

Pre-Conditions:
  1. this.getState() == JccConnection.IDLE or JccConnection.AUTHORISE_CALL_ATTEMPT
Post-Conditions:
  1. this.getJccState() != IDLE OR AUTHORISE_CALL_ATTEMPT
Note that this JccConnection may have progressed beyond the ADDRESS_COLLECTED state.

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.

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 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 JccConnectionDisconnected 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() != JccConnection.IDLE or JccConnection.DISCONNECTED
  2. ((this.getCall()).getProvider()).getState() == JccProvider.IN_SERVICE
  3. (this.getCall()).getState() ==JccCall.ACTIVE

Post-conditions:

  1. this.getState() == JccConnection.DISCONNECTED
  2. ((this.getCall()).getProvider()).getState() == JccProvider.IN_SERVICE
  3. Connection_Disconnected event is delivered for to the registered listeners.
  4. CallInvalid 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 a connection is not available.

answer

public void answer()
This method causes the call to be answered.

Pre-conditions:

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

Post-conditions:

  1. this.getState() == JccConnection.CONNECTED
  2. ((this.getCall()).getProvider()).getState() == JccProvider.IN_SERVICE
  3. JccConnectionConnected event is delivered for to the registered listeners.
  4. (this.getCall()).getState() ==JccCall.ACTIVE

continueProcessing

public void continueProcessing()
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.

attachMedia

public void attachMedia()
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 CONNECTED state for this method to complete successfully.

detachMedia

public 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. The JccConnection object must be in the CONNECTED state for this method to complete successfully.

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()
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.
Returns:
String representing the collected digits

getLastAddr

public JcpAddress 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 JcpAddress 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 JcpAddress getDestinationAddress()
Returns the JcpAddress which is the address to which this call leg is going to be routed.
Returns:
the destination JcpAddress.


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


Copyright-2000 Sun Microsystems