001: /*
002: * $Header: /home/cvs/jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/Deployer.java,v 1.6 2002/04/09 23:48:21 craigmcc Exp $
003: * $Revision: 1.6 $
004: * $Date: 2002/04/09 23:48:21 $
005: *
006: * ====================================================================
007: *
008: * The Apache Software License, Version 1.1
009: *
010: * Copyright (c) 1999 The Apache Software Foundation. All rights
011: * reserved.
012: *
013: * Redistribution and use in source and binary forms, with or without
014: * modification, are permitted provided that the following conditions
015: * are met:
016: *
017: * 1. Redistributions of source code must retain the above copyright
018: * notice, this list of conditions and the following disclaimer.
019: *
020: * 2. Redistributions in binary form must reproduce the above copyright
021: * notice, this list of conditions and the following disclaimer in
022: * the documentation and/or other materials provided with the
023: * distribution.
024: *
025: * 3. The end-user documentation included with the redistribution, if
026: * any, must include the following acknowlegement:
027: * "This product includes software developed by the
028: * Apache Software Foundation (http://www.apache.org/)."
029: * Alternately, this acknowlegement may appear in the software itself,
030: * if and wherever such third-party acknowlegements normally appear.
031: *
032: * 4. The names "The Jakarta Project", "Tomcat", and "Apache Software
033: * Foundation" must not be used to endorse or promote products derived
034: * from this software without prior written permission. For written
035: * permission, please contact apache@apache.org.
036: *
037: * 5. Products derived from this software may not be called "Apache"
038: * nor may "Apache" appear in their names without prior written
039: * permission of the Apache Group.
040: *
041: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
042: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
043: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
044: * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
045: * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
046: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
047: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
048: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
049: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
050: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
051: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
052: * SUCH DAMAGE.
053: * ====================================================================
054: *
055: * This software consists of voluntary contributions made by many
056: * individuals on behalf of the Apache Software Foundation. For more
057: * information on the Apache Software Foundation, please see
058: * <http://www.apache.org/>.
059: *
060: * [Additional notices, if required by prior licensing conditions]
061: *
062: */
063:
064: package org.apache.catalina;
065:
066: import java.io.IOException;
067: import java.net.URL;
068:
069: /**
070: * A <b>Deployer</b> is a specialized Container into which web applications
071: * can be deployed and undeployed. Such a Container will create and install
072: * child Context instances for each deployed application. The unique key
073: * for each web application will be the context path to which it is attached.
074: *
075: * @author Craig R. McClanahan
076: * @version $Revision: 1.6 $ $Date: 2002/04/09 23:48:21 $
077: */
078:
079: /* public interface Deployer extends Container { */
080: public interface Deployer {
081:
082: // ----------------------------------------------------- Manifest Constants
083:
084: /**
085: * The ContainerEvent event type sent when a new application is
086: * being installed by <code>install()</code>, before it has been
087: * started.
088: */
089: public static final String PRE_INSTALL_EVENT = "pre-install";
090:
091: /**
092: * The ContainerEvent event type sent when a new application is
093: * installed by <code>install()</code>, after it has been started.
094: */
095: public static final String INSTALL_EVENT = "install";
096:
097: /**
098: * The ContainerEvent event type sent when an existing application is
099: * removed by <code>remove()</code>.
100: */
101: public static final String REMOVE_EVENT = "remove";
102:
103: // --------------------------------------------------------- Public Methods
104:
105: /**
106: * Return the name of the Container with which this Deployer is associated.
107: */
108: public String getName();
109:
110: /**
111: * Install a new web application, whose web application archive is at the
112: * specified URL, into this container with the specified context path.
113: * A context path of "" (the empty string) should be used for the root
114: * application for this container. Otherwise, the context path must
115: * start with a slash.
116: * <p>
117: * If this application is successfully installed, a ContainerEvent of type
118: * <code>INSTALL_EVENT</code> will be sent to all registered listeners,
119: * with the newly created <code>Context</code> as an argument.
120: *
121: * @param contextPath The context path to which this application should
122: * be installed (must be unique)
123: * @param war A URL of type "jar:" that points to a WAR file, or type
124: * "file:" that points to an unpacked directory structure containing
125: * the web application to be installed
126: *
127: * @exception IllegalArgumentException if the specified context path
128: * is malformed (it must be "" or start with a slash)
129: * @exception IllegalStateException if the specified context path
130: * is already attached to an existing web application
131: * @exception IOException if an input/output error was encountered
132: * during installation
133: */
134: public void install(String contextPath, URL war) throws IOException;
135:
136: /**
137: * <p>Install a new web application, whose context configuration file
138: * (consisting of a <code><Context></code> element) and web
139: * application archive are at the specified URLs.</p>
140: *
141: * <p>If this application is successfully installed, a ContainerEvent
142: * of type <code>INSTALL_EVENT</code> will be sent to all registered
143: * listeners, with the newly created <code>Context</code> as an argument.
144: * </p>
145: *
146: * @param config A URL that points to the context configuration file to
147: * be used for configuring the new Context
148: * @param war A URL of type "jar:" that points to a WAR file, or type
149: * "file:" that points to an unpacked directory structure containing
150: * the web application to be installed
151: *
152: * @exception IllegalArgumentException if one of the specified URLs is
153: * null
154: * @exception IllegalStateException if the context path specified in the
155: * context configuration file is already attached to an existing web
156: * application
157: * @exception IOException if an input/output error was encountered
158: * during installation
159: */
160: public void install(URL config, URL war) throws IOException;
161:
162: /**
163: * Return the Context for the deployed application that is associated
164: * with the specified context path (if any); otherwise return
165: * <code>null</code>.
166: *
167: * @param contextPath The context path of the requested web application
168: */
169: public Context findDeployedApp(String contextPath);
170:
171: /**
172: * Return the context paths of all deployed web applications in this
173: * Container. If there are no deployed applications, a zero-length
174: * array is returned.
175: */
176: public String[] findDeployedApps();
177:
178: /**
179: * Remove an existing web application, attached to the specified context
180: * path. If this application is successfully removed, a
181: * ContainerEvent of type <code>REMOVE_EVENT</code> will be sent to all
182: * registered listeners, with the removed <code>Context</code> as
183: * an argument.
184: *
185: * @param contextPath The context path of the application to be removed
186: *
187: * @exception IllegalArgumentException if the specified context path
188: * is malformed (it must be "" or start with a slash)
189: * @exception IllegalArgumentException if the specified context path does
190: * not identify a currently installed web application
191: * @exception IOException if an input/output error occurs during
192: * removal
193: */
194: public void remove(String contextPath) throws IOException;
195:
196: /**
197: * Start an existing web application, attached to the specified context
198: * path. Only starts a web application if it is not running.
199: *
200: * @param contextPath The context path of the application to be started
201: *
202: * @exception IllegalArgumentException if the specified context path
203: * is malformed (it must be "" or start with a slash)
204: * @exception IllegalArgumentException if the specified context path does
205: * not identify a currently installed web application
206: * @exception IOException if an input/output error occurs during
207: * startup
208: */
209: public void start(String contextPath) throws IOException;
210:
211: /**
212: * Stop an existing web application, attached to the specified context
213: * path. Only stops a web application if it is running.
214: *
215: * @param contextPath The context path of the application to be stopped
216: *
217: * @exception IllegalArgumentException if the specified context path
218: * is malformed (it must be "" or start with a slash)
219: * @exception IllegalArgumentException if the specified context path does
220: * not identify a currently installed web application
221: * @exception IOException if an input/output error occurs while stopping
222: * the web application
223: */
224: public void stop(String contextPath) throws IOException;
225:
226: }
|