address.java

Java Telephony API .java程序

/*
#pragma ident "@(#)Address.java	1.2      96/11/03     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.AddressCapabilities;

/**
 * An Address object represents what we commonly think of as a "telephone
 * number." In more rare implementations where the underlying network is not
 * a telephony network, this address may represent something else. For example,
 * if the underlying network is IP, this address might represent an IP
 * address (e.g. 18.203.0.49). An Address object has a "name" which corresponds
 * to this telephony address which does not change throughout the lifetime of
 * the object.
 * <p>
 * An Address can be associated with a Call via a Connection object. The
 * Address object represents the logical endpoint of a telephone call. One the
 * most simplistic view, an application can see a telephone call as being from
 * one Address to another. When the Connection object moves into the
 * Connection.DISCONNECTED state, the Address object loses its reference to the
 * Connection object. This implies that the Connection object is no longer
 * reported via the <EM>Address.getConnection</EM> method.
 * <p>
 * Address objects are responsible for reporting information about telephone
 * calls which were created before the Provider. In other words, Address
 * object must report on all Connection 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>
 * Address objects may be associated with zero or many Terminal objects. An
 * Address which is associated with more than one Terminal object reflects the
 * fact that a telephone number may appear on more than one physical telephone
 * set.
 * <p>
 * All changes in an Address object are reported via the AddressObserver
 * interface. Applications instantiate an object which implements this
 * interface and begins this delivery of events to this object using the
 * <EM>Address.addObserver()</EM> method.
 * <p>
 * @see java.telephony.AddressObserver
 */

public interface Address {

  /**
   * Returns the name of the Address. Each Address possesses a unique
   * name. This name corresponds to its telephone number address string.
   * <p>
   * @return The name of the Address.
   * @exception PlatformException A platform-specific exception occurred.
   */
 public String getName()
    throws PlatformException;


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


  /**
   * Returns an array of Terminals associated with this Address object.
   * If no Terminals are associated with this Address <EM>getTerminals()</EM>
   * returns NULL.
   * <p>
   * @return An array of Terminal objects associated with this Address.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public Terminal[] getTerminals()
    throws PlatformException;


  /**
   * Returns an array of Connection object currently associated with this
   * Address object. When a Connection moves into the Connection.DISCONNECTED
   * state the Address object loses the reference. Therefore, all Connections
   * returned by this method will never be in the Connection.DISCONNECTED state.
   * If the Address has no Connections associated with it, this method
   * returns the null. The Provider must be in the Provider.IN_SERVICE state
   * in order 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 following post-conditions apply:
   * <p>
   * <OL>
   * <LI>Let Connection c[] = this.getConnections()
   * <LI>c == null or c.length >= 1
   * <LI>For all i, c[i].getState != Connection.DISCONNECTED
   * </OL>
   * <p>
   * @return An array of Connection objects associated with this Address.
   * @exception InvalidStateException The Provider is not IN_SERVICE.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public Connection[] getConnections()
    throws InvalidStateException, PlatformException;


  /**
   * Adds an observer to the Address. The AddressObserver reports all
   * Address-related state changes as events. The Address object will report
   * events to this AddressObserver object for the lifetime of the Address
   * object or until the observer is removed with the
   * <EM>Address.removeObserver()</EM> method.
   * <p>
   * If an application attempts to add an instance of an observer already
   * present on this Address, 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>
   * This method is valid anytime and has no pre-conditions.
   * <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(AddressObserver observer)
    throws ResourceUnavailableException, PlatformException;


  /**
   * Returns a list of all AddressObservers associated with this Address
   * object. If there are no observers associated with this Address 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 AddressObserver[] obs = this.getObservers()
   * <LI>obs == null or obs.length >= 1
   * </OL>
   * <p>
   * @return An array of AddressObserver objects associated with this
   * Address.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public AddressObserver[] getObservers()
    throws PlatformException;


  /**
   * Removes the given observer from the Address. If successful, the observer
   * will no longer receive events generated by this Address object.
   * <p>
   * Also, if an observer is not part of the Address, 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(AddressObserver observer)
    throws PlatformException;


  /**
   * Adds an observer to a Call object when this Address object first becomes
   * part of that Call. This method permits applications to select a Address
   * object in which they are interested and automatically have the
   * implementation attach an observer to each Call in which this Address
   * is included.
   * <p>
   * For example, an application may want to monitor the telephone call
   * activity associated with a particular address. In version 1.0 of the
   * Java Telephony specification, the application must first monitor the
   * Address for the AddrCallAtAddrEv event and them manually add an observer
   * to the new Call object.
   * <p>
   * In version 1.1 of the specification, the AddrCallAtAddrEv does not exist
   * and this method replaces the functionality described above. Instead of
   * monitoring for a AddrCallAtAddrEv event, this application simply uses
   * the Address.addCallObserver() method, and observer will be added to
   * new telephone calls at the Address automatically.
   * <p>
   * The CallObserver is removed from the call when the Call leaves this
   * Address.
   * <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 Address object behaves similarly to 
   * a call observer added on a Call object, except that it provides
   * a snapshot of all calls active on that Address.
   * @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 Address
   * 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 Address 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
   * Address.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public CallObserver[] getCallObservers()
    throws PlatformException;


  /**
   * Removes the given CallObserver from the Address. 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 Address, however it does not affect
   * CallObservers which have already been added to a Call.
   * <p>
   * Also, if a CallObserver is not part of the Address, 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 AddressCapabilities object with respect to a Terminal 
   * If null is passed as a Terminal parameter, the general/provider-wide
   * Address capabilities are returned.
   */
  public AddressCapabilities getAddressCapabilities(Terminal terminal)
    throws InvalidArgumentException, PlatformException;
}