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. |
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. |
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.
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:
- this.getState() == JccConnection.IDLE or JccConnection.AUTHORISE_CALL_ATTEMPT
Post-Conditions:
- 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:
- this.getState() != JccConnection.IDLE or JccConnection.DISCONNECTED
- ((this.getCall()).getProvider()).getState() == JccProvider.IN_SERVICE
- (this.getCall()).getState() ==JccCall.ACTIVE
Post-conditions:
- this.getState() == JccConnection.DISCONNECTED
- ((this.getCall()).getProvider()).getState() == JccProvider.IN_SERVICE
- Connection_Disconnected event is delivered for to the registered
listeners.
- 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:
- this.getState() != JccConnection.CONNECTED or JccConnection.DISCONNECTED
or JccConnection.FAILED
- ((this.getCall()).getProvider()).getState() == JccProvider.IN_SERVICE
- (this.getCall()).getState() ==JccCall.ACTIVE
Post-conditions:
- this.getState() == JccConnection.CONNECTED
- ((this.getCall()).getProvider()).getState() == JccProvider.IN_SERVICE
- JccConnectionConnected event is delivered for to the registered
listeners.
- (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