jtapipeerfactory.java

Java Telephony API .java程序

/*
 * 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.lang.String;

/**
 * The JtapiPeerFactory class is a static class which is the primary means
 * used by applications to obtain a Provider object. The term 'peer' is used
 * throughout Java to mean "a particular platform-specific implementation of
 * a Java interface or API. This term has the same meaning for the Java
 * Telephony API. Applications are not permitted to create an instance of
 * the JtapiPeerFactory class.
 * <p>
 * Applications use this class to first obtain a class which implements the
 * <EM>java.telephony.JtapiPeer</EM> interface. This JtapiPeer interface
 * represents a paritcular vendor's implementation of the telephony API.
 * <p>
 * Once applications have a JtapiPeer object for a particular platform-
 * dependent implementation, they may obtain a Provider object via that
 * interface. The details of that interface are discussed in the specification
 * for the JtapiPeer interface.
 * <p>
 * Applications use the <EM>getJtapiPeer()</EM> method on this class to
 * obtain a JtapiPeer object. The argument to this method is a classname
 * which represents an object which implements the JtapiPeer interface. This
 * object and the classname under which it can be found must be supplied by
 * the vendor of the implementation. Note that this object is not a Provider,
 * however, this interface is used to obtain Providers from that particular
 * implementation.
 * <p>
 * The Java Telephony API places conventions on vendors on the classname
 * they use for their JtapiPeer object. This class name <EM>must</EM> begin
 * with the domain name assigned to the vendor in reverse order. Because the
 * space of domain names is managed, it ensures that collisions between two
 * different vendor's implementations will not happen. For example, an
 * implementation from Sun Microsystem's will have "com.sun" as the prefix
 * to its JtapiPeer class. After the reversed domain name, vendor's are
 * free to choose any class hierarchy they desire.
 * <p>
 * In basic environments, applications and users do not want the burden of
 * finding out the class name in order to use a particular implementation.
 * Therefore, the JtapiPeerFactory class supports a mechanism for applications
 * to obtain the default implementation for their system. If applications use
 * a null argument to the <EM>getJtapiPeer()</EM> method, they will be
 * returned the default installed implementation on their system.
 * <p>
 * <STRONG>Note:</STRONG> It is the responsibilty of implementation vendor's
 * to supply a version of this JtapiPeerFactory class which has a default
 * implementation programmed into it. During the installation of their
 * implementation on a system, this generic class should be replaced with their
 * own version which points to a default implementation. Implementation just
 * have to implement the private <EM>getDefaultJtapiPeerName()</EM> method.
 * The specification provides a generic version of this class with no default
 * provider built-in.
 */

public class JtapiPeerFactory {

  /**
   * Constructor for JtapiPeerFactory class. This is private because
   * applications are not permitted to create an instance of the
   * JtapiPeerFactory.
   */
  private JtapiPeerFactory()
  {
  }


  /**
   * Returns an instance of a JtapiPeer object given a fully qualified
   * classname of the class which implements the JtapiPeer object.
   * <p>
   * If no classname is provided (null), a default is picked by the
   * current implementation of this class.
   * <p>
   * @param _jtapiPeerName The classname of the JtapiPeer object class.
   * @return An instance of the JtapiPeer object.
   * @exception JtapiPeerUnavailableException Indicates that the JtapiPeer
   * specified by the classname is not available.
   */
  public synchronized static JtapiPeer getJtapiPeer(String _jtapiPeerName)
    throws JtapiPeerUnavailableException
  {

    String jtapiPeerName;
    Class jtapiPeerClass;
    String errmsg;
    JtapiPeer jtapiPeer;

    // If _jtapiPeerName is null set it to a default jtapiPeer name
    if (_jtapiPeerName == null)
    {
        jtapiPeerName = getDefaultJtapiPeerName();
    }
    else
    {
        jtapiPeerName = _jtapiPeerName;
    }

    try
    {
      jtapiPeerClass = Class.forName(jtapiPeerName);

      // Instantiate an instance of this class and cast it to the JtapiPeer
      // interface. If the class does not support the JtapiPeer interface, an
      // exception will be thrown because of the case, in addition to the
      // exceptions thrown from the newInstance() method.
      try {
	jtapiPeer = (JtapiPeer)jtapiPeerClass.newInstance();
      }
      catch (Exception e) {
	errmsg = "JtapiPeer: " + jtapiPeerName + " could not be instantiated.";
	throw new JtapiPeerUnavailableException(errmsg);
      }
      return jtapiPeer;
    } catch (Exception e)
    {
        errmsg = "JtapiPeer: " + jtapiPeerName + " does not exist.";
        throw new JtapiPeerUnavailableException(errmsg);
    }
  }


  /**
   * Returns a default JtapiPeer name. This method should be defined by each
   * vendor and a version of this class should be installed when the
   * particular implementation is installed on a system.
   */
  private static String getDefaultJtapiPeerName()
  {
    String JtapiPeerName = "";
    // Implementation will add code here to return default JtapiPeer name.
    return(JtapiPeerName);
  }
}