|
JCAT v0.3.1 |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
A JccCall is a transient association of (zero or more) addresses for the
purposes of engaging in a real-time communications interchange. The call
and its associated connection and address objects describe the control
and media flows taking place in some underlying "real world" communication
network. Other parties involved in the call may also exert control over it,
thus the membership and state of the endpoints may change without
explicit request by the Jcc application. The JccProvider
adjusts the call,
address and connection objects to reflect the results of these
combined command actions.
JccConnection
s.
A two-party call has two JccConnections, and a conference call
has three or more JccConnections. Each JccConnection models the relationship
between a JccCall and an JccAddress, where an JccAddress identifies a particular
party or set of parties on a call.
JccProvider.createCall()
method, which returns a JccCall object that
has zero Connections and is in the IDLE
state. The JccCall
maintains a reference to its JccProvider for the life of that JccCall object.
The JccProvider object instance does not change throughout the lifetime of
the JccCall object. The JccProvider associated with a JccCall is obtained via the
getProvider()
method.
getState()
method. This state describes the current
progress of a telephone call, where is it in its life cycle, and how many
connections exist on the call. The JccCall state may be one of three values:
IDLE
, ACTIVE
, or
INVALID
. The following is a description of each state:
IDLE |
This is the initial state for all calls. In this state, the JccCall has zero
connections, that is getConnections() must
return null.
|
ACTIVE |
A call with some current ongoing activity is in this state. JccCalls with one
or more associated JccConnections must be in this state. If a JccCall is in this
state, the getConnections() method must return an array
of size at least one.
|
INVALID |
This is the final state for all calls. JccCall objects which lose all of their
JccConnection objects (via a transition of the JccConnection object into the
JccConnection.DISCONNECTED state) moves into this state. Calls
in this state have zero JccConnections and these JccCall objects may not be used
for any future action. In this state, the
getConnections()
must return null.
|
getConnections()
method. A JccCall retains a reference to a
JccConnection only if it is not in the JccConnection.DISCONNECTED
state. Therefore, if a JccCall has a reference to a JccConnection, then that
JccConnection must not be in the JccConnection.DISCONNECTED
state.
When a JccConnection moves into the JccConnection.DISCONNECTED
state
(e.g. when a party hangs up), the JccCall loses its reference to that
JccConnection which is no longer reported via the
JccCall.getConnections()
method.
JccCallListener
or JccConnectionListener
interface reports all events pertaining to
the JccCall object. Events delivered to this interface must implement or extend the
JccCallEvent
interface. Applications can add listeners to a JccCall
object
via the addCallListener(JccCallListener)
method.
Connection-related events can be reported
via the
JccConnectionListener
interface.
These events include the
creation of these objects and their state changes. Events which are
reported
via the JccConnectionListener
interface pertaining to JccConnections or JccCalls
extend the JccConnectionEvent
interface.
JccCallEvent.CALL_EVENT_TRANSMISSION_ENDED
is delivered to
an object registered as a JccCallListener
(or an extension of that interface).
This is the final event received by the Listener from the call.
Field Summary | |
static int |
ACTIVE
JccCall.ACTIVE state indicates the Call has one or more Connections none of which is in the JccConnection.DISCONNECTED state. |
static int |
IDLE
JccCall.IDLE state indicates the Call has zero Connections. |
static int |
INVALID
The JccCall.INVALID state indicates that the Call has lost all of its connections, that is, all of its Connection objects have moved into the JccConnection.DISCONNECTED
state and are no longer associated with the Call. |
Method Summary | |
void |
addCallListener(JccCallListener calllistener)
Add a listener to this call. |
void |
addConnectionListener(JccConnectionListener cl,
EventFilter filter)
Add a connection listener to all connections under this call. |
JccConnection[] |
connect(JccAddress origaddr,
java.lang.String dialedDigits)
Places a call from an originating address to a destination address string. |
JccConnection |
createConnection(java.lang.String targetAddress,
java.lang.String originatingAddress,
java.lang.String originalCalledAddress,
java.lang.String redirectingAddress)
Creates a new JccConnection and attaches it to this JccCall. |
JccConnection[] |
getConnections()
Retrieves an array of connections asssociated with this call. |
JccProvider |
getProvider()
Retrieves the provider handling this call object. |
int |
getState()
Retrieves the state of the call. |
void |
release(int causeCode)
This method requests the release of the call object and associated connection objects. |
void |
removeCallListener(JccCallListener calllistener)
Removes a listener from this call. |
void |
removeConnectionListener(JccConnectionListener cl)
Removes the connection listener from all connections under this call. |
JccConnection |
routeCall(java.lang.String targetAddress,
java.lang.String originatingAddress,
java.lang.String originalDestinationAddress,
java.lang.String redirectingAddress)
This method requests routing of a call to the targetAddress given as an input parameter. |
void |
superviseCall(JccCallListener calllistener,
double time,
int treatment)
The application calls this method to supervise a call. |
Field Detail |
public static final int IDLE
public static final int ACTIVE
JccConnection.DISCONNECTED
state. The
Call object transitions into this state from the IDLE
state only.
public static final int INVALID
JccConnection.DISCONNECTED
state and are no longer associated with the Call.
A Call in this state cannot
be used for future actions.
Method Detail |
public void addConnectionListener(JccConnectionListener cl, EventFilter filter) throws ResourceUnavailableException, MethodNotSupportedException
Registering a single listener twice will result in the last filter being used for the purposes of consultation to determine the events that the application is interested in. Note that registering for the same event multiple times should not result in multiple notifications being sent to an application for the same event.
Post-Conditions:
cl
- JccConnectionListener object that receives the specified events.filter
- EventFilter determines if the event is to be
delivered to the specified listener.
MethodNotSupportedException
- The listener cannot be added at this time.
ResourceUnavailableException
- The resource limit for the number of
listeners has been exceeded.
public void removeConnectionListener(JccConnectionListener cl)
cl
- JccConnectionListener object that was registered using a corresponding
addConnectionListener method.public void release(int causeCode) throws PrivilegeViolationException, ResourceUnavailableException, InvalidStateException, InvalidArgumentException
JccConnection.release(int)
method on each JccConnection which is part of the Call. Typically each JccConnection
associated with this call will move into the JccConnection.DISCONNECTED
state.
The call will also be terminated in the network. If the application
has registered as a listener then it receives the JccCallEvent.CALL_EVENT_TRANSMISSION_ENDED
event.
Valid cause codes (prefixed by CAUSE_
) for the integer that is
named causeCode are defined in JccEvent
and JccCallEvent
.
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_
.
PrivilegeViolationException
- The application does not have
the authority or permission to disconnect the Call. For example,
an Address associated with this Call may not be controllable
in the Provider's domain.
ResourceUnavailableException
- An internal resource required
to drop a connection is not available.
InvalidStateException
- Some object required for the
successful invocation of this method is not in the proper state as
given by this method's pre-conditions.
InvalidArgumentException
- The given release cause code is invalid.public void superviseCall(JccCallListener calllistener, double time, int treatment) throws MethodNotSupportedException
routeCall(String,String,String,String)
, the timer measurement
will start as soon as the call is answered by the called party. A call supervision
event is also sent if the call is terminated before the supervision event occurs.
The call supervision events are then reported to the listener registered using this method. The events related to call supervision are reported only to the listeners registered using this method.
Note that a policy object may be designed to define the policy to be implemented by the platform as a result of this method instead of defining the policy through the given parameters. This might be designed in the future specifications.
calllistener
- JccCallListener object that receives the specified events.time
- specifies the granted time in milliseconds for the connection. When specified
as 0, volume based supervision is applied. Either bytes(volume) or time should be specified.treatment
- defines the treatment of the call by the call control service when
the call supervision timer expires. The values which may be combined using a logical
OR function are:
0x01
to release the call when the call supervision timer expires.0x02
to notify the application when the call supervision timer expires. 0x04
to send a warning tone to the controlling party when a call supervision timer
expires. If call release is requested, then the call will be released following the
tone after an administered time period.
MethodNotSupportedException
- if the implementation does not support this
method.public JccConnection[] connect(JccAddress origaddr, java.lang.String dialedDigits) throws ResourceUnavailableException, PrivilegeViolationException, InvalidPartyException, InvalidStateException, MethodNotSupportedException
The Call must be in the IDLE
state (and therefore have no
existing associated JccConnections and the Provider must be in the
JccProvider.IN_SERVICE
state. The successful effect of this method
is to place the call and create and return two JccConnections associated with
this Call.
ACTIVE
state and exactly two JccConnections will be
created and returned. The JccConnection associated with the originating endpoint is
the first JccConnection in the returned array. This JccConnection will execute the
originating JccConnection's Final State Diagram (see
table 3). The JccConnection associated
with the destination endpoint is the second JccConnection in the returned array and
will execute the terminating JccConnection's Final State Diagram. These
two JccConnections must at least be in the JccConnection.IDLE
state. That is, if one of
the Connections progresses beyond the IDLE state while this method is completing, this
Connection may be in a state other than the IDLE. This state must be reflected by an
event sent to the application.
Pre-Conditions:
origaddr
- The originating Address for this call.dialedDigits
- The destination address string for this call.
ResourceUnavailableException
- An internal resource necessary for placing
the call is unavailable.
PrivilegeViolationException
- The application does not have the proper
authority to place a call.
InvalidPartyException
- Either the originator or the destination does not
represent a valid party required to place a call.
InvalidStateException
- Some object required by this method is not in a valid
state as designated by the pre-conditions for this method.
MethodNotSupportedException
- The implementation does not support this method.public JccConnection createConnection(java.lang.String targetAddress, java.lang.String originatingAddress, java.lang.String originalCalledAddress, java.lang.String redirectingAddress) throws InvalidStateException, ResourceUnavailableException, PrivilegeViolationException, MethodNotSupportedException, InvalidArgumentException, InvalidPartyException
JccConnection.routeConnection(boolean)
.
createConnection("C","A","B","B")
will be applied in case the number of party "B" is translated into
the number of party "C", while party "A" dialed party "B". createConnection("C","A","B",null)
results in the
same behavior. Note that the connection with address "B" is automatically moved to
DISCONNECTED
with cause code
CAUSE_REDIRECTED
after the connection to "C" is routed.
A reference to the created connection i.e "C"'s connection will be returned.
A getAddress() method invocation on the returned JccConnection reference object
results in the JccAddress corresponding to party "C" being returned.
Party "C" will have to be routed to in this case.
createConnection("C","A","B","D")
will be applied in case the number of party "D" is translated into
the number of party "C", while party "A" dialed party "B".
A reference to the created connection i.e "C"'s connection will be returned.
A getAddress() method invocation on the returned JccConnection reference object
results in the JccAddress corresponding to party "C" being returned.
Party "C" will have to be routed to in this case. Note that the connection with address "B" is automatically moved to
DISCONNECTED
with cause code
CAUSE_REDIRECTED
after the connection to "C" is routed.
Pre-conditions:
Post-conditions:
targetAddress
- specifies the address to which the call
should be routed.originatingAddress
- specifies the address of the originating (calling)
party for this leg of the call. This is optional and can be set to null.originalCalledAddress
- specifies the initial destination address to which
this leg of the call was initiated. This is optional and can be set to null.redirectingAddress
- specifies the last address from which this leg of the call
was redirected. This is optional and can be set to null.
InvalidArgumentException
- An InvalidArgumentException
indicates an argument passed to the method is invalid.
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 necessary
for creating the Connection object is unavailable.
PrivilegeViolationException
- The application does not have
the proper authority to create the Connection.
MethodNotSupportedException
- The implementation does not
support this method
InvalidPartyException
- In case one of the parties given is invalid.public JccConnection routeCall(java.lang.String targetAddress, java.lang.String originatingAddress, java.lang.String originalDestinationAddress, java.lang.String redirectingAddress) throws InvalidStateException, ResourceUnavailableException, PrivilegeViolationException, MethodNotSupportedException, InvalidPartyException, InvalidArgumentException
createConnection(String,String,String,String)
,
JccConnection.routeConnection(FALSE)
and JccConnection.attachMedia()
or is also
equivalent to createConnection(String,String,String,String)
and
JccConnection.routeConnection(TRUE).
routeCall("B","A",null,null)
will result in third party setup of a Connection.
A reference to the created connection i.e "B"'s connection will be returned.
A getAddress() method invocation on the returned JccConnection reference object
results in the JccAddress corresponding to party "B" being returned.
routeCall("C","A","B","B")
will be applied in case the
number of party "B" is translated into the number of party "C", while party "A"
dialed party "B". routeCall("C","A",null,"B")
and routeCall("C","A","B",null)
result in the same behavior. Note that in all three cases the connection with address "B" is
automatically moved to
DISCONNECTED
with cause code
CAUSE_REDIRECTED
.
A reference to the created connection i.e "C"'s connection will be returned.
A getAddress() method invocation on the returned JccConnection reference object
results in the JccAddress corresponding to party "C" being returned.
routeCall("D","A","B","C")
will be applied in case the number
of party "C" is translated into the number of party "D", while party "A" dialed party B.
A reference to the created connection, i.e. "D"'s connection, will be returned.
A getAddress() method invocation on the returned JccConnection reference object
results in the JccAddress corresponding to party "D" being returned.
Note that the connection with address "C" is automatically moved to
DISCONNECTED
with cause code
CAUSE_REDIRECTED
.
Pre-conditions:
Post-conditions:
targetAddress
- specifies the address to which the call
should be routed.originatingAddress
- specifies the address of the originating (calling)
party for this leg of the call. This is optional and can be set to null.redirectingAddress
- specifies the last address from which this leg of the call
was redirected. This is optional and can be set to null.
InvalidArgumentException
- An InvalidArgumentException
indicates an argument passed to the method is invalid.
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 necessary
for creating the Connection object is unavailable.
PrivilegeViolationException
- The application does not have
the proper authority to create the Connection.
MethodNotSupportedException
- The implementation does not
support this method
InvalidPartyException
- In case one of the parties given is invalid.public int getState()
IDLE
,
ACTIVE
or INVALID
.
public void addCallListener(JccCallListener calllistener) throws ResourceUnavailableException, MethodNotSupportedException
JccCallEvent.CALL_EVENT_TRANSMISSION_ENDED
event.
JccProvider.addCallListener(JccCallListener)
or similar methods.
JccProvider.addCallListener()
either of these methods
modifies the behavior of that listener as if it were added via
this method instead.
Post-Conditions:
calllistener
- JccCallListener object that receives the specified events.
MethodNotSupportedException
- The listener cannot be added at this time.
ResourceUnavailableException
- The resource limit for the number of
listeners has been exceeded.public void removeCallListener(JccCallListener calllistener)
This method has different effects depending upon how the listener was added to the Call, as follows:
addCallListener(JccCallListener)
, this method removes the
listener until it is re-applied by the application.
JccProvider.addCallListener(JccCallListener)
or simular methods, this method removes
the listener for this call only. It does not affect whether this
listener will be added to future calls coming in to the JccProvider.
calllistener
- JccCall Listener object.public JccProvider getProvider()
public JccConnection[] getConnections()
JccConnection.DISCONNECTED
state. Further,
if the Call is in the IDLE
or INVALID
state,
this method returns null.
Post-Conditions:
|
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