|
JCAT v0.3.1 |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
The purpose of a JccConnection object is to describe
the relationship between a JccCall
object and a JccAddress
object.
A JccConnection object exists if the JccAddress is a part of the telephone call.
Each JccConnection has a state which describes the particular stage
of the relationship between the JccCall and JccAddress. These states and their
meanings are described below. Applications use the
getCall()
and getAddress()
methods to obtain the JccCall and JccAddress associated with this JccConnection,
respectively.
From one perspective, an application may view a JccCall only in terms of the JccAddress/JccConnection objects which are part of the JccCall. This is termed a logical view of the Call. In this logical view, a telephone call is viewed as two or more endpoint addresses in communication. The JccConnection object describes the state of each of these endpoint addresses with respect to the JccCall.
Although a JccConnection's
JccAddress and JccCall references remain valid throughout the lifetime of the
JccConnection object, the same is not true for the JccCall and JccAddress object's
references to this JccConnection.
Particularly, when a JccConnection moves into
the DISCONNECTED
state, it is no longer listed by the
JccCall.getConnections()
method.
Typically, when a JccConnection moves into the
DISCONNECTED
state, the application loses its
references to it to facilitate its garbage collection.
IDLE |
This state is the initial state for all new Connections. Connections
which are in the IDLE state are not actively
part of a telephone call, yet their references to the Call and Address
objects are valid. Connections typically do not stay in the
IDLE state for long, quickly transitioning to
other states. |
DISCONNECTED | This state implies it is no longer part of the telephone call, although its references to Call and Address still remain valid. A Connection in this state is interpreted as once previously belonging to this telephone call. |
AUTHORIZE_CALL_ATTEMPT |
This state implies that the originating or terminating terminal needs to be authorized for the call. |
ADDRESS_COLLECT |
This state implies that more information needs to be collected for the call. |
ADDRESS_ANALYZE |
This state implies that the address needs to be analyzed to determine the resources needed. |
CALL_DELIVERY |
This state implies that the resources (such as network links) needed to deliver signaling messages are being used. |
ALERTING |
This state implies that the Address is being notified of an incoming call. |
CONNECTED | This state
implies that a Connection and its Address is actively part of a
telephone call. In common terms, two people talking to one another are
represented by two Connections in the CONNECTED
state. |
FAILED | This state indicates that a Connection to that
end of the call has failed for some reason. One reason why a Connection
would be in the FAILED state is because the
party was busy. Connections that are in the FAILED state are still connected to the call.
|
JccCallListener
interface on the JccCall object associated with
this JccConnection.
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
(table 2 contains a column that lists the methods
that implicitly resume processing). An example of a valid API method that implicitly
resumes processing is release(int)
. Typically, the
"informational" methods like isBlocked()
, getAddress()
,
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.
Field Summary | |
static int |
ADDRESS_ANALYZE
Represents the connection ADDRESS_ANALYZE state. |
static int |
ADDRESS_COLLECT
Represents the connection ADDRESS_COLLECT state. |
static int |
ALERTING
The JccConnection.ALERTING state implies that the Address is
being notified of an incoming call. |
static int |
AUTHORIZE_CALL_ATTEMPT
Represents the connection AUTHORIZE_CALL_ATTEMPT state. |
static int |
CALL_DELIVERY
Represents the connection CALL_DELIVERY state. |
static int |
CONNECTED
The JccConnection.CONNECTED state implies that
originating and terminating connection objects and the associated
Address objects are actively part of a call. |
static int |
DISCONNECTED
The JccConnection.DISCONNECTED state implies it is no
longer part of the telephone call, although its references to Call and
Address still remain valid. |
static int |
FAILED
The JccConnection.FAILED state indicates that a Connection
to that end of the call has failed for some reason. |
static int |
IDLE
The JccConnection.IDLE state is the initial state for all
new JccConnection objects. |
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 |
getAddress()
Returns the JccAddress associated with this JccConnection. |
JccCall |
getCall()
Retrieves the Jcccall that is associated with this JccConnection. |
java.lang.String |
getDestinationAddress()
Returns the address of the destination party. |
java.lang.String |
getLastAddress()
Returns the last redirected address associated with this JccConnection. |
MidCallData |
getMidCallData()
This methods gives access to service code type and service code value. |
java.lang.String |
getOriginalAddress()
Returns the original address associated with this JccConnection. |
JccAddress |
getOriginatingAddress()
Returns the address of the originating party. |
java.lang.String |
getRedirectedAddress()
Returns the redirected address. |
int |
getState()
Retrieves the state of the JccConnection object. |
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(int causeCode)
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. |
Field Detail |
public static final int AUTHORIZE_CALL_ATTEMPT
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.
public static final int ADDRESS_COLLECT
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.
public static final int ADDRESS_ANALYZE
The entry criteria have changed since JCC 1.0a
Entry criteria This state is
entered on the availability of complete or partial initial information package/dialing
string from the originating party.
The request (with JccProvider.createEventFilterMinimunCollectedAddressLength(int,int,int)
)
to collect a variable number of address digits and report them to the application (through
JccConnectionListener.connectionAddressAnalyze(JccConnectionEvent)
)) is handled within
this state. The collection of more digits as requested and the reporting of received digits to
the application (when the digit collect criteria are met) is done in this state. This action is
recursive, e.g. the application could ask for 3 digits to be collected and when reported, requests
can be done repeatedly, e.g. the application may for example request first for 3 digits to be
collected and when reported request further digits.
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 abandon, etc. will cause exit from this state.
public static final int CALL_DELIVERY
Entry criteria:
public static final int DISCONNECTED
JccConnection.DISCONNECTED
state implies it is no
longer part of the telephone call, although its references to Call and
Address still remain valid.
Entry criteria: This state
is entered when a disconnect indication is received from the
corresponding party or the application.
Function: The (bearer) connection to the party
is disconnected and depending on the incoming network connection, appropriate
backward signaling takes place.
Exit criteria:
public static final int IDLE
JccConnection.IDLE
state is the initial state for all
new JccConnection objects.
A JccConnection object in the
IDLE state while not yet actively participating in a call can
still reference a JccCall and JccAddress object.
Entry criteria Start of a new call.
Functions: Interface (line/trunk) is idled.
Exit criteria: An indication of the desire to place an outgoing
call or when the indication of an incoming call is received.
public static final int ALERTING
JccConnection.ALERTING
state implies that the Address is
being notified of an incoming call.
Entry criteria: This state
is entered when the terminating party is being alerted of an incoming
call.
Function: An indication is sent to the originating party that the terminating
party is being alerted.
Exit criteria: This state is exited when the call is accepted
and answered by the terminating party. Exception criteria such as
callrejected, NoAnswer and Abandon if possible all cause exit
from this state.
public static final int CONNECTED
JccConnection.CONNECTED
state implies that
originating and terminating connection objects and the associated
Address objects are actively part of a call. Entry criteria:
public static final int FAILED
JccConnection.FAILED
state indicates that a Connection
to that end of the call has failed for some reason.
One
reason why a JccConnection would be in the FAILED state is due to the
fact that the party was busy. Connections that are in the FAILED
state are still connected to the call.
Entry criteria: This state is entered when an exception condition
is encountered.
Function: Default handling of the exception condition is provided.
Exit criteria: Default handling of the exception condition by
the implementation is completed.
Method Detail |
public void selectRoute(java.lang.String address) throws MethodNotSupportedException, InvalidStateException, ResourceUnavailableException, PrivilegeViolationException, InvalidPartyException
Pre-Conditions:
address
- indicates the String representation of the translated addresses.
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.public void release(int causeCode) throws PrivilegeViolationException, ResourceUnavailableException, InvalidStateException, InvalidArgumentException
DISCONNECTED
state following which it may be deleted.
Valid cause codes (prefixed by CAUSE_
) for the integer that is
named causeCode are defined in JccEvent
and JccCallEvent
.
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 JccConnectionEvent.CONNECTION_DISCONNECTED
event for
this JccConnection is delivered to the registered listeners.
Pre-conditions:
Post-conditions:
causeCode
- an integer that represents a cause code. Valid values
are defined in JccEvent
and JccCallEvent
, they are typically prefixed
by CAUSE_
.
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.
InvalidArgumentException
- The given release cause code is invalid.public void answer() throws PrivilegeViolationException, ResourceUnavailableException, InvalidStateException, MethodNotSupportedException
This method can only be invoked on a terminating connection object.
Pre-conditions:
Post-conditions:
MethodNotSupportedException
- The implementation does not support this method.
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.public void continueProcessing() throws PrivilegeViolationException, ResourceUnavailableException, InvalidStateException
Pre-conditions:
Post-conditions:
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.public void attachMedia() throws PrivilegeViolationException, ResourceUnavailableException, InvalidStateException
CONNECTED
state for this method to complete successfully.
Pre-conditions:
Post-conditions:
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.public void detachMedia() throws PrivilegeViolationException, ResourceUnavailableException, InvalidStateException
CONNECTED
state
for this method to complete successfully.
Pre-conditions:
Post-conditions:
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.public boolean isBlocked()
public java.lang.String getLastAddress()
public java.lang.String getOriginalAddress()
public java.lang.String getDestinationAddress()
getState()
) is
either in ADDRESS_COLLECT
, ADDRESS_ANALYZE
, or CALL_DELIVERY
.
It will return null otherwise.
public JccAddress getOriginatingAddress()
getAddress()
.
public java.lang.String getRedirectedAddress()
CONNECTION_DISCONNECTED
with cause code CAUSE_REDIRECTED
occured and the connection returned by
JccConnectionEvent.getConnection()
is this
and it is a
terminating connection, this method will return the address of the party to
which this connection is redirected. In all other cases this method returns
null
.
null
if
the call is not redirected.public void routeConnection(boolean attachmedia) throws InvalidStateException, ResourceUnavailableException, PrivilegeViolationException, MethodNotSupportedException, InvalidPartyException, InvalidArgumentException
Pre-Conditions:
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.
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.public MidCallData getMidCallData() throws InvalidStateException, ResourceUnavailableException, MethodNotSupportedException
JccConnectionEvent.CONNECTION_MID_CALL
occured.
Pre-Conditions:
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, e.g. no mid call data is available at this time.
MethodNotSupportedException
- The implementation does not support this method.public int getState()
public JccCall getCall()
public JccAddress getAddress()
|
JCAT v0.3.1 |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright - 2001, 2003 Sun Microsystems