terminal.java

Java Telephony API .java程序

/*
#pragma ident "@(#)Terminal.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.TerminalCapabilities;

/**
 * A Terminal represents a physical hardware endpoint connected to the
 * telephony network. An example of a Terminal is a telephone set, but
 * a Terminal does not have to take the form of this limited and traditional
 * example. A wide variety of hardware can act as Terminals.
 * <p>
 * Terminal objects are distinguished from one another by their names; each
 * Terminal has a unique name. How Terminals are named within a Provider
 * is up to the implementaion. Typically, when choosing a Terminal,
 * applications simply obtain the names of the available Terminals. This list
 * is presented to the user who will be able to identify the desired
 * Terminal. Typically, the user will have no trouble identifying the desired
 * Terminal. Therefore, the portability of applications is not affected by
 * the lack of standardization of Terminal names. A common way to name
 * Terminals is by a "primary" telephone number Address at that Terminal. This
 * is only an example, however, and implementations need not name their
 * Terminals in this manner.
 * <p>
 * There may be many Terminals associated with a Provider. The application
 * obtains a list of these Terminals via the <EM>Provider.getTerminals()</EM>
 * method. Applications may obtain a specific Terminal object given its name
 * via the <EM>Provider.getTerminal(name)</EM> method. These two methods
 * represent the manner in which applications obtain Terminal objects.
 * Applications never create Terminal objects, either through the Provider or
 * using the "new" constructor.
 * <p>
 * A Terminal may have one or more Address objects associated with it. In
 * real-terms, this corresponds to telephones having multiple telephone numbers
 * associated with a Terminal. Address objects are the logical endpoints of
 * telephone calls, described by a Connection object between the Call and
 * Address. Terminals act as the physical endpoint of a Call. A Connection
 * object may have zero or more TerminalConnection objects. These
 * TerminalConnection objects describe which Terminals act as the physical
 * endpoint of the Call for that Connection's Address object.
 * <p>
 * Terminal objects are responsible for reporting information about telephone 
 * calls which were created before the Provider. In other words, Terminal
 * object must report on all TerminalConnection objects which are part of all
 * telephone calls in the Provider's domain--even if these telephone Calls were
 * created before the Provider was created.
 * <p>
 * More than one Terminal object may share the same Address object. In real-
 * terms, this corresponds to a telephone number appearing on more than one
 * telephone terminal. Because each Terminal may be in a different state w.r.t
 * the telephone call, Terminal objects are associated with Calls via the
 * TerminalConnection object. The TerminalConnection object describes the
 * specific state of the Terminal with respect to the Call.
 * <p>
 * All changes in a Terminal object are reported via the TerminalObserver
 * interface. Applications instantiate an object which implements this
 * interface and begins this delivery of events to this object using the
 * <EM>Terminal.addObserver()</EM> method.
 * <p>
 * @see java.telephony.TerminalObserver
 */

public interface Terminal {

  /**
   * Returns the name of the Terminal. Each Terminal possesses a unique
   * name, which is assigned to it by the JTAPI implementation.
   * <p>
   * @return The name of the Terminal.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public String getName()
    throws PlatformException;


  /**
   * Returns the Provider associated with this Terminal. This Provider object
   * is valid throughout the lifetime of the Terminal and does not change
   * once the Terminal is created.
   * <p>
   * @return The Provider associated with this Terminal.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public Provider getProvider()
    throws PlatformException;


  /**
   * Returns an array of Address objects associated with this Terminal object.
   * The Terminal object must have at least one Address object associated
   * with it. The Provider must be in the Provider.IN_SERVICE state for this
   * method to be valid.
   * <p>
   * The pre-conditions for this method are:
   * <OL>
   * <LI>(this.getProvider()).getState() == Provider.IN_SERVICE.
   * </OL>
   * <p>
   * The post-conditions for this method are:
   * <OL>
   * <LI>(this.getProvider()).getState() == Provider.IN_SERVICE
   * <LI>Let Address[] addrs = this.getAddresses()
   * <LI>addrs.length >= 1
   * </OL>
   * <p>
   * @return An array of Address objects associated with this Terminal.
   * @exception InvalidStateException The Provider is not IN_SERVICE.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public Address[] getAddresses()
    throws InvalidStateException, PlatformException;


  /**
   * Returns an array of TerminalConnection objects associated with this
   * Terminal. Once a TerminalConnection is added to a Terminal, the Terminal
   * maintains a reference until the TerminalConnection moves into the
   * TerminalConnection.DROPPED state. The Provider must be IN_SERVICE for
   * this method to be valid. If there are no TerminalConnections associated
   * with this Terminal, then this method returns null.
   * <p>
   * The pre-conditions for this method are:
   * <OL>
   * <LI>(this.getProvider()).getState() == Provider.IN_SERVICE
   * </OL>
   * <p>
   * The post-conditions for this method are:
   * <OL>
   * <LI>(this.getProvider()).getState() == Provider.IN_SERVICE
   * <LI>Let TerminalConnection tc[] = this.getTerminalConnections()
   * <LI>tc == null or tc.length >= 1
   * <LI>For all i, tc[i].getState() != TerminalConnection.DROPPED
   * </OL>
   * <p>
   * @return An array of TerminalConnection objects associated with this
   * Terminal.
   * @exception InvalidStateException The Provider is not IN_SERVICE.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public TerminalConnection[] getTerminalConnections()
    throws InvalidStateException, PlatformException;


  /**
   * Adds an observer to the Terminal. The TerminalObserver reports all
   * Terminal-related state changes as events. The Terminal object will report
   * events to this TerminalObserver object for the lifetime of the Terminal
   * object or until the observer is removed with the
   * <EM>Terminal.removeObserver()</EM>.
   * <p>
   * If an application attempts to add an instance of an observer already
   * present on this Terminal, then repeated attempts to add the instance
   * of the observer will silently fail, i.e. multiple instances of an
   * observer are not added and no exception will be thrown.
   * <p>
   * There are no pre-conditions for this method.
   * <p>
   * The post-condition predicates for this method are:
   * <OL>
   * <LI>observer is an element of this.getObservers()
   * </OL>
   * <p>
   * @param observer The observer being added.
   * @exception ResourceUnavailableException The resource limit for the
   * numbers of observers has been exceeded.
   * @exception PlatformException A platform-specific exception occurred.
   */ 
  public void addObserver(TerminalObserver observer)
    throws ResourceUnavailableException, PlatformException;


  /**
   * Returns a list of all TerminalObservers associated with this Terminal object.
   * If there are no observers associated with this Terminal, this method
   * returns null.
   * <p>
   * There are no pre-conditions for this method.
   * <p>
   * The post-conditions for this method are:
   * <OL>
   * <LI>Let TerminalObserver[] obs = this.getObservers()
   * <LI>obs == null or obs.length >= 1
   * </OL>
   * <p>
   * @return An array of TerminalObserver objects associated with this
   * Terminal.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public TerminalObserver[] getObservers()
    throws PlatformException;


  /**
   * Removes the given observer from the Terminal. If successful, the observer
   * will no longer receive events generated by this Terminal object.
   * <p>
   * If an observer is not part of the Terminal, then this method
   * fails silently, i.e. no observer is removed an no exception is thrown.
   * <p>
   * There are no pre-conditions for this method.
   * <p>
   * The post-condition predicates for this method are:
   * <OL>
   * <LI>observer is not an element of this.getObservers()
   * </OL>
   * <p>
   * @param observer The observer which is being removed.
   * @exception PlatformException A platform-specific exception occurred.
   */ 
  public void removeObserver(TerminalObserver observer)
    throws PlatformException;


  /**
   * Adds an observer to a Call object when this Terminal object first becomes
   * part of that Call. This method permits applications to select a Terminal
   * object in which they are interested and automatically have the
   * implementation attach an observer to each Call in which this Terminal
   * is included.
   * <p>
   * For example, an application may want to monitor the telephony call
   * activity associated with a particular terminal. In version 1.0 of the
   * Java Telephony specification, the application must first monitor the
   * Terminal for the TermCallAtTermEv event and them manually add an observer
   * to the new Call object.
   * <p>
   * In version 1.1 of the specification, the TermCallAtTermEv does not exist
   * and this method replaces the functionality described above. Instead of
   * monitoring for a TermCallAtTermEv event, this application simply uses
   * the Terminal.addCallObserver() method, and observer will be added to
   * new telephone calls at the Terminal automatically.
   * <p>
   * The CallObserver is removed from the call when the Call leaves the
   * Terminal.
   * <p>
   * If an application attempts to add an instance of an observer already
   * present on the Call, then repeated attempts to add the instance
   * of the observer will silently fail, i.e. multiple instances of an
   * observer are not added and no exception will be thrown.
   * <p>
   * A call observer added on an Terminal object behaves similarly to 
   * A call observer added on a Call object, except that it provides
   * a snapshot of all calls active on that Terminal.
   * @see java.telephony.Call 
   * <p>
   * There are no pre-conditions for this method.
   * <p>
   * The post-condition predicates for this method are:
   * <OL>
   * <LI>observer is an element of this.getObservers()
   * </OL>
   * <p>
   * @param observer The observer being added.
   * @exception ResourceUnavailableException The resource limit for the
   * numbers of observers has been exceeded.
   * @exception PlatformException A platform-specific exception occurred.
   */ 
  public void addCallObserver(CallObserver observer)
    throws ResourceUnavailableException, PlatformException;


  /**
   * Returns a list of all CallObservers associated with this Terminal
   * object. That is, it returns a list of CallObserver object which have
   * been added via the <EM>addCallObserver()</EM> method. If there are no
   * Call observers associated with this Terminal object, this method returns
   * null.
   * <p>
   * There are no pre-conditions for this method.
   * <p>
   * The post-conditions for this method are:
   * <OL>
   * <LI>Let CallObserver[] obs = this.getCallObservers()
   * <LI>obs == null or obs.length >= 1
   * </OL>
   * <p>
   * @return An array of CallObserver objects associated with this
   * Terminal.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public CallObserver[] getCallObservers()
    throws PlatformException;


  /**
   * Removes the given CallObserver from the Terminal. In other words, it
   * removes a CallObserver which was added via the <EM>addCallObserver()</EM>
   * method. If successful, the observer will no longer be added to new
   * Calls which are presented to this Terminal, however it does not affect
   * CallObservers which have already been added to a Call.
   * <p>
   * Also, if a CallObserver is not part of the Terminal, then this method
   * fails silently, i.e. no observer is removed an no exception is thrown.
   * <p>
   * There are no pre-conditions for this method.
   * <p>
   * The post-condition predicates for this method are:
   * <OL>
   * <LI>observer is not an element of this.getCallObservers()
   * </OL>
   * <p>
   * @param observer The CallObserver which is being removed.
   * @exception PlatformException A platform-specific exception occurred.
   */ 
  public void removeCallObserver(CallObserver observer)
    throws PlatformException;


/**
  * Gets the TerminalConnectionCapabilities object with respect to a Terminal and an
  * Address.
  * If null is passed as a Terminal parameter, the general/provider-wide Terminal Connection 
  * capabilities are returned.
  * <p>
  */
  public TerminalCapabilities getTerminalCapabilities(Terminal terminal, Address address)
    throws InvalidArgumentException, PlatformException;
}