connection.java

Java Telephony API .java程序

/*
#pragma ident "@(#)Connection.java	1.1      96/11/01     SMI"

 * Copyright (c) 1996 Sun Microsystems, Inc. All Rights Reserved.
 *
 * Permission to use, copy, modify, and distribute this software
 * and its documentation for NON-COMMERCIAL purposes and without
 * fee is hereby granted provided that this copyright notice
 * appears in all copies. Please refer to the file "copyright.html"
 * for further important copyright and licensing information.
 *
 * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF
 * THE SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
 * TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
 * PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR
 * ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
 * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.
 */

package java.telephony;
import  java.telephony.capabilities.ConnectionCapabilities;

/**
 * A Connection represents a link (i.e. an association) between a Call object
 * and an Address object. The purpose of a Connection object is to describe
 * this relationship between the Address and a Call. A Connection object exists
 * if the Address is a part of the telephone call. Each Connection has a
 * <EM>state</EM> which describes the particular stage of the relationship
 * between the Call and Address. For example, when the Address is actively
 * part of a telephone call, the Connection state which relates the two
 * is CONNECTED. If there is an incoming call to an Address, the Connection
 * state is ALERTING. These various states are described below. In most
 * situations, the state of the Connection describes what actions are
 * possible on the Connection.
 * <p>
 * Connection objects are immutable in terms of its Call and Address
 * references. In other words, the Call and Address object references do
 * not change throughout the lifetime of the Connection object instance. The
 * same Connection object may not be used in another telephone call. The
 * existence of a Connection implies that its Address is associated with its
 * Call in the manner described by the Connection's state.
 * <p>
 * Although a Connection's Address and Call references remain valid throughout
 * the lifetime of the Connection object, the same is not true for the Call
 * and Address object's references to this Connection. Particularly, when a 
 * Connection moves into the Connection.DISCONNECTED state, it is no longer
 * listed by the <EM>Call.getConnections()</EM> and
 * <EM>Address.getConnections()</EM> methods. Typically, when a Connection
 * moves into the Connection.DISCONNECTED state, the application loses
 * its references to it to faciliate its garbage collection.
 * <p>
 * Connections may be viewed as a container for zero or more TerminalConnection
 * objects. Connection objects represent the relationship between the Call and
 * the Address, whereas TerminalConnection objects represent the relationship
 * between the Call and the Terminal. The relationship between the Call and
 * the Address may be views as a "logical" view of the Call, i.e. where the
 * endpoints are telephone number addresses. The relationship between a Call
 * and a Terminal represents the "physical" view of the Call, i.e. at which
 * Terminal the telephone calls terminates. The TerminalConnection object
 * specification provides further information.
 * <p>
 * Below is a description of each Connection state in real-world terms. These
 * real-world descriptions have no bearing on the specifications of methods,
 * they only serve to provide a more intuitive understanding of what is going
 * on.
 * <p>
 * The Connection.IDLE state is the initial state for all new Connections.
 * Connections which are in the Connection.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 Connection.IDLE state for
 * long, quickly transitioning to other states.
 * <p>
 * The Connection.DISCONNECTED state implies it is no longer part of the
 * telephone call, although its references to Call and Address still remain
 * valid. A Connection in the Connection.DISCONNECTED state is interpreted as
 * once previously belonging to this telephone call.
 * <p>
 * The Connection.INPROGRESS state implies that the Connection, which
 * represents the destination end of a telephone call, is in the process of
 * contacting the destination side. Under certain circumstances, the Connection
 * may not progress beyond this state. Extension packages elaborate further on
 * this state in various situations.
 * <p>
 * The Connection.ALERTING state implies that the Address is being notified of
 * an incoming call. Typically, the Connection.ALERTING Connection will
 * answer the telephone call.
 * <p>
 * The Connection.CONNECTED 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 Connection.CONNECTED
 * state.
 * <p>
 * The Connection.UNKNOWN state implies that the implementation is unable to
 * determine the current state of the Connection. Typically, method are invalid
 * on Connections which are in the Connection.UNKNOWN state. Connections may
 * move in and out of the Connection.UNKNOWN state at any time.
 * <p>
 * The Connection.FAILED 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
 * Connection.FAILED state is because the party was busy.
 * <p>
 * With these loose, real-world meanings in the back of one's mind, the
 * Connection class defines a finite-state diagram which describes the
 * allowable Connection state transitions. This finite-state diagram must be
 * guaranteed by the implementation. Each method which causes a change in
 * a Connection state must be consistent with this state diagram. The finite
 * state diagram of the Connection states appears in graphical in the Overview
 * document for the Java Telephony API. Below, the finite state diagram appears
 * below in text:
 * <p>
 * All states may transition into and out of the UNKNOWN state which is not
 * represented below.
 * <p>
 * <UL>
 * <LI>IDLE ---> ALERTING | CONNECTED | DISCONNECTED | FAILED | INPROGRESS
 * <LI>INPROGRESS ---> ALERTING | CONNECTED | DISCONNECTED | FAILED
 * <LI>ALERTING ---> CONNECTED | DISCONNECTED | FAILED | UNKNOWN
 * <LI>CONNECTED ---> DISCONNECTED | FAILED | UNKNOWN
 * <LI>DISCONNECTED ---> UNKNOWN
 * <LI>FAILED ---> DISCONNECTED | UNKNOWN
 * </UL>
 * <p>
 * The Connection object supports the <EM>disconnect()</EM> method which drops
 * an entire Connection from the telephone call. The result of this method is
 * to move this Connection object into the Connection.DISCONNECTED state at
 * which time the address, nor any of its Terminals are associated with the
 * telephone call.
 * <p>
 * When a Connection object changes state, the application is notified via an
 * event through the CallObserver interface. A Call object is notified only
 * if the Connection is part of the Call. The CallObserver interface is also
 * notified when a new Connection has been created on a Call.
 * <p>
 * @see java.telephony.CallObserver
 */

public interface Connection {

  /**
   * The Connection.IDLE state is the initial state for all new Connections.
   * Connections which are in the Connection.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 Connection.IDLE state for
   * long, quickly transitioning to other states.
   */
  public static final int IDLE = 0x30;


  /**
   * The Connection.INPROGRESS state implies that the Connection, which
   * represents the destination end of a telephone call, is in the process of
   * contacting the destination side. Under certain circumstances, the
   * Connection may not progress beyon this state. Extension packages elaborate
   * further on this state in various situations.
   */
  public static final int INPROGRESS = 0x31;


  /**
   * The Connection.ALERTING state implies that the Address is being notified of
   * an incoming call. Typically, the Connection.ALERTING Connection will
   * answer the telephone call.
   */
  public static final int ALERTING = 0x32;


  /**
   * The Connection.CONNECTED state implies that a Connection and its Address is
   * actively part of a telephone call. In common terms, two people talking to