javax.telephony.callcenter
Interface RouteSession

All Known Subinterfaces:
ITsapiRouteSession, LucentRouteSession, LucentV7RouteSession

public interface RouteSession

Introduction

A RouteSession represents an outstanding route request of a Call. Each session is associated with a particular RouteAddress which represents the Address to which the Call was originally placed. This RouteAddress is obtained via the getRouteAddress() method defined on this interface. Applications must have previously asked to route calls to this Address.

Routing Callbacks

Each RouteSession may be associated with zero or more routing callbacks, as represented by the RouteCallback interface. Using the RouteCallback interface, applications may routing decisions for Calls. Applications register a callback via the RouteAddress.registerRouteCallback() method. Current callbacks registered on a RouteAddress are associated with all new RouteSessions created at that RouteAddress. A RouteSession, therefore, may have more than one callback associated with it. The first RouteCallback to respond with a routing request for a particular RouteSession wins, in the case multiple RouteCallbacks exist.

The Routing State

A RouteSession has a state which represents the current status of the Call with respect to the routing requests submitted by the application. These states are defined as static integer constants on this interface. Applications obtain the current state via the RouteSession.getState() method. The various states of a route session are summarized below.

RouteSession.ROUTE This state indicates that an application has been requested to route a Call.
RouteSession.ROUTE_USED This state indicates that a destination has been selected for a Call. This destination is one which the application had selected during its routing of the Call.
RouteSession.ROUTE_END This state indicates that the routing of a Call has terminated.
RouteSession.RE_ROUTE This state indicates that an application has been requested to select another destination for the Call.
RouteSession.ROUTE_CALLBACK_ENDED This state indicates that all RouteCallback objects have been removed from this routing session. There are no more routing callbacks associated with this session. This is the final state for the RouteSession interface.

RouteSession State Transition Diagram

The states of the RouteSession must transition according to the finite state diagram below. The implementation must guarantee the state of a RouteSession adheres to these valid transitions.

Selecting the Routing for a Call

Applications use the RouteSession.selectRoute() method to select possible destinations for the Call associated with this routing session. The state of the RouteSession must either be RouteSession.ROUTE or RouteSession.RE_ROUTE in order for this method to be valid.

An array of destination address strings are given to this method. This list represents a priority-order list of possible destinations for the Call. The Call is routed to the first destination given (at index 0). If it fails, the second destination is attempted. This process is repeated until there are no more remaining destinations, or until a successful destination has been chosen. If a successful destination has been chosen, the state of the RouteSession moves into RouteSession.ROUTE_USED.

See Also:
RouteCallback, RouteAddress, RouteSessionEvent, RouteEvent, ReRouteEvent, RouteUsedEvent, RouteEndEvent, RouteCallbackEndedEvent

Field Summary
static int CAUSE_INVALID_DESTINATION
          Cause code indicating that the routing session is being terminated because because the application supplied an invalid destination in the RouteSession.routeSelect() method.
static int CAUSE_NO_ERROR
          Cause code indicating no error.
static int CAUSE_PARAMETER_NOT_SUPPORTED
          Cause code indicating that the routing session is being terminated because the application supplied an unsupported parameter in the RouteSession.routeSelect() method.
static int CAUSE_ROUTING_TIMER_EXPIRED
          Cause code indicating a routing timer has expired.
static int CAUSE_STATE_INCOMPATIBLE
          Cause code indicating that the routing session is being terminated because the Connection state is incompatable with the RouteSession.
static int CAUSE_UNSPECIFIED_ERROR
          Cause code indicating that the routing session is being terminated for unspecified reasons.
static int ERROR_RESOURCE_BUSY
          Error code indicating the application is too busy to handle the routing request.
static int ERROR_RESOURCE_OUT_OF_SERVICE
          Error code indicating the application or a database upon which it relies for routing is temporary out of service and cannot handle the routing request.
static int ERROR_UNKNOWN
          Error code indicating the application is not giving a reason for ending the routing session.
static int RE_ROUTE
          The RouteSession.RE_ROUTE state indicates that an application has been requested to select another destination for the Call.
static int ROUTE
          The RouteSession.ROUTE state indicates that an application has been requested to route a Call.
static int ROUTE_CALLBACK_ENDED
          The RouteSession.ROUTE_CALLBACK_ENDED state indicates that all RouteCallback objects have been removed from this routing session.
static int ROUTE_END
          The RouteSession.ROUTE_END state indicates that the routing of a Call has terminated.
static int ROUTE_USED
          The RouteSession.ROUTE_USED state indicates that a destination has been selected for a Call.
 
Method Summary
 void endRoute(int errorValue)
          Ends a routing session.
 int getCause()
          Returns the cause indicating why this route session is in its current state.
 RouteAddress getRouteAddress()
          Returns the RouteAddress associated with this routing session and the one for which the application has registered to route Calls for.
 int getState()
          Returns the current state of the route session.
 void selectRoute(java.lang.String[] routeSelected)
          Selects one or more possible destinations for the routing of the Call.
 

Field Detail

ROUTE

public static final int ROUTE
The RouteSession.ROUTE state indicates that an application has been requested to route a Call.

See Also:
Constant Field Values

ROUTE_USED

public static final int ROUTE_USED
The RouteSession.ROUTE_USED state indicates that a destination has been selected for a Call. This destination is one which the application had selected during its routing of the Call.

