JCAT
v0.3.1

javax.jcat
Interface JcatTerminalConnection


public interface JcatTerminalConnection

A JcatTerminalConnection object maintains a state that reflects the relationship between a JcatTerminal and a JcatConnection. A JcatTerminalConnection object state is distinct from the JcatConnection object states. The JcatConnection object states describe the relationship between an entire JcatAddress endpoint and a JcatCall, whereas the JcatTerminalConnection state describes the relationship between one of the JcatTerminal objects at the endpoint JcatAddress on the JcatCall with respect to its JcatConnection. Different JcatTerminals on a JcatCall, which are associated with the same, JcatConnection may be in different states. Furthermore, the state of the JcatTerminalConnection has a dependency and specific relationship to the state of its JcatConnection.

The TerminalConnection object has the following states:

IDLE This state is the initial state for a JcatTerminalConnection object. A JcatTerminalConnection object does not stay in the IDLE state for long, quickly transitioning to other states.
RINGING This state indicates the JcatTerminal is ringing and that the JcatTerminal has an incoming call.
DROPPED This state indicates that a particular JcatTerminal has permanently left the call. When a JcatTerminalConnection object moves into the DROPPED state, it is no longer associated with its JcatConnection and JcatTerminal objects. That is, both of these objects lose their references to the JcatTerminalConnection. However, the JcatTerminalConnection still maintains its references to the JcatConnection and JcatTerminal object for application reference.
BRIDGED This state indicates that a JcatTerminal is currently bridged into a Call. A JcatTerminal may typically join a JcatCall when it is bridged. A bridged JcatTerminal is part of the call, but not active. Typically, some hardware resource is occupied while a JcatTerminal is bridged into a JcatCall.
TALKING This state indicates that the JcatTerminal is actively part of a JcatCall, is typically "off-hook", and the party is communicating on the call.
INUSE This state indicates that a JcatTerminal hardware resource is currently in use. The terminal is not available for the JcatCall associated with this JcatTerminalConnection, that is the JcatTerminal may not join the call. This state is similar to the BRIDGED state except that the JcatTerminal may not join the JcatCall.
HELD This state indicates that a JcatTerminal is part of a JcatCall, but is on hold. Other JcatTerminal objects, which are on the same JcatCall and associated with the same JcatConnection may or may not also be in this state.

TerminalConnection object state transition diagram

The figure below illustrates the finite-state diagram for a JcatTerminalConnection object. The finite-states describe the allowable state transitions of a JcatTerminalConnection object. The API must guarantee these state transitions. The specifications of operations, which affect the state of the JcatTerminalConnections, also obey these state transitions. The JcatTerminalConnection object may transition into the DROPPED state from any state. The JcatTerminalConnection object in the IDLE or RINGING state can transition into any other state.

JcatTerminalConnection FSM

The following table defines the specific relationship between JcatConnection states and JcatTerminalConnection states.

JcatConnection State JcatTerminalConnectionState
JccConnection.IDLE Zero or more JcatTerminalConnection objects may exist for this JcatConnection, and each must be in the IDLE state.
JccConnection.AUTHORIZE_CALL_ATTEMPT, JccConnection.ADDRESS_COLLECT, JccConnection.ADDRESS_ANALYZE, JccConnection.CALL_DELIVERY Zero or more JcatTerminalConnection objects may exist for this JcatConnection, and each must be in the IDLE state.
JccConnection.ALERTING Zero or more JcatTerminalConnections may exist for this JcatConnection, and each must be in the RINGING state.
JccConnection.CONNECTED Zero or more JcatTerminalConnections may exist for this JcatConnection, and each must be in the BRIDGED or INUSE state (passive) or in the TALKING or HELD (active) state. Note that when JcatTerminalConnections transition into the DROPPED state they are no longer associated with the JcatConnection.
JccConnection.FAILED No TerminalConnections may exist for this Connection. Note that all TerminalConnections previously associated with this Connection will move into the DROPPED state.
JcatConnection.SUSPENDED Zero or more JcatTerminalConnections may exist for this JcatConnection, and each must be in the HELD state.
JccConnection.DISCONNECTED Zero or more JcatTerminalConnections may exist for this JcatConnection, and each must be in the DROPPED state.

Since:
1.0

Field Summary
static int BRIDGED
          This state indicates that a JcatTerminal is currently bridged into a Call.
static int DROPPED
          This state indicates that a particular JcatTerminal has permanently left the call.
static int HELD
          This state indicates that a JcatTerminal is part of a JcatCall, but is on hold.
static int IDLE
          This state is the initial state for a JcatTerminalConnection object.
static int INUSE
          This state indicates that a JcatTerminal hardware resource is currently in use.
static int RINGING
          This state indicates the JcatTerminal is ringing and that the JcatTerminal has an incoming JcatCall.
static int TALKING
          This state indicates that the JcatTerminal is actively part of a JcatCall.
 
Method Summary
 void answer()
          Answers an incoming telephone call on this Terminal Connection.
 JcatConnection getConnection()
          Returns the JcatConnection object associated with this JcatTerminalConnection.
 int getState()
          Returns the state of the JcatTerminalConnection object.
 JcatTerminal getTerminal()
          Returns the JcatTerminal associated with this JcatTerminalConnection object.
 void hold()
          Places a JcatTerminalConnection on hold with respect to the JcatCall of which it is a part.
 void join()
          Makes a currently bridged JcatTerminalConnection active on a JcatCall.
 void leave()
          Places a currently active JcatTerminalConnection in a bridged state on a JcatCall.
 void unhold()
          Takes a JcatTerminalConnection off hold with respect to the JcatCall of which it is a part.
 

Field Detail

IDLE

public static final int IDLE
This state is the initial state for a JcatTerminalConnection object.

See Also:
Constant Field Values

RINGING

public static final int RINGING
This state indicates the JcatTerminal is ringing and that the JcatTerminal has an incoming JcatCall.

See Also:
Constant Field Values

DROPPED

public static final int DROPPED
This state indicates that a particular JcatTerminal has permanently left the call.

See Also:
Constant Field Values

BRIDGED

public static final int BRIDGED
This state indicates that a JcatTerminal is currently bridged into a Call.

See Also:
Constant Field Values

TALKING

public static final int TALKING
This state indicates that the JcatTerminal is actively part of a JcatCall.

See Also:
Constant Field Values

INUSE

public static final int INUSE
This state indicates that a JcatTerminal hardware resource is currently in use.

See Also:
Constant Field Values

HELD

public static final int HELD
This state indicates that a JcatTerminal is part of a JcatCall, but is on hold.

See Also:
Constant Field Values
Method Detail

answer

public void answer()
Answers an incoming telephone call on this Terminal Connection. This operation waits (i.e. the invoking thread blocks) until the telephone call has been answered at the endpoint before returning. When this operation returns successfully, the state of this Terminal Connection object is TALKING.

Allowable Terminal Connection States

The Terminal Connection must be in the RINGING state when this operation is invoked. This implies that the associated Connection object is in the JccConnection.ALERTING state. There may be more than one Terminal Connection on the Connection which are in the RINGING state.

Multiple Terminal Connections

The underlying telephone hardware determines the resulting state of other Terminal Connection objects after the telephone call has been answered by one of the Terminal Connections. The other Terminal Connection object may either move into the BRIDGED or INUSE state or the DROPPED state. If a Terminal Connection moves into the BRIDGED or INUSE state, it remains part of the telephone call, but not actively so. It may have the ability to join the call in the future. If a Terminal Connection moves into the DROPPED state, it is removed from the telephone call. The appropriate events are delivered to the application indicates into which of these two states the other Terminal Connection objects have moved.

Events

The following events are reported to applications via the JcatTerminalConnectionListener and JccConnectionListener interface as a result of the successful outcome of this operation:
  1. JcatTerminalConnectionEvent.TERMINALCONNECTION_TALKING for the Terminal Connection which invoked this operation.
  2. JccConnectionEvent.CONNECTION_CONNECTED for the Connection associated with the Terminal Connection.
  3. JcatTerminalConnectionEvent.TERMINALCONNECTION_BRIDGED, JcatTerminalConnectionEvent.TERMINALCONNECTION_INUSE or JcatTerminalConnectionEvent.TERMINALCONNECTION_DROPPED for other Terminal Connections associated with the Connection.


