DeploymentManager


1   /*
2    * The contents of this file are subject to the terms 
3    * of the Common Development and Distribution License 
4    * (the License).  You may not use this file except in
5    * compliance with the License.
6    * 
7    * You can obtain a copy of the license at 
8    * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9    * glassfish/bootstrap/legal/CDDLv1.0.txt.
10   * See the License for the specific language governing 
11   * permissions and limitations under the License.
12   * 
13   * When distributing Covered Code, include this CDDL 
14   * Header Notice in each file and include the License file 
15   * at glassfish/bootstrap/legal/CDDLv1.0.txt.  
16   * If applicable, add the following below the CDDL Header, 
17   * with the fields enclosed by brackets [] replaced by
18   * you own identifying information: 
19   * "Portions Copyrighted [year] [name of copyright owner]"
20   * 
21   * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22   */
23  
24  package javax.enterprise.deploy.spi;
25  
26  import javax.enterprise.deploy.spi.status.*;
27  import javax.enterprise.deploy.spi.exceptions.*;
28  import javax.enterprise.deploy.model.DeployableObject  ;
29  import javax.enterprise.deploy.shared.DConfigBeanVersionType  ;
30  import javax.enterprise.deploy.shared.ModuleType  ;
31  import java.io.File  ;
32  import java.io.InputStream  ;
33  import java.util.Locale  ;
34  
35  import java.lang.Deprecated  ;
36  
37  /**
38   * The DeploymentManager object provides the core set
39   * of functions a J2EE platform must provide for J2EE
40   * application deployment.  It provides server related
41   * information, such as, a list of deployment targets,
42   * and vendor unique runtime configuration information.
43   */
44  public interface DeploymentManager {
45      
46      /**
47       * Retrieve the list of deployment targets supported by
48       * this DeploymentManager.
49       *
50       * @throws IllegalStateException is thrown when the method is
51       *                    called when running in disconnected mode.
52       * @return   A list of deployment Target designators the
53       *           user may select for application deployment or 'null'
54       *           if there are none.
55       */
56      public Target  [] getTargets() throws IllegalStateException  ;
57      
58      
59      /**
60       * Retrieve the list of J2EE application modules distributed
61       * to the identified targets and that are currently running
62       * on the associated server or servers.
63       *
64       * @param moduleType A predefined designator for a J2EE
65       *                   module type.
66       *
67       * @param targetList A list of deployment Target designators
68       *                   the user wants checked for module run
69       *                   status.
70       *
71       * @return An array of TargetModuleID objects representing
72       *                   the running modules or 'null' if there
73       *                   are none.
74       *
75       * @throws IllegalStateException is thrown when the method is
76       *                    called when running in disconnected mode.
77       * @throws TargetException An invalid Target designator
78       *                   encountered.
79       */
80      public TargetModuleID  [] getRunningModules(ModuleType   moduleType,
81              Target  [] targetList) throws TargetException,
82              IllegalStateException  ;
83      
84      /**
85       * Retrieve the list of J2EE application modules distributed
86       * to the identified targets and that are currently not
87       * running on the associated server or servers.
88       *
89       * @param moduleType A predefined designator for a J2EE
90       *                   module type.
91       *
92       * @param targetList A list of deployment Target designators
93       *                   the user wants checked for module not
94       *                   running status.
95       *
96       * @return An array of TargetModuleID objects representing
97       *                   the non-running modules or 'null' if
98       *                   there are none.
99       *
100      * @throws IllegalStateException is thrown when the method is
101      *                    called when running in disconnected mode.
102      * @throws TargetException An invalid Target designator
103      *                   encountered.
104      */
105     public TargetModuleID  [] getNonRunningModules(ModuleType   moduleType,
106             Target  [] targetList) throws TargetException,
107             IllegalStateException  ;
108     
109     /**
110      * Retrieve the list of all J2EE application modules running
111      * or not running on the identified targets.
112      *
113      * @param moduleType A predefined designator for a J2EE
114      *                   module type.
115      *
116      * @param targetList A list of deployment Target designators
117      *                   the user wants checked for module not
118      *                   running status.
119      *
120      * @return An array of TargetModuleID objects representing
121      *                   all deployed modules running or not or
122      *                   'null' if there are no deployed modules.
123      *
124      * @throws IllegalStateException is thrown when the method is
125      *                    called when running in disconnected mode.
126      * @throws TargetException An invalid Target designator
127      *                   encountered.
128      */
129     public TargetModuleID  [] getAvailableModules(ModuleType   moduleType,
130             Target  [] targetList) throws TargetException,
131             IllegalStateException  ;
132     
133     /**
134      * Retrieve the object that provides server-specific deployment
135      * configuration information for the J2EE deployable component.
136      *
137      * @param dObj An object representing a J2EE deployable component.
138      * @throws InvalidModuleException The DeployableObject is an
139      *                      unknown or unsupport component for this
140      *                      configuration tool.
141      */
142     
143     public DeploymentConfiguration   createConfiguration(DeployableObject   dObj)
144     throws InvalidModuleException;
145     
146     
147     /**
148      * The distribute method performs three tasks; it validates the
149      * deployment configuration data, generates all container specific
150      * classes and interfaces, and moves the fully baked archive to
151      * the designated deployment targets.
152      *
153      * @param targetList   A list of server targets the user is specifying
154      *                     this application be deployed to.
155      * @param moduleArchive The file name of the application archive
156      *                      to be disrtibuted.
157      * @param deploymentPlan The XML file containing the runtime
158      *                       configuration information associated with
159      *                       this application archive.
160      * @throws IllegalStateException is thrown when the method is
161      *                    called when running in disconnected mode.
162      * @return ProgressObject an object that tracks and reports the
163      *                       status of the distribution process.
164      */
165     
166     public ProgressObject distribute(Target  [] targetList,
167             File   moduleArchive, File   deploymentPlan)
168             throws IllegalStateException  ;
169     
170     /**
171      * The distribute method performs three tasks; it validates the
172      * deployment configuration data, generates all container specific
173      * classes and interfaces, and moves the fully baked archive to
174      * the designated deployment targets.
175      *
176      * @param targetList   A list of server targets the user is specifying
177      *                     this application be deployed to.
178      * @param moduleArchive The input stream containing the application
179      *                      archive to be disrtibuted.
180      * @param deploymentPlan The input stream containing the deployment
181      *                       configuration information associated with
182      *                       this application archive.
183      * @throws IllegalStateException is thrown when the method is
184      *                    called when running in disconnected mode.
185      * @return ProgressObject an object that tracks and reports the
186      *                       status of the distribution process.
187      * @deprecated as of Java EE 5, replaced with {@link #distribute(Target[], ModuleType, InputStream, InputStream)}
188      */
189     
190     public ProgressObject distribute(Target  [] targetList,
191             InputStream   moduleArchive, InputStream   deploymentPlan)
192             throws IllegalStateException  ;
193     
194     /**
195      * The distribute method performs three tasks; it validates the
196      * deployment configuration data, generates all container specific
197      * classes and interfaces, and moves the fully baked archive to
198      * the designated deployment targets.
199      *
200      * @param targetList   A list of server targets the user is specifying
201      *                     this application be deployed to.
202      * @param moduleType   The module type of this application archive.
203      * @param moduleArchive The input stream containing the application
204      *                      archive to be disrtibuted.
205      * @param deploymentPlan The input stream containing the deployment
206      *                       configuration information associated with
207      *                       this application archive.
208      * @throws IllegalStateException is thrown when the method is
209      *                    called when running in disconnected mode.
210      * @return ProgressObject an object that tracks and reports the
211      *                       status of the distribution process.
212      *
213      */
214     
215     public ProgressObject distribute(Target  [] targetList, ModuleType   type,
216             InputStream   moduleArchive, InputStream   deploymentPlan)
217             throws IllegalStateException  ;    
218     
219     /**
220      * Start the application running.
221      *
222      * <p> Only the TargetModuleIDs which represent a root module
223      * are valid for being started. A root TargetModuleID has no parent.
224      * A TargetModuleID with a parent can not be individually started.
225      * A root TargetModuleID module and all its child modules will be
226      * started.
227      *
228      * @param moduleIDList  A array of TargetModuleID objects
229      *                    representing the modules to be started.
230      * @throws IllegalStateException is thrown when the method is
231      *                    called when running in disconnected mode.
232      * @return ProgressObject an object that tracks and reports the
233      *                       status of the start operation.
234      */
235     
236     public ProgressObject start(TargetModuleID  [] moduleIDList)
237     throws IllegalStateException  ;
238     
239     /**
240      * Stop the application running.
241      *
242      * <p> Only the TargetModuleIDs which represent a root module
243      * are valid for being stopped. A root TargetModuleID has no parent.
244      * A TargetModuleID with a parent can not be individually stopped.
245      * A root TargetModuleID module and all its child modules will be
246      * stopped.
247      *
248      * @param moduleIDList  A array of TargetModuleID objects
249      *                    representing the modules to be stopped.
250      * @throws IllegalStateException is thrown when the method is
251      *                    called when running in disconnected mode.
252      * @return ProgressObject an object that tracks and reports the
253      *                       status of the stop operation.
254      */
255     
256     public ProgressObject stop(TargetModuleID   [] moduleIDList)
257     throws IllegalStateException  ;
258     
259     /**
260      * Remove the application from the target server.
261      *
262      * <p> Only the TargetModuleIDs which represent a root module
263      * are valid for undeployment. A root TargetModuleID has no parent.
264      * A TargetModuleID with a parent can not be undeployed. A root
265      * TargetModuleID module and all its child modules will be undeployed.
266      * The root TargetModuleID module and all its child modules must
267      * stopped before they can be undeployed.
268      *
269      * @param moduleIDList An array of TargetModuleID objects representing
270      *                   the root modules to be stopped.
271      * @throws IllegalStateException is thrown when the method is
272      *                    called when running in disconnected mode.
273      * @return ProgressObject an object that tracks and reports the
274      *                       status of the stop operation.
275      */
276     
277     public ProgressObject undeploy(TargetModuleID  [] moduleIDList)
278     throws IllegalStateException  ;
279     
280     /**
281      * This method designates whether this platform vendor provides
282      * application redeployment functionality. A value of true means
283      * it is supported.  False means it is not.
284      *
285      * @return A value of true means redeployment is supported by this
286      *                   vendor's DeploymentManager.  False means it
287      *                   is not.
288      */
289     public boolean isRedeploySupported();
290     
291     /**
292      * (optional)
293      * The redeploy method provides a means for updating currently
294      * deployed J2EE applications.  This is an optional method for
295      * vendor implementation.
296      *
297      * Redeploy replaces a currently deployed application with an
298      * updated version.  The runtime configuration information for
299      * the updated application must remain identical to the application
300      * it is updating.
301      *
302      * When an application update is redeployed, all existing client
303      * connections to the original running application must not be disrupted;
304      * new clients will connect to the application update.
305      *
306      * This operation is valid for TargetModuleIDs that represent a
307      * root module. A root TargetModuleID has no parent. A root
308      * TargetModuleID module and all its child modules will be redeployed.
309      * A child TargetModuleID module cannot be individually redeployed.
310      * The redeploy operation is complete only when this action for
311      * all the modules has completed.
312      *
313      * @param moduleIDList An array of designators of the applications
314      *                      to be updated.
315      * @param moduleArchive The file name of the application archive
316      *                      to be disrtibuted.
317      * @param deploymentPlan The deployment configuration information
318      *                       associated with this application archive.
319      * @return ProgressObject an object that tracks and reports the
320      *                       status of the redeploy operation.
321      * @throws IllegalStateException is thrown when the method is
322      *                    called when running in disconnected mode.
323      * @throws java.lang.UnsupportedOperationException this optional command
324      *         is not supported by this implementation.
325      */
326     
327     public ProgressObject redeploy(TargetModuleID  [] moduleIDList,
328             File   moduleArchive, File   deploymentPlan)
329             throws java.lang.UnsupportedOperationException  ,
330             IllegalStateException  ;
331     
332     /**
333      * (optional)
334      * The redeploy method provides a means for updating currently
335      * deployed J2EE applications.  This is an optional method for
336      * vendor implementation.
337      *
338      * Redeploy replaces a currently deployed application with an
339      * updated version.  The runtime configuration information for
340      * the updated application must remain identical to the application
341      * it is updating.
342      *
343      * When an application update is redeployed, all existing client
344      * connections to the original running application must not be disrupted;
345      * new clients will connect to the application update.
346      *
347      * This operation is valid for TargetModuleIDs that represent a
348      * root module. A root TargetModuleID has no parent. A root
349      * TargetModuleID module and all its child modules will be redeployed.
350      * A child TargetModuleID module cannot be individually redeployed.
351      * The redeploy operation is complete only when this action for
352      * all the modules has completed.
353      *
354      * @param moduleIDList An array of designators of the applications
355      *                      to be updated.
356      * @param moduleArchive The input stream containing the application
357      *                      archive to be disrtibuted.
358      * @param deploymentPlan The input stream containing the runtime
359      *                       configuration information associated with
360      *                       this application archive.
361      * @return ProgressObject an object that tracks and reports the
362      *                       status of the redeploy operation.
363      * @throws IllegalStateException is thrown when the method is
364      *                    called when running in disconnected mode.
365      * @throws java.lang.UnsupportedOperationException this optional command
366      *         is not supported by this implementation.
367      */
368     
369     public ProgressObject redeploy(TargetModuleID  [] moduleIDList,
370             InputStream   moduleArchive, InputStream   deploymentPlan)
371             throws java.lang.UnsupportedOperationException  ,
372             IllegalStateException  ;
373     
374     
375     
376     /**
377      * The release method is the mechanism by which the tool signals
378      * to the DeploymentManager that the tool does not need it to
379      * continue running connected to the platform.
380      *
381      * The tool may be signaling it wants to run in a disconnected
382      * mode or it is planning to shutdown.
383      *
384      * When release is called the DeploymentManager may close any
385      * J2EE resource connections it had for deployment configuration
386      * and perform other related resource cleanup.  It should not
387      * accept any new operation requests (i.e., distribute, start
388      * stop, undeploy, redeploy.  It should finish any operations
389      * that are currently in process.  Each ProgressObject associated
390      * with a running operation should be marked as released (see
391      * the ProgressObject).
392      *
393      */
394     
395     public void release();
396     
397     /**
398      * Returns the default locale supported by this implementation of
399      * javax.enterprise.deploy.spi subpackages.
400      *
401      * @return Locale the default locale for this implementation.
402      */
403     public Locale   getDefaultLocale();
404     
405     /**
406      * Returns the active locale this implementation of
407      * javax.enterprise.deploy.spi subpackages is running.
408      *
409      * @return Locale the active locale of this implementation.
410      */
411     public Locale   getCurrentLocale();
412     
413     /**
414      * Set the active locale for this implementation of
415      * javax.enterprise.deploy.spi subpackages to run.
416      *
417      * @throws java.lang.UnsupportedOperationException the provide locale is
418      *      not supported.
419      */
420     public void setLocale(Locale   locale)
421         throws java.lang.UnsupportedOperationException  ;
422     
423     /**
424      * Returns an array of supported locales for this implementation.
425      *
426      * @return Locale[] the list of supported locales.
427      */
428     public Locale  [] getSupportedLocales();
429     
430     /**
431      * Reports if this implementation supports the designated locale.
432      *
433      * @return  A value of 'true' means it is support and 'false' it is
434      *      not.
435      */
436     public boolean isLocaleSupported(Locale   locale);
437     
438     /**
439      * Returns the J2EE platform version number for which the
440      * configuration beans are provided.  The beans must have
441      * been compiled with the J2SE version required by the J2EE
442      * platform.
443      *
444      * @return a DConfigBeanVersionType object representing the
445      * platform version number for which these beans are provided.
446      */
447     public DConfigBeanVersionType   getDConfigBeanVersion();
448     
449     /**
450      * Returns 'true' if the configuration beans support the J2EE platform
451      * version specified.  It returns 'false' if the version is
452      * not supported.
453      *
454      * @param version a DConfigBeanVersionType object representing the
455      *  J2EE platform version for which support is requested.
456      * @return 'true' if the version is supported and 'false if not.
457      */
458     public boolean isDConfigBeanVersionSupported(DConfigBeanVersionType   version);
459     
460     /**
461      * Set the configuration beans to be used to the J2EE platform
462      * version specificed.
463      *
464      * @param version a DConfigBeanVersionType object representing the
465      * J2EE platform version for which support is requested.
466      * @throws DConfigBeanVersionUnsupportedException when the
467      *        requested bean version is not supported.
468      */
469     public void setDConfigBeanVersion(DConfigBeanVersionType   version) throws
470             DConfigBeanVersionUnsupportedException;
471 }
472
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags