[Ejtools-cvs] CVS: thirdparty/sun/jsr88/src/main/javax/enterprise/deploy/spi/factories DeploymentFactory.java,NONE,1.1 DeploymentFactoryManager.java,NONE,1.1 DeploymentFactoryManager.java.new,NONE,1.1

[Laurent E. <let...@us...>]

Update of /cvsroot/ejtools/thirdparty/sun/jsr88/src/main/javax/enterprise/deploy/spi/factories
In directory usw-pr-cvs1:/tmp/cvs-serv31212/sun/jsr88/src/main/javax/enterprise/deploy/spi/factories

Added Files:
	DeploymentFactory.java DeploymentFactoryManager.java 
	DeploymentFactoryManager.java.new 
Log Message:
Initial Import

--- NEW FILE: DeploymentFactory.java ---

package javax.enterprise.deploy.spi.factories;

import javax.enterprise.deploy.spi.DeploymentManager;
import javax.enterprise.deploy.spi.exceptions.DeploymentManagerCreationException;

/**
 * The DeploymentFactory interface is a deployment driver for a    
 * J2EE plaform product.  It returns a DeploymentManager object
 * which represents a connection to a specific J2EE platform
 * product.
 *
 * <p> Each application server vendor must provide an implementation 
 *  of this class in order for the J2EE Deployment API to work 
 *  with their product.
 *
 * <p> The class implementing this interface should have a public
 * no-argument constructor, and it should be stateless (two instances
 * of the class should always behave the same).  It is suggested but
 * not required that the class have a static initializer that registers
 * an instance of the class with the DeploymentFactoryManager class.
 *
 * <p> A <tt>connected</tt> or <tt>disconnected</tt> DeploymentManager 
 * can be requested.  A DeploymentManager that runs connected to the 
 * platform can provide access to J2EE resources. A DeploymentManager 
 * that runs disconnected only provides module deployment configuration 
 * support. 
 *
 * @see DeploymentFactoryManager
 */
public interface DeploymentFactory 
{
    /**
     * Tests whether this factory can create a DeploymentManager
     * object based on the specificed URI.  This does not indicate
     * whether such an attempt will be successful, only whether the
     * factory can handle the uri. 
     * @param uri The uri to check
     * @return <tt>true</tt> if the factory can handle the uri.
     */
    public boolean handlesURI(String uri);

    /**
     * Return a <tt>connected</tt> DeploymentManager instance.
     *
     * @param uri The URI that specifies the connection parameters
     * @param username An optional username (may be <tt>null</tt> if
     *        no authentication is required for this platform).
     * @param password An optional password (may be <tt>null</yy> if
     *        no authentication is required for this platform).
     * @return A ready DeploymentManager instance.
     * @throws DeploymentManagerCreationException  occurs when a 
     *        DeploymentManager could not be returned (server down, 
     *        unable to authenticate, etc).
     */
    public DeploymentManager getDeploymentManager(String uri, 
            String username, String password) 
            throws DeploymentManagerCreationException;

    /**
     * Return a <tt>disconnected</tt> DeploymentManager instance. 
     *
     * @param uri the uri of the DeploymentManager to return.
     * @return A DeploymentManager <tt>disconnected</tt> instance.
     * @throws DeploymentManagerCreationException occurs if the 
     *         DeploymentManager could not be created.
     */
    public DeploymentManager getDisconnectedDeploymentManager(String uri) 
            throws DeploymentManagerCreationException;

    /**
     * Provide a string with the name of this vendor's DeploymentManager.
     * @return the name of the vendor's DeploymentManager.
     */
    public String getDisplayname();

    /**
     * Provide a string identifying version of this vendor's 
     * DeploymentManager.
     * @return the name of the vendor's DeploymentManager.
     */
    public String getProductVersion();
}

--- NEW FILE: DeploymentFactoryManager.java ---

package javax.enterprise.deploy.spi.factories;

import java.util.ArrayList;
import java.util.List;
import javax.enterprise.deploy.spi.DeploymentManager;
import javax.enterprise.deploy.spi.exceptions.DeploymentManagerCreationException;

/**
 * The DeploymentFactoryManager is a central registry for 
 * J2EE deployment connections.  The DeploymentFactoryManager 
 * retains references to deployment factories preloaded and 
 * explicitly loaded by this class.
 *
 * <p>The Deployer requests a <tt>connected</tt> DeploymentManager
 * instance by providing a  URI which indicates the desired traget 
 * product.  The appropriate factory will try to make the connection 
 * with the URI.
 *
 * <p>To acquire a <tt>disconnected</tt> DeploymentManager the tool 
 * requests the list of available deployment factories by calling 
 * getDeploymentFactories. The tool calls a returned DeploymentFactory 
 * object's getDeploymentManager method with no arguments to get a 
 * disconnected DeploymentManager.
 *
 * <p>Typically each DeploymentFactory class will register itself in
 * a static initializer, so the class only needs to be loaded in order
 * for it to be registered.  Class names may be listed in the system
 * property "javax.enterprise.deploy.factories.factories" and they will be
 * automatically registered.</p>
 *
 * <p>Here is an example of the usage:</p>
 * <PRE>
 *
 *     DeploymentManager manager;
 *     String url = "deployer:weblogic:myserver:9999";
 *     String user = "admin";
 *     String password = "pw";
 *     manager = DeploymentFactoryManager.getDeploymentManager(url, 
 *           user, password);
 *     if(manager != null) {
 *         ...  // Deploy an application
 *     }
 * </PRE>
 */
public interface DeploymentFactoryManager 
{
    /**
     * Registers a DeploymentFactory so it will be able to handle
     * requests.
     */
    public void registerDeploymentFactory(DeploymentFactory factory); 