See Also:
Constant Field Values

ROUTE_END

public static final int ROUTE_END
The RouteSession.ROUTE_END state indicates that the routing of a Call has terminated.

See Also:
Constant Field Values

RE_ROUTE

public static final int RE_ROUTE
The RouteSession.RE_ROUTE state indicates that an application has been requested to select another destination for the Call.

See Also:
Constant Field Values

ROUTE_CALLBACK_ENDED

public static final int ROUTE_CALLBACK_ENDED
The RouteSession.ROUTE_CALLBACK_ENDED state indicates that all RouteCallback objects have been removed from this routing session. There are no more routing callbacks associated with this session. This is the final state for the RouteSession interface.

See Also:
Constant Field Values

CAUSE_NO_ERROR

public static final int CAUSE_NO_ERROR
Cause code indicating no error.

See Also:
Constant Field Values

CAUSE_ROUTING_TIMER_EXPIRED

public static final int CAUSE_ROUTING_TIMER_EXPIRED
Cause code indicating a routing timer has expired.

See Also:
Constant Field Values

CAUSE_PARAMETER_NOT_SUPPORTED

public static final int CAUSE_PARAMETER_NOT_SUPPORTED
Cause code indicating that the routing session is being terminated because the application supplied an unsupported parameter in the RouteSession.routeSelect() method.

See Also:
Constant Field Values

CAUSE_INVALID_DESTINATION

public static final int CAUSE_INVALID_DESTINATION
Cause code indicating that the routing session is being terminated because because the application supplied an invalid destination in the RouteSession.routeSelect() method.

See Also:
Constant Field Values

CAUSE_STATE_INCOMPATIBLE

public static final int CAUSE_STATE_INCOMPATIBLE
Cause code indicating that the routing session is being terminated because the Connection state is incompatable with the RouteSession.

See Also:
Constant Field Values

CAUSE_UNSPECIFIED_ERROR

public static final int CAUSE_UNSPECIFIED_ERROR
Cause code indicating that the routing session is being terminated for unspecified reasons.

See Also:
Constant Field Values

ERROR_UNKNOWN

public static final int ERROR_UNKNOWN
Error code indicating the application is not giving a reason for ending the routing session. This value may be passed as an argument to the RouteSession.endRoute() method.

See Also:
Constant Field Values

ERROR_RESOURCE_BUSY

public static final int ERROR_RESOURCE_BUSY
Error code indicating the application is too busy to handle the routing request. This value may be passed as an argument to the RouteSession.endRoute() method.

See Also:
Constant Field Values

ERROR_RESOURCE_OUT_OF_SERVICE

public static final int ERROR_RESOURCE_OUT_OF_SERVICE
Error code indicating the application or a database upon which it relies for routing is temporary out of service and cannot handle the routing request. This value may be passed as an argument to the RouteSession.endRoute() method.

See Also:
Constant Field Values
Method Detail

getRouteAddress

public RouteAddress getRouteAddress()
Returns the RouteAddress associated with this routing session and the one for which the application has registered to route Calls for.

Returns:
The RouteAddress associated with this session.

selectRoute

public void selectRoute(java.lang.String[] routeSelected)
                 throws MethodNotSupportedException
Selects one or more possible destinations for the routing of the Call. This method takes an array of string destination telephone address names, in priority order. The highest priority destination is the first element in the given array, and routing is attempted with this destination first. Successive given destination addresses are attempted until one is found which does not fail.

A RouteUsedEvent event is delivered to the application when a successful routing destination has been selected and the Call has been routed to that destination.

Pre-conditions:

  1. this.getRouteAddress().getProvider().getState() == Provider.IN_SERVICE
  2. this.getState() == RouteSession.ROUTE or RouteSession.RE_ROUTE
Post-Conditions
  1. this.getRouteAddress().getProvider().getState() == Provider.IN_SERVICE
  2. this.getState() == RouteSession.ROUTE_USED if Call was successfully routed.
  3. RouteUsedEvent is delivered for this RouteSession if a successful destination was selected.

Parameters:
routeSelected - A list of possible destinations for the call.
Throws:
MethodNotSupportedException - Routing is not supported by the implementation.

endRoute

public void endRoute(int errorValue)
              throws MethodNotSupportedException
Ends a routing session. The application provides an integer error value argument giving the reason why it is terminating this routing session. These error values are defined by this interface.

If this method is successful, the state of this RouteSession moves into the RouteSession.ROUTE_END state and a RouteEndEvent is delivered.

Pre-Conditions

  1. this.getRouteAddress().getProvider().getState() == Provider.IN_SERVICE

Post-Conditions

  1. this.getRouteAddress().getProvider().getState() == Provider.IN_SERVICE
  2. this.getState() == RouteSession.ROUTE_END
  3. RouteEndEvent is delivered to the application for this RouteSession

Parameters:
errorValue - Indicates the reason why the application is terminating this routing session, as defined by the constants in this interface.
Throws:
MethodNotSupportedException - The implementation does not support this method.

getState

public int getState()
Returns the current state of the route session.

Returns:
The current state of the route session.

getCause

public int getCause()
Returns the cause indicating why this route session is in its current state. These cause values are constant integer definitions defined by this interface.

Returns:
The cause of the current route session state.


Copyright © 2005 Avaya All Rights Reserved.