javax.telephony.callcenter
Interface CallCenterCall

All Superinterfaces:

Call

public interface CallCenterCall

extends Call

Introduction

The CallCenterCall interface extends the core Call interface. This interface provides additional Call-related features for the call center package. Applications may query an object with the instanceof operator to check whether it supports this interface.

Predictive Dialing

Predictive dialing is a special means to place a telephone call. In a predictive telephone call, the destination end is created and placed on the Call first. Only when the destination Connection reaches a certain state, as designated by the application, the originating Connection is created and the originating end is placed on the Call. Predictive dialing is used, for example, when customers are called from a long list, and a customer service representative is placed on the Call only when a customer can be reached. Applications placed predictive telephone calls via the connectPredictive() method on this interface.

Application Data

Applications may associated an arbitrary piece of data with a Call. This data is seen by any application which has a handle to a Call. This mechanism is often used to store information specific to a Call, such as customer information. The setApplicationData() method defined on this sets the current data and the getApplicationData() method retrieves the current application-specific data.

Trunks

Zero or more trunks may be associated with the Call. Applications obtain the trunks associated with a Call via the getTrunks() method on this interface. A trunk is represented by the CallCenterTrunk interface.

Observers and Events

Events pertaining to the CallCenterCall interface are reported via the CallCenterCallObserver interface. The following are those events reported via this interface:

• Connection "in progress" state event
• Trunk state events
• Application data change events

See Also:

CallCenterCallObserver, CallCenterTrunk

Field Summary

static int	ANSWERING_TREATMENT_CONNECT Answering endpoint treatment: connect the Call when the endpoint is detected.
static int	ANSWERING_TREATMENT_DROP Answering endpoint treatment: drop the Call when the endpoint is detected.
static int	ANSWERING_TREATMENT_NONE Answering endpoint treatment: no treatment specified.
static int	ANSWERING_TREATMENT_PROVIDER_DEFAULT Answering endpoint treatment: follow the default treatment.
static int	ENDPOINT_ANSWERING_MACHINE Answering endpoint type: answering endpoint may be an answering machine.
static int	ENDPOINT_ANY Answering endpoint type: answering endpoint may be anything.
static int	ENDPOINT_FAX_MACHINE Answering endpoint type: answering endpoint may be a fax machine.
static int	ENDPOINT_HUMAN_INTERVENTION Answering endpoint type: answering endpoint may be a human.
static int	MAX_RINGS The CallCenterCall.MIN_RINGS constant defines the minimum number of rings which the application may specify for the destination end before a predictive telephone call is classified as "no answer".
static int	MIN_RINGS The CallCenterCall.MIN_RINGS constant defines the minimum number of rings which the application may specify for the destination end before a predictive telephone call is classified as "no answer".

Fields inherited from interface javax.telephony.Call

ACTIVE, IDLE, INVALID

Method Summary

Connection[]	connectPredictive(Terminal originatorTerminal, Address originatorAddress, java.lang.String destination, int connectionState, int maxRings, int treatment, int endpointType) Places a predictive telephone call.
java.lang.Object	getApplicationData() Returns the application-specific data associated with the Call.
CallCenterTrunk[]	getTrunks() Returns an array of all CallCenterTrunks currently being used for this Call.
void	setApplicationData(java.lang.Object data) This method associates application specific data with a Call.

Methods inherited from interface javax.telephony.Call

addCallListener, addObserver, connect, getCallCapabilities, getCallListeners, getCapabilities, getConnections, getObservers, getProvider, getState, removeCallListener, removeObserver

Field Detail

MIN_RINGS

public static final int MIN_RINGS

The CallCenterCall.MIN_RINGS constant defines the minimum number of rings which the application may specify for the destination end before a predictive telephone call is classified as "no answer".

MAX_RINGS

public static final int MAX_RINGS

The CallCenterCall.MIN_RINGS constant defines the minimum number of rings which the application may specify for the destination end before a predictive telephone call is classified as "no answer".

ANSWERING_TREATMENT_PROVIDER_DEFAULT

public static final int ANSWERING_TREATMENT_PROVIDER_DEFAULT

Answering endpoint treatment: follow the default treatment. The answering endpoint treatment should follow the default treatment.

ANSWERING_TREATMENT_DROP

public static final int ANSWERING_TREATMENT_DROP

Answering endpoint treatment: drop the Call when the endpoint is detected.

ANSWERING_TREATMENT_CONNECT

public static final int ANSWERING_TREATMENT_CONNECT

Answering endpoint treatment: connect the Call when the endpoint is detected.

ANSWERING_TREATMENT_NONE

public static final int ANSWERING_TREATMENT_NONE

Answering endpoint treatment: no treatment specified.

ENDPOINT_ANSWERING_MACHINE

public static final int ENDPOINT_ANSWERING_MACHINE

Answering endpoint type: answering endpoint may be an answering machine.

ENDPOINT_FAX_MACHINE

public static final int ENDPOINT_FAX_MACHINE

Answering endpoint type: answering endpoint may be a fax machine.

ENDPOINT_HUMAN_INTERVENTION

public static final int ENDPOINT_HUMAN_INTERVENTION

Answering endpoint type: answering endpoint may be a human.

ENDPOINT_ANY

public static final int ENDPOINT_ANY

Answering endpoint type: answering endpoint may be anything.

Method Detail

connectPredictive

public Connection[] connectPredictive(Terminal originatorTerminal,
                                      Address originatorAddress,
                                      java.lang.String destination,
                                      int connectionState,
                                      int maxRings,
                                      int treatment,
                                      int endpointType)
                               throws ResourceUnavailableException,
                                      PrivilegeViolationException,
                                      InvalidPartyException,
                                      InvalidArgumentException,
                                      InvalidStateException,
                                      MethodNotSupportedException

Places a predictive telephone call. A predictive telephone call is a telephone call placed to the destination end first, and connects the originating end only if the destination end reaches either the Connection.CONNECTED or Connection.ALERTING state. The destination Connection is created first, and the originating Connection is created only if the destination reaches the designated state. This method returns successfully when both Connections are created and returned.

The originating and destination end arguments

The first three arguments are identical to the arguments of the Call.connect() method. They represent the desired originating and destination ends of the Call. The originating Terminal may be null, however, for certain types of Addresses, such as ACD Addresses, this argument may be null. The destination address string given must be complete and valid.

The target destination Connection state

The application designates when the originating end of the Call is created and placed on the telephone Call, based upon the state of the destination Connection. The desired target state for the destination Connection is given as the connectionState argument to this method. The value must be either Connection.CONNECTED or Connection.ALERTING. If the destination Connection never reaches this state, this method throws an appropriate exception.

The maximum number of rings

The application may also designate the maximum number of rings allowed on the destination end before the Call is classified as a "no answer". The value must be between CallCenterCall.MIN_RINGS (2) and CallCenterCall.MAX_RINGS (15).

Answering treatment and endpoint type

The two final arguments specify how the Call is treated when the destination Connection reaches its target destination, and the allowed kinds of endpoints on the answering end. Each of these arguments must be one of the designated constants defined by this interface.

The returned Connections

The Connections created and returned by this method behave similarly to Connections which were returned from Call.connect(). The originating Connection moves into the Connection.CONNECTED state when an originating party is placed on the Call. If the target state for the destination Connection is Connection.ALERTING, it moves into the Connection.CONNECTED state when the called party answers the Call.

Pre-conditions

1. (this.getProvider()).getState() == Provider.IN_SERVICE
2. this.getState() == Call.IDLE
3. connectionState == Connection.CONNECTED or Connection.ALERTING
4. maxRings >= CallCenterCall.MIN_RINGS
5. maxRings <= CallCenterCall.MAX_RINGS

Post-conditions

1. Let connections[] = this.getConnections()
2. (this.getProvider()).getState() == Provider.IN_SERVICE
3. this.getState() == Call.IDLE
4. connections.length == 2
5. connections[0].getState() == connectionState
6. connections[1].getState() == Connection.IDLE

Parameters:

originatorTerminal - The originating Terminal. If the originating Address is an ACD Address, for example, this value may be null.

originatorAddress - The originating Address of the telephone call.

destination - The complete and valid telephone address string.

connectionState - The target state for the destination Connection before the originating Connection is created. This must either be Connection.CONNECTED or Connection.ALERTING

maxRings - The maximum number of rings before classifying the Call as "no answer".

treatment - The treatment of the Call when the endpoint is detected.

endpointType - The permitted answering endpoint type.

Returns:

An array of the originating and destination Connection

Throws:

ResourceUnavailableException - An internal resource necessary for placing the phone call is unavailable.

PrivilegeViolationException - The application does not have the proper authority to place a telephone call.

InvalidPartyException - Either the originator or the destination does not represent a valid party required to place a telephone call.

InvalidArgumentException - An argument provided is not valid either by not providing enough information or is inconsistent with another argument.

InvalidStateException - Either the Provider is not in service or the Call is not idle.

MethodNotSupportedException - The implementation does not support this method.

setApplicationData

public void setApplicationData(java.lang.Object data)
                        throws ResourceUnavailableException,
                               InvalidArgumentException,
                               InvalidStateException,
                               MethodNotSupportedException

This method associates application specific data with a Call. The format of the data is application-specific. The application-specific data given in this method replaces any existing application data. If the argument given is null, the current application data (if any) is removed.

In the case that a Call is transfered or conferenced, the application data from the Call from which the conference or transfer is invoked will be retained.

Pre-conditions:

1. (this.getProvider()).getState() == Provider.IN_SERVICE
2. this.getState() == Call.ACTIVE or Call.IDLE

Post-conditions:

1. (this.getProvider()).getState() == Provider.IN_SERVICE
2. this.getState() == Call.ACTIVE or Call.IDLE
3. this.getApplicationData() = data
4. A CallCentCallAppDataEv is delivered for this Call

Parameters:

data - The data to be associated with the call.

Throws:

ResourceUnavailableException - An internal resource necessary for adding the data was unavailable. For example, the size of the Object was not supported by the implementation.

InvalidArgumentException - The argument provided is not valid. For example, the implementation does not support the specific object type.

InvalidStateException - Either the Provider was not in service or the Call was not active or idle.

MethodNotSupportedException - The implementation does not support this method.

See Also:

CallCentCallAppDataEv

getApplicationData

public java.lang.Object getApplicationData()
                                    throws MethodNotSupportedException

Returns the application-specific data associated with the Call. This method returns null is there is no associated data.

Returns:

The application-specific data associated with this Call.

Throws:

MethodNotSupportedException - The implementation does not support this method.

getTrunks

public CallCenterTrunk[] getTrunks()
                            throws MethodNotSupportedException

Returns an array of all CallCenterTrunks currently being used for this Call. If there are no trunks being used for this Call, this method returns null. Each trunk returns by this method will be in the CallCenterTrunk.VALID state.

Post-conditions:

1. Let CallCenterTrunk[] trunks = this.getTrunks()
2. trunks == null or trunks.length >= 1
3. trunks[i].getState() == CallCenterTrunk.VALID_TRUNK, for all i

Returns:

An array of trunks currently associated with this Call.

Throws:

MethodNotSupportedException - The implementation does not support this method.