    /**
     * Retrieve the lists of currently registered DeploymentFactories.
     *
     * @return the list of DeploymentFactory objects or 'null' if there
     *         are none.
     */
    public DeploymentFactory[] getDeploymentFactories(); 

    /**
     * Return a <tt>disconnected</tt> DeploymentManager instance.
     *
     * @param uri identifier of the disconnected DeploymentManager to
     *             return.
     * @return A DeploymentManager instance.
     * @throws DeploymentDriverException  occurs if the DeploymentManager
     *         could not be created.
     */
    public DeploymentManager getDisconnectedDeploymentManager(String uri)
                  throws DeploymentManagerCreationException;

    /**
     * Retrieves a DeploymentManager instance to use for deployment.
     * The caller provides a URI and optional username and password, 
     * and all registered DeploymentFactories will be checked.  The 
     * first one to understand the URI provided will attempt to 
     * initiate a server connection and return a ready DeploymentManager
     * instance.
     *
     * @param uri The uri to check
     * @param username An optional username (may be <tt>null</tt> if
     *        no authentication is required for this platform).
     * @param password An optional password (may be <tt>null</yy> if
     *        no authentication is required for this platform).
     * @return A ready DeploymentManager instance.
     * @throws DeploymentManagerCreationException
     *         Occurs when the factory appropriate to the specified URI
     *         was unable to initialize a DeploymentManager instance
     *         (server down, unable to authenticate, etc.).
     */
    public DeploymentManager getDeploymentManager(String uri, 
          String username, String password) 
          throws DeploymentManagerCreationException; 
}

--- NEW FILE: DeploymentFactoryManager.java.new ---

package javax.enterprise.deploy.spi.factories;

import java.util.ArrayList;
import java.util.List;
import javax.enterprise.deploy.spi.DeploymentManager;
import javax.enterprise.deploy.spi.exceptions.DeploymentManagerCreationException;

/**
 *  The DeploymentFactoryManager is a central registry for J2EE deployment
 *  connections. The DeploymentFactoryManager retains references to deployment
 *  factories preloaded and explicitly loaded by this class. <p>
 *
 *  The Deployer requests a <tt>connected</tt> DeploymentManager instance by
 *  providing a URI which indicates the desired traget product. The appropriate
 *  factory will try to make the connection with the URI. <p>
 *
 *  To acquire a <tt>disconnected</tt> DeploymentManager the tool requests the
 *  list of available deployment factories by calling getDeploymentFactories.
 *  The tool calls a returned DeploymentFactory object's getDeploymentManager
 *  method with no arguments to get a disconnected DeploymentManager. <p>
 *
 *  Typically each DeploymentFactory class will register itself in a static
 *  initializer, so the class only needs to be loaded in order for it to be
 *  registered. Class names may be listed in the system property
 *  "javax.enterprise.deploy.factories.factories" and they will be automatically
 *  registered.</p> <p>
 *
 *  Here is an example of the usage:</p> <PRE>
 *
 *     DeploymentManager manager;
 *     String url = "deployer:weblogic:myserver:9999";
 *     String user = "admin";
 *     String password = "pw";
 *     manager = DeploymentFactoryManager.getDeploymentManager(url,
 *           user, password);
 *     if(manager != null) {
 *         ...  // Deploy an application
 *     }
 * </PRE>
 *
 * @author     laurent
 * @created    23 mars 2002
 */
public class DeploymentFactoryManager
{
   /**  Description of the Field */
   private static java.util.Vector drivers = new java.util.Vector();
   /**  Description of the Field */
   private static boolean initialized = false;


   /**  Prevent the DriverManager class from being instantiated. */
   private DeploymentFactoryManager() { }


   /**
    *  Retrieve the lists of currently registered DeploymentFactories.
    *
    * @return    the list of DeploymentFactory objects or 'null' if there are
    *      none.
    */
   public static DeploymentFactory[] getDeploymentFactories();


   /**
    *  Return a <tt>disconnected</tt> DeploymentManager instance.
    *
    * @param  uri                                     identifier of the
    *      disconnected DeploymentManager to return.
    * @return                                         A DeploymentManager
    *      instance.
    * @exception  DeploymentManagerCreationException  Description of Exception
    * @throws  DeploymentDriverException              occurs if the
    *      DeploymentManager could not be created.
    */
   public static DeploymentManager getDisconnectedDeploymentManager(String uri) throws DeploymentManagerCreationException;


   /**
    *  Retrieves a DeploymentManager instance to use for deployment. The caller
    *  provides a URI and optional username and password, and all registered
    *  DeploymentFactories will be checked. The first one to understand the URI
    *  provided will attempt to initiate a server connection and return a ready
    *  DeploymentManager instance.
    *
    * @param  uri                                  The uri to check
    * @param  username                             An optional username (may be
    *      <tt>null</tt> if no authentication is required for this platform).
    * @param  password                             An optional password (may be
    *      <tt>null</yy> if no authentication is required for this platform).
    * @return                                      A ready DeploymentManager
    *      instance.
    * @throws  DeploymentManagerCreationException  Occurs when the factory
    *      appropriate to the specified URI was unable to initialize a
    *      DeploymentManager instance (server down, unable to authenticate,
    *      etc.).
    */
   public static DeploymentManager getDeploymentManager(String uri, String username, String password) throws DeploymentManagerCreationException;


   /**
    *  Registers a DeploymentFactory so it will be able to handle requests.
    *
    * @param  factory  Description of Parameter
    */
   public static void registerDeploymentFactory(DeploymentFactory factory);
}