getConnection

public JcatConnection getConnection()
Returns the JcatConnection object associated with this JcatTerminalConnection. A JcatTerminalConnection's reference to the JcatConnection remains valid throughout the lifetime of the JcatTerminalConnection. Also, this reference does not change once the JcatTerminalConnection object has been created.

Returns:
JcatConnection object associated with this JcatTerminalConnection.

getState

public int getState()
Returns the state of the JcatTerminalConnection object.

Returns:
state of the Terminal Connection object.

getTerminal

public JcatTerminal getTerminal()
Returns the JcatTerminal associated with this JcatTerminalConnection object. A terminal connection's reference to its terminal remains valid for the lifetime of the object, even if the terminal loses its references to this terminal connection object. Also, this reference does not change once the JcatTerminalConnection object has been created.

Returns:
JcatTerminal associated with this JcatTerminalConnection object.

hold

public void hold()
          throws InvalidStateException,
                 MethodNotSupportedException,
                 PrivilegeViolationException,
                 ResourceUnavailableException
Places a JcatTerminalConnection on hold with respect to the JcatCall of which it is a part. Many JcatTerminals may be on the same JcatCall and associated with the same JcatConnection. Any one of them may go "on hold" at any time, provided they are "active" in the Call. The JcatTerminalConnection must be in the TALKING state. This operation returns when the Terminal Connection has moved to the HELD state, or until an error occurs and an exception is thrown.

Throws:
InvalidStateException
MethodNotSupportedException
PrivilegeViolationException
ResourceUnavailableException
See Also:
JcatCall

join

public void join()
          throws InvalidStateException,
                 MethodNotSupportedException,
                 PrivilegeViolationException,
                 ResourceUnavailableException
Makes a currently bridged JcatTerminalConnection active on a JcatCall. Other terminals, which share the same JcatAddress as this JcatTerminal, may be active on the same JcatCall. This situation is known as bridging. The JcatTerminalConnection must be in the BRIDGED state. This operation returns when the JcatTerminalConnection has moved to the TALKING state or until an error occurs and an exception is thrown.

Throws:
InvalidStateException
MethodNotSupportedException
PrivilegeViolationException
ResourceUnavailableException
See Also:
JcatCall

leave

public void leave()
           throws InvalidStateException,
                  MethodNotSupportedException,
                  PrivilegeViolationException,
                  ResourceUnavailableException
Places a currently active JcatTerminalConnection in a bridged state on a JcatCall. Other terminals, which share the same JcatAddress as this JcatTerminal, may remain active on the same JcatCall. This situation where JcatTerminals share a JcatAddress on a call is known as bridging. The terminal connection on which this operation is invoked must be in the TALKING state. There are two possible outcomes of this operation depending upon the number of remaining, active JcatTerminalConnection objects on the Call. If there are other active terminal connections, then this JcatTerminalConnection moves into the BRIDGED state and this operation returns. If there are no other active JcatTerminalConnection objects, then this JcatTerminalConnection moves into the DROPPED state. Its associated JcatConnection moves into the JccConnection.DISCONNECTED state, i.e. the entire endpoint leaves the telephone call. This operation waits until one of these two outcomes occurs or until an error occurs and an exception is thrown.

Throws:
InvalidStateException
MethodNotSupportedException
PrivilegeViolationException
ResourceUnavailableException

unhold

public void unhold()
            throws InvalidStateException,
                   MethodNotSupportedException,
                   PrivilegeViolationException,
                   ResourceUnavailableException
Takes a JcatTerminalConnection off hold with respect to the JcatCall of which it is a part. Many JcatTerminal objects may be on the same JcatCall and associated with the same JcatConnection. Any one of them may go "on hold" at any time, provided they are active in the JcatCall. The JcatTerminalConnection must be in the HELD state. This operation returns successfully when the JcatTerminalConnection moves into the TALKING state or until an error occurs and an exception is thrown.

Throws:
InvalidStateException
MethodNotSupportedException
PrivilegeViolationException
ResourceUnavailableException

JCAT
v0.3.1

August, 2003
If you have any comments or queries, please mail them to JSR-122-EG@JCP.ORG

Copyright - 2001, 2003 Sun Microsystems