001 /**
002 *
003 * Copyright 2003-2004 The Apache Software Foundation
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018 //
019 // This source code implements specifications defined by the Java
020 // Community Process. In order to remain compliant with the specification
021 // DO NOT add / change / or delete method signatures!
022 //
023
024 package javax.enterprise.deploy.spi;
025
026 import javax.enterprise.deploy.spi.exceptions.DConfigBeanVersionUnsupportedException;
027 import javax.enterprise.deploy.spi.exceptions.TargetException;
028 import javax.enterprise.deploy.spi.exceptions.InvalidModuleException;
029 import javax.enterprise.deploy.spi.status.ProgressObject;
030 import javax.enterprise.deploy.shared.DConfigBeanVersionType;
031 import javax.enterprise.deploy.shared.ModuleType;
032 import javax.enterprise.deploy.model.DeployableObject;
033 import java.io.File;
034 import java.io.InputStream;
035 import java.util.Locale;
036
037 /**
038 * The DeploymentManager object provides the core set of functions a J2EE platform
039 * must provide for J2EE application deployment. It provides server related
040 * information, such as, a list of deployment targets, and vendor unique runtime
041 * configuration information.
042 *
043 * @version $Rev: 46019 $ $Date: 2004-09-14 02:56:06 -0700 (Tue, 14 Sep 2004) $
044 */
045 public interface DeploymentManager {
046 /**
047 * Retrieve the list of deployment targets supported by this DeploymentManager.
048 *
049 * @return A list of deployment Target designators the user may select for
050 * application deployment or <code>null</code> if there are none.
051 *
052 * @throws IllegalStateException is thrown when the method is called when
053 * running in disconnected mode.
054 */
055 public Target[] getTargets() throws IllegalStateException;
056
057 /**
058 * Retrieve the list of J2EE application modules distributed to the identified
059 * targets and that are currently running on the associated server or servers.
060 *
061 * @param moduleType A predefined designator for a J2EE module type.
062 * @param targetList A list of deployment Target designators the user wants
063 * checked for module run status.
064 *
065 * @return An array of TargetModuleID objects representing the running modules
066 * or <code>null</code> if there are none.
067 *
068 * @throws TargetException occurs when an invalid Target was provided.
069 * @throws IllegalStateException is thrown when the method is called when running
070 * in disconnected mode.
071 */
072 public TargetModuleID[] getRunningModules(ModuleType moduleType, Target[] targetList) throws TargetException, IllegalStateException;
073
074 /**
075 * Retrieve the list of J2EE application modules distributed to the identified
076 * targets and that are currently not running on the associated server or servers.
077 *
078 * @param moduleType A predefined designator for a J2EE module type.
079 * @param targetList A list of deployment Target designators the user wants checked
080 * for module not running status.
081 *
082 * @return An array of TargetModuleID objects representing the non-running modules
083 * or <code>null</code> if there are none.
084 *
085 * @throws TargetException occurs when an invalid Target was provided.
086 * @throws IllegalStateException is thrown when the method is called when running
087 * in disconnected mode.
088 */
089 public TargetModuleID[] getNonRunningModules(ModuleType moduleType, Target[] targetList) throws TargetException, IllegalStateException;
090
091 /**
092 * Retrieve the list of all J2EE application modules running or not running on the
093 * identified targets.
094 *
095 * @param moduleType A predefined designator for a J2EE module type.
096 * @param targetList A list of deployment Target designators the user wants checked
097 * for module not running status.
098 *
099 * @return An array of TargetModuleID objects representing all deployed modules
100 * running or not or <code>null</code> if there are no deployed modules.
101 *
102 * @throws TargetException occurs when an invalid Target was provided.
103 * @throws IllegalStateException is thrown when the method is called when running
104 * in disconnected mode.
105 */
106 public TargetModuleID[] getAvailableModules(ModuleType moduleType, Target[] targetList) throws TargetException, IllegalStateException;
107
108 /**
109 * Retrieve the object that provides server-specific deployment configuration
110 * information for the J2EE deployable component.
111 *
112 * @param dObj An object representing a J2EE deployable component.
113 *
114 * @return An object used to configure server-specific deployment information
115 *
116 * @throws InvalidModuleException The DeployableObject is an unknown or unsupported
117 * component for this configuration tool.
118 */
119 public DeploymentConfiguration createConfiguration(DeployableObject dObj) throws InvalidModuleException;
120
121 /**
122 * The distribute method performs three tasks; it validates the deployment
123 * configuration data, generates all container specific classes and interfaces,
124 * and moves the fully baked archive to the designated deployment targets.
125 *
126 * @param targetList A list of server targets the user is specifying this application
127 * should be deployed to.
128 * @param moduleArchive The file name of the application archive to be distributed.
129 * @param deploymentPlan The file containing the runtime configuration information
130 * associated with this application archive.
131 *
132 * @return an object that tracks and reports the status of the distribution process.
133 *
134 * @throws IllegalStateException is thrown when the method is called when running in disconnected mode.
135 */
136 public ProgressObject distribute(Target[] targetList, File moduleArchive, File deploymentPlan) throws IllegalStateException;
137
138 /**
139 * The distribute method performs three tasks; it validates the deployment
140 * configuration data, generates all container specific classes and interfaces,
141 * and moves the fully baked archive to the designated deployment targets.
142 *
143 * @param targetList A list of server targets the user is specifying this application
144 * should be deployed to.
145 * @param moduleArchive The stream containing the application archive to be distributed.
146 * @param deploymentPlan The stream containing the runtime configuration information
147 * associated with this application archive.
148 *
149 * @return an object that tracks and reports the status of the distribution process.
150 *
151 * @throws IllegalStateException is thrown when the method is called when running in disconnected mode.
152 */
153 public ProgressObject distribute(Target[] targetList, InputStream moduleArchive, InputStream deploymentPlan) throws IllegalStateException;
154
155 /**
156 * Start the application running.
157 *
158 * <p>Only the TargetModuleIDs which represent a root module are valid for being
159 * started. A root TargetModuleID has no parent. A TargetModuleID with a parent
160 * can not be individually started. A root TargetModuleID module and all its
161 * child modules will be started.</p>
162 *
163 * @param moduleIDList An array of TargetModuleID objects representing the modules to be started.
164 *
165 * @return An object that tracks and reports the status of the start operation.
166 *
167 * @throws IllegalStateException is thrown when the method is called when running in disconnected mode.
168 */
169 public ProgressObject start(TargetModuleID[] moduleIDList) throws IllegalStateException;
170
171 /**
172 * Stop the application running.
173 *
174 * <p>Only the TargetModuleIDs which represent a root module are valid for
175 * being stopped. A root TargetModuleID has no parent. A TargetModuleID
176 * with a parent can not be individually stopped. A root TargetModuleID
177 * module and all its child modules will be stopped.</p>
178 *
179 * @param moduleIDList An array of TargetModuleID objects representing the modules to be stopped.
180 *
181 * @return An object that tracks and reports the status of the stop operation.
182 *
183 * @throws IllegalStateException is thrown when the method is called when running in disconnected mode.
184 */
185 public ProgressObject stop(TargetModuleID[] moduleIDList) throws IllegalStateException;
186
187 /**
188 * Remove the application from the target server.
189 *
190 * <p>Only the TargetModuleIDs which represent a root module are valid for
191 * undeployment. A root TargetModuleID has no parent. A TargetModuleID with
192 * a parent can not be undeployed. A root TargetModuleID module and all its
193 * child modules will be undeployed. The root TargetModuleID module and all
194 * its child modules must stopped before they can be undeployed.
195 *
196 * @param moduleIDList An array of TargetModuleID objects representing the root
197 * modules to be undeployed.
198 *
199 * @return An object that tracks and reports the status of the stop operation.
200 *
201 * @throws IllegalStateException is thrown when the method is called when running in disconnected mode.
202 */
203 public ProgressObject undeploy(TargetModuleID[] moduleIDList) throws IllegalStateException;
204
205 /**
206 * This method designates whether this platform vendor provides application
207 * redeployment functionality. A value of true means it is supported. False
208 * means it is not.
209 *
210 * @return A value of true means redeployment is supported by this vendor's
211 * DeploymentManager. False means it is not.
212 */
213 public boolean isRedeploySupported();
214
215 /**
216 * (optional) The redeploy method provides a means for updating currently
217 * deployed J2EE applications. This is an optional method for vendor
218 * implementation. Redeploy replaces a currently deployed application with an
219 * updated version. The runtime configuration information for the updated
220 * application must remain identical to the application it is updating. When
221 * an application update is redeployed, all existing client connections to the
222 * original running application must not be disrupted; new clients will connect
223 * to the application update. This operation is valid for TargetModuleIDs that
224 * represent a root module. A root TargetModuleID has no parent. A root
225 * TargetModuleID module and all its child modules will be redeployed. A child
226 * TargetModuleID module cannot be individually redeployed. The redeploy
227 * operation is complete only when this action for all the modules has completed.
228 *
229 * @param moduleIDList An array of designators of the applications to be updated.
230 * @param moduleArchive The file name of the application archive to be redeployed.
231 * @param deploymentPlan The deployment configuration information associated with
232 * this application archive.
233 *
234 * @return An object that tracks and reports the status of the redeploy operation.
235 *
236 * @throws UnsupportedOperationException this optional command is not supported by
237 * this implementation.
238 * @throws IllegalStateException is thrown when the method is called when running
239 * in disconnected mode.
240 */
241 public ProgressObject redeploy(TargetModuleID[] moduleIDList, File moduleArchive, File deploymentPlan) throws UnsupportedOperationException, IllegalStateException;
242
243 /**
244 * (optional) The redeploy method provides a means for updating currently
245 * deployed J2EE applications. This is an optional method for vendor
246 * implementation. Redeploy replaces a currently deployed application with an
247 * updated version. The runtime configuration information for the updated
248 * application must remain identical to the application it is updating. When
249 * an application update is redeployed, all existing client connections to the
250 * original running application must not be disrupted; new clients will connect
251 * to the application update. This operation is valid for TargetModuleIDs that
252 * represent a root module. A root TargetModuleID has no parent. A root
253 * TargetModuleID module and all its child modules will be redeployed. A child
254 * TargetModuleID module cannot be individually redeployed. The redeploy
255 * operation is complete only when this action for all the modules has completed.
256 *
257 * @param moduleIDList An array of designators of the applications to be updated.
258 * @param moduleArchive The stream containing the application archive to be redeployed.
259 * @param deploymentPlan The streeam containing the deployment configuration information
260 * associated with this application archive.
261 *
262 * @return An object that tracks and reports the status of the redeploy operation.
263 *
264 * @throws UnsupportedOperationException this optional command is not supported by
265 * this implementation.
266 * @throws IllegalStateException is thrown when the method is called when running
267 * in disconnected mode.
268 */
269 public ProgressObject redeploy(TargetModuleID[] moduleIDList, InputStream moduleArchive, InputStream deploymentPlan) throws UnsupportedOperationException, IllegalStateException;
270
271 /**
272 * The release method is the mechanism by which the tool signals to the
273 * DeploymentManager that the tool does not need it to continue running
274 * connected to the platform. The tool may be signaling it wants to run in a
275 * disconnected mode or it is planning to shutdown. When release is called the
276 * DeploymentManager may close any J2EE resource connections it had for
277 * deployment configuration and perform other related resource cleanup. It
278 * should not accept any new operation requests (i.e., distribute, start, stop,
279 * undeploy, redeploy. It should finish any operations that are currently in
280 * process. Each ProgressObject associated with a running operation should be
281 * marked as released (see the ProgressObject).
282 */
283 public void release();
284
285 /**
286 * Returns the default locale supported by this implementation of
287 * javax.enterprise.deploy.spi subpackages.
288 *
289 * @return the default locale for this implementation.
290 */
291 public Locale getDefaultLocale();
292
293 /**
294 * Returns the active locale this implementation of
295 * javax.enterprise.deploy.spi subpackages is running.
296 *
297 * @return the active locale of this implementation.
298 */
299 public Locale getCurrentLocale();
300
301 /**
302 * Set the active locale for this implementation of
303 * javax.enterprise.deploy.spi subpackages to run.
304 *
305 * @param locale the locale to set
306 *
307 * @throws UnsupportedOperationException the provide locale is not supported.
308 */
309 public void setLocale(Locale locale) throws UnsupportedOperationException;
310
311 /**
312 * Returns an array of supported locales for this implementation.
313 *
314 * @return the list of supported locales.
315 */
316 public Locale[] getSupportedLocales();
317
318 /**
319 * Reports if this implementation supports the designated locale.
320 *
321 * @param locale the locale to check
322 *
323 * @return A value of <code>true</code> means it is supported and <code>false</code> it is not.
324 */
325 public boolean isLocaleSupported(Locale locale);
326
327 /**
328 * Returns the J2EE platform version number for which the configuration
329 * beans are provided. The beans must have been compiled with the J2SE
330 * version required by the J2EE platform.
331 *
332 * @return a DConfigBeanVersionType object representing the platform
333 * version number for which these beans are provided.
334 */
335 public DConfigBeanVersionType getDConfigBeanVersion();
336
337 /**
338 * Returns <code>true</code> if the configuration beans support the J2EE platform
339 * version specified. It returns <code>false</code> if the version is not supported.
340 *
341 * @param version a DConfigBeanVersionType object representing the J2EE
342 * platform version for which support is requested.
343 *
344 * @return <code>true</code> if the version is supported and 'false if not.
345 */
346 public boolean isDConfigBeanVersionSupported(DConfigBeanVersionType version);
347
348 /**
349 * Set the configuration beans to be used to the J2EE platform version specified.
350 *
351 * @param version a DConfigBeanVersionType object representing the J2EE
352 * platform version for which support is requested.
353 *
354 * @throws DConfigBeanVersionUnsupportedException when the requested bean
355 * version is not supported.
356 */
357 public void setDConfigBeanVersion(DConfigBeanVersionType version) throws DConfigBeanVersionUnsupportedException;
358 }