provider.java

Java Telephony API .java程序

/*
#pragma ident "@(#)Provider.java	1.34      97/02/06     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.*;
import  java.lang.*;

/**
 * A Provider represents the telephony-software-entity that interfaces with a 
 * telephony subsystem. The telephony subsystem could be a PBX connected to 
 * a server machine, or a telephony/fax card in a desktop machine or a 
 * networking technology such as IP.
 * <p>
 * A Provider instance is created and returned by the <EM>JtapiPeer</EM> 
 * method <EM>getProvider()</EM> which is given a string to describe the desired
 * Provider. This method sets up any needed communcation paths between the
 * application and the Provider object instance.
 * <p>
 * The Provider has methods for creating Call objects and obtaining Terminal
 * and Address objects. Applications cannot create their own instances of Call,
 * Terminal, Address, Connection, and TerminalConnection objects with the
 * "new" operator.
 * <p>
 * The Provider maintains lists of Call, Terminal, and Address objects it
 * knows about. Applications may create new Call objects using the
 * <EM>Provider.createCall()</EM> method. The Provider maintains a reference
 * to this new Call object until the Call object moves into the
 * Provider.INVALID state. Applications may obtain a list of all Call
 * objects known by the Provider (which are either in the Provider.IDLE or 
 * Provider.ACTIVE state) using the <EM>Provider.getCalls()</EM> method.
 * <p>
 * There may have been telephone calls present in the Provider's domain
 * before the Provider software object has been created by the application.
 * The Provider is still responsible, however, for reporting the existence
 * of these Calls when the application invokes the <EM>getCalls()</EM> method.
 * This principle applies to other objects as well. For example, the Address
 * object must report all Connections which are part of telephone calls even
 * if these Calls came into existence before the Provider.
 * <p>
 * Unlike Call objects, applications may not create Terminal or Address
 * objects. The Provider begins with knowledge of certain Terminal and Address
 * objects defined in the system. This list of Terminals and Addresses
 * represents those Terminals and Addresses within the Provider's domain.
 * This list is static once the Provider is created. The <EM>getTerminals()
 * </EM> and <EM>getAddresses()</EM> method returns these lists, respectively.
 * Other Addresses and Terminals may be created sometime during the operation
 * of the Provider when the Provider learns of new instances of these objects.
 * These new object, however, represent Addresses and Terminals outside the
 * Provider's domain. For example, if the Provider's domain is a PBX, the
 * Provider will know about all Addresses and Terminals in this PBX when the
 * Provider first starts. Any Addresses and Terminals it subsequently learns
 * about are outside this PBX. These Address and Terminal objects outside this
 * PBX are not reported via the <EM>getTerminals()</EM> and
 * <EM>getAddresses()</EM> methods.
 * <p>
 * The Provider may either be in the Provider.IN_SERVICE state, the
 * Provider.OUT_OF_SERVICE state, or the Provider.SHUTDOWN state. The Provider
 * state represents whether any action on that Provider or the objects
 * associated with the Provider are valid. The pre-condition that the Provider
 * state must be Provider.IN_SERVICE exists on most Java Telephony API object
 * methods and is noted in all instances. The Provider.OUT_OF_SERVICE state
 * indicates that the Provider is not available because of a temporary
 * condition not controlled by the application. The Provider.SHUTDOWN state
 * indicates that the Provider is permanently unavailable. The application may
 * use the <EM>Provider.shutdown()</EM> method to move the Provider into the
 * Provider.SHUTDOWN state itself or an external condition may cuase the
 * Provider to move into this state as well.
 * <p>
 * Each time a state changes occurs on a Provider object, the application is
 * notified via an <EM>event</EM>.  This event is reported via the
 * ProviderObserver interface. Applications instantiate objects which implement
 * the ProviderObject interface and use the <EM>Provider.addObserver()</EM>
 * method to begin the delivery of events. All Provider events reported via
 * this interface extend the ProviderEvent interface. Applications may then
 * query the event object returned for the specific state change. In the core
 * Provider API, the following generates events to the ProviderObserver:
 * when the Provider state changes to either Provider.IN_SERVICE,
 * Provider.OUT_OF_SERVICE, or Provider.SHUTDOWN.
 * <p>
 * It is not guaranteed or expected that objects (Call, Terminal, 
 * etc.) instantiated through one Provider will be usable with another
 * Provider. Thus an application that uses two providers must keep all the
 * objects relating to these providers separate.
 * <p>
 * @see java.telephony.JtapiPeer
 * @see java.telephony.ProviderObserver
 */

public interface Provider {

  /**
   * The Provider.IN_SERVICE state indicates that a Provider is currentl
   * available for use.
   */
  public static final int IN_SERVICE = 0x10;


