001: /*
002: * Copyright 1999,2004 The Apache Software Foundation.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.apache.catalina;
018:
019: import java.io.IOException;
020: import java.net.URL;
021:
022: /**
023: * A <b>Deployer</b> is a specialized Container into which web applications
024: * can be deployed and undeployed. Such a Container will create and install
025: * child Context instances for each deployed application. The unique key
026: * for each web application will be the context path to which it is attached.
027: *
028: * @author Craig R. McClanahan
029: * @version $Revision: 1.4 $ $Date: 2004/04/12 22:05:15 $
030: */
031:
032: /* public interface Deployer extends Container { */
033: public interface Deployer {
034:
035: // ----------------------------------------------------- Manifest Constants
036:
037: /**
038: * The ContainerEvent event type sent when a new application is
039: * being installed by <code>install()</code>, before it has been
040: * started.
041: */
042: public static final String PRE_INSTALL_EVENT = "pre-install";
043:
044: /**
045: * The ContainerEvent event type sent when a new application is
046: * installed by <code>install()</code>, after it has been started.
047: */
048: public static final String INSTALL_EVENT = "install";
049:
050: /**
051: * The ContainerEvent event type sent when an existing application is
052: * removed by <code>remove()</code>.
053: */
054: public static final String REMOVE_EVENT = "remove";
055:
056: // --------------------------------------------------------- Public Methods
057:
058: /**
059: * Return the name of the Container with which this Deployer is associated.
060: */
061: public String getName();
062:
063: /**
064: * Install a new web application, whose web application archive is at the
065: * specified URL, into this container with the specified context path.
066: * A context path of "" (the empty string) should be used for the root
067: * application for this container. Otherwise, the context path must
068: * start with a slash.
069: * <p>
070: * If this application is successfully installed, a ContainerEvent of type
071: * <code>INSTALL_EVENT</code> will be sent to all registered listeners,
072: * with the newly created <code>Context</code> as an argument.
073: *
074: * @param contextPath The context path to which this application should
075: * be installed (must be unique)
076: * @param war A URL of type "jar:" that points to a WAR file, or type
077: * "file:" that points to an unpacked directory structure containing
078: * the web application to be installed
079: *
080: * @exception IllegalArgumentException if the specified context path
081: * is malformed (it must be "" or start with a slash)
082: * @exception IllegalStateException if the specified context path
083: * is already attached to an existing web application
084: * @exception IOException if an input/output error was encountered
085: * during installation
086: */
087: public void install(String contextPath, URL war) throws IOException;
088:
089: /**
090: * <p>Install a new web application, whose context configuration file
091: * (consisting of a <code><Context></code> element) and web
092: * application archive are at the specified URLs.</p>
093: *
094: * <p>If this application is successfully installed, a ContainerEvent
095: * of type <code>INSTALL_EVENT</code> will be sent to all registered
096: * listeners, with the newly created <code>Context</code> as an argument.
097: * </p>
098: *
099: * @param config A URL that points to the context configuration file to
100: * be used for configuring the new Context
101: * @param war A URL of type "jar:" that points to a WAR file, or type
102: * "file:" that points to an unpacked directory structure containing
103: * the web application to be installed
104: *
105: * @exception IllegalArgumentException if one of the specified URLs is
106: * null
107: * @exception IllegalStateException if the context path specified in the
108: * context configuration file is already attached to an existing web
109: * application
110: * @exception IOException if an input/output error was encountered
111: * during installation
112: */
113: public void install(URL config, URL war) throws IOException;
114:
115: /**
116: * Installs a new web application from the web application archive at the
117: * specified URL, which must contain a META-INF/context.xml context
118: * configuration file (consisting of a <code><Context></code>
119: * element).
120: *
121: * <p>The web application is installed at the path specified inside the
122: * embedded META-INF/context.xml. The docBase (if any) specified inside the
123: * embedded META-INF/context.xml is overridden with the web application's
124: * location.
125: *
126: * <p>If the installation succeeds, a ContainerEvent of type
127: * <code>INSTALL_EVENT</code> is sent to all registered listeners,
128: * with the newly created <code>Context</code> as its argument.
129: *
130: * @param war URL pointing to web application location (WAR-packaged or
131: * unpacked directory)
132: *
133: * @exception IllegalArgumentException if <code>war</code> is null, or if
134: * the deployment host does not support any context.xml
135: * configuration files
136: * @exception IllegalStateException if the context path specified in the
137: * context configuration file is already in use by an existing
138: * web application
139: * @exception IOException if an input/output error was encountered
140: * during installation
141: */
142: public void install(URL war) throws IOException;
143:
144: /**
145: * Return the Context for the deployed application that is associated
146: * with the specified context path (if any); otherwise return
147: * <code>null</code>.
148: *
149: * @param contextPath The context path of the requested web application
150: */
151: public Context findDeployedApp(String contextPath);
152:
153: /**
154: * Return the context paths of all deployed web applications in this
155: * Container. If there are no deployed applications, a zero-length
156: * array is returned.
157: */
158: public String[] findDeployedApps();
159:
160: /**
161: * Remove an existing web application, attached to the specified context
162: * path. If this application is successfully removed, a
163: * ContainerEvent of type <code>REMOVE_EVENT</code> will be sent to all
164: * registered listeners, with the removed <code>Context</code> as
165: * an argument.
166: *
167: * @param contextPath The context path of the application to be removed
168: *
169: * @exception IllegalArgumentException if the specified context path
170: * is malformed (it must be "" or start with a slash)
171: * @exception IllegalArgumentException if the specified context path does
172: * not identify a currently installed web application
173: * @exception IOException if an input/output error occurs during
174: * removal
175: */
176: public void remove(String contextPath) throws IOException;
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. Deletes the web application war file and/or directory
184: * if they exist in the Host's appBase.
185: *
186: * @param contextPath The context path of the application to be removed
187: * @param undeploy boolean flag to remove web application from server
188: *
189: * @exception IllegalArgumentException if the specified context path
190: * is malformed (it must be "" or start with a slash)
191: * @exception IllegalArgumentException if the specified context path does
192: * not identify a currently installed web application
193: * @exception IOException if an input/output error occurs during
194: * removal
195: */
196: public void remove(String contextPath, boolean undeploy)
197: throws IOException;
198:
199: /**
200: * Start an existing web application, attached to the specified context
201: * path. Only starts a web application if it is not running.
202: *
203: * @param contextPath The context path of the application to be started
204: *
205: * @exception IllegalArgumentException if the specified context path
206: * is malformed (it must be "" or start with a slash)
207: * @exception IllegalArgumentException if the specified context path does
208: * not identify a currently installed web application
209: * @exception IOException if an input/output error occurs during
210: * startup
211: */
212: public void start(String contextPath) throws IOException;
213:
214: /**
215: * Stop an existing web application, attached to the specified context
216: * path. Only stops a web application if it is running.
217: *
218: * @param contextPath The context path of the application to be stopped
219: *
220: * @exception IllegalArgumentException if the specified context path
221: * is malformed (it must be "" or start with a slash)
222: * @exception IllegalArgumentException if the specified context path does
223: * not identify a currently installed web application
224: * @exception IOException if an input/output error occurs while stopping
225: * the web application
226: */
227: public void stop(String contextPath) throws IOException;
228:
229: /**
230: * Returns true if context.xml config files are supported.
231: *
232: * @return true of context.xml config files are supported, false otherwise
233: */
234: public boolean isDeployXML();
235:
236: }
|