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