  /** 
   * The Provider.OUT_OF_SERVICE state indicates that a Provider is temporarily
   * not available for use. Most methods in the Java Telephony API are invalid
   * when the Provider is in this state. Providers may come back IN_SERVICE
   * at any time, however, the application can take no direct action to cause
   * this change.
   */
  public static final int OUT_OF_SERVICE = 0x11;


  /**
   * The SHUTDOWN state indicates that a Provider is permanently no longer
   * available for use. Most methods in the Java TelephonyAPI are invalid when
   * the Provider is in this state.
   */
  public static final int SHUTDOWN = 0x12; 


  /**
   * Returns the current state of the Provider, either Provider.IN_SERVICE,
   * Provider.OUT_OF_SERVICE, or Provider.SHUTDOWN.
   * <p>
   * @return The current state of the provider.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public int getState()
    throws PlatformException;


  /**
   * Returns the unique string name of the Provider. Each different Provider must
   * have a unique string associated with it. This is the same string which the
   * application passed to the <EM>JtapiPeer.getProvider()</EM> method
   * to create this Provider instance.
   * <p>
   * @see java.telephony.JtapiPeer
   * <p>
   * @return The URL-string name of the Provider.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public String getName()
    throws PlatformException;
 

  /**
   * Returns an array of Call objects currently associated with the Provider.
   * When a Call moves into the Call.INVALID state, the Provider loses its
   * reference to this Call. Therefore, all Calls returned by this method
   * must either be in the Call.IDLE or Call.ACTIVE state. This method
   * returns null if the Provider has zero calls associated with it.
   * <p>
   * The pre-conditions for this method are:
   * <OL>
   * <LI>this.getState() == Provider.IN_SERVICE
   * </OL>
   * The post-conditions for this method are:
   * <OL>
   * <p>
   * <LI>this.getState() == Provider.IN_SERVICE
   * <LI>Let Calls calls[] = Provider.getCalls()
   * <LI>calls == null or calls.length >= 1
   * <LI>For all i, calls[i].getState() == Call.IDLE or Call.ACTIVE
   * </OL>
   * <p>
   * @return An array of Call objects currently known by this Provider.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public Call[] getCalls()
    throws PlatformException;


  /**
   * Returns an Address object which corresponds to the telephone number
   * string provided. If the provided name does not correspond to an
   * Address known by the Provider and within the Provider's domain,
   * the InvalidArgumentException is thrown. In other words, the Address
   * must appear in the list generated by Provider.getAddresses().
   * <p>
   * The pre-conditions for this method are:
   * <OL>
   * <LI>this.getState() == Provider.IN_SERVICE
   * <LI>Let Address addr = this.getAddress(number);
   * <LI>addr is an element of this.getAddresses();
   * </OL>
   * <p>
   * The post-conditions for this method are:
   * <OL>
   * <LI>this.getState() == Provider.IN_SERVICE
   * <LI>Let Address addr = this.getAddress(number);
   * <LI>addr is an element of this.getAddresses();
   * </OL>
   * <p>
   * @param number The telephone address string.
   * @return The Address object corresponding to the given telephone
   * number.
   * @exception InvalidArgumentException The name of the Address does not
   * correspond to the name of any Address object known to the Provider or
   * within the Provider's domain.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public Address getAddress(String number)
    throws InvalidArgumentException, PlatformException;


  /**
   * Returns a list of Addresses associated with the Provider and within the
   * Provider's domain. This list is static (i.e. is does not change) after
   * the Provider is first created. The Provider must be Provider.IN_SERVICE.
   * If no Address objects are associated with this Provider, then this method
   * returns null.
   * <p>
   * The pre-condition predicates for this method is:
   * <OL>
   * <LI>this.getState() == Provider.IN_SERVICE
   * </OL>
   * <p>
   * The post-condition predicates for this method is:
   * <OL>
   * <LI>this.getState() == Provider.IN_SERVICE
   * <LI>Let Address[] addr = this.getAddresses()
   * <LI>addr == null or addr.length >= 1
   * </OL>
   * <p>
   * @return An array of Addresses known by this provider.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public Address[] getAddresses()
    throws PlatformException;


  /**
   * Returns a list of Terminals associated with the Provider and within the
   * Provider's domain.  Each Terminal possesses a unique
   * name, which is assigned to it by the JTAPI implementation.
   * The Provider must be Provider.IN_SERVICE. If
   * there are no Terminals associated with this Provider, then this method
   * returns null.
   * <p>
   * The pre-condition predicate for this method is:
   * <OL>
   * <LI>this.getState() == Provider.IN_SERVICE
   * </OL>
   * <p>
   * The post-condition predicate for this method is:
   * <OL>
   * <LI>this.getState() == Provider.IN_SERVICE
   * <LI>Let Terminal[] term = this.getTerminals()
   * <LI>term == null or term.length >= 1
   * </OL>