DeploymentMgr


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 com.sun.appserv.management.deploy;
25  
26  import java.io.IOException  ;
27  import java.io.Serializable  ;
28  import java.util.Map  ;
29  
30  import javax.management.Notification  ;
31  
32  import com.sun.appserv.management.base.XTypes;
33  import com.sun.appserv.management.base.AMX;
34  import com.sun.appserv.management.base.Utility;
35  import com.sun.appserv.management.base.Singleton;
36  import com.sun.appserv.management.base.Util;
37  
38  /**
39   This interface provides facilities to deploy any type of 
40   J2EE module. 
41   *
42   Users of this interface are likely to do the following 
43   <p>
44    - Start uploading the necessary file for deployment by 
45    using the initiateFileUpload and sendBytes APIs. Once 
46    the file(s) upload are completed the deploy operation 
47    can be initiated. 
48   </p>
49   <p>
50    - Instead of uploading files or when dealing with 
51    redeployment with a partial archive delivery, a  
52    DeploymentSource object is used to retrieve the 
53    delivered files.  This DeploymentSource is encoded
54    as a Map.
55   </p>
56   <p>
57    - Deploy operations can be invoked either by using 
58    uploaded files ID (obtained from initiateFileUpload) 
59    or a DeploymentSource. DeploymentOptions can be passed 
60    as a Map of Deployment option name to deployment option 
61    value.
62   </p>
63   </p>
64    - Deploy operations are asynchronous therefore they can
65    be monitored using the getDeploymentProgress and 
66    getStatusCode operations. 
67   </p>
68   <p>
69    - To observe completion of a deployment, the client should
70    register itself as a listener on the DeploymentMgr using
71    addNotificationListener().  A Notification will be issued in
72    which the value of notif.getUserData() will be the deployID
73    used for the deployment.  The notif will have the getType() of
74    DEPLOYMENT_COMPLETED_NOTIFICATION_TYPE.
75   </p>
76   <p>
77    - In case the client wants to retrieve non portable artifacts
78    after successful deployment the file download APIs should be 
79    used (initiateFileDownload and receiveBytes).
80   </p>
81   <p>
82    MBean API's concept of Deploy and Undeploy are different from the CLI and GUI concept.
83    In order to have a fully functioning application for deploy or a fully removed application for undeploy,
84    3 steps must be performed in both cases.  
85    Associate and start (also, stop and disassociate) are always performed together in CLI and GUI.
86    MBean API users must perform the 3 steps
87    explicitly.  I.e. Deploy and Undeploy in the MBean API performs only the transfer and registration 
88    of files in the AppServer.  
89   </p>
90   <p>These are the required steps: </p>
91   <strong>Deploy</strong>
92   <ul>
93   <li>Deploy
94   <li>Associate
95   <li>Start
96   </ul>
97   <strong>Undeploy</strong>
98   <ul>
99   <li>Stop
100  <li>Disassociate
101  <li>Undeploy
102  </ul>
103  <p>
104  Also, J2EEServer.getDeployedObjectsSet() is based on a running modules. Hence, a deployedObject will appear 
105  in the list only when the module is running
106  </p>
107  @see Util#getAMXNotificationValue
108  */
109 public interface DeploymentMgr extends AMX, Utility, Singleton
110 {
111 /** The j2eeType as returned by {@link com.sun.appserv.management.base.AMX#getJ2EEType}. */
112     public static final String    J2EE_TYPE   = XTypes.DEPLOYMENT_MGR;
113     
114     /**
115         Prefix for all keys used by DeploymentMgr
116      */
117     public static final String    KEY_PREFIX  = XTypes.DEPLOYMENT_MGR + ".";
118     
119     /**
120         Key within the Map of a Notification indicating deployment ID.
121         @see Util#getAMXNotificationValue
122      */
123     public final String   NOTIF_DEPLOYMENT_ID_KEY = KEY_PREFIX + "DeploymentID";
124     
125     /**
126         Key within the Map of a Notification of type
127         DEPLOYMENT_COMPLETED_NOTIFICATION_TYPE, indicating
128         the final status of the deployment.
129         @see Util#getAMXNotificationValue
130      */
131     public final String   NOTIF_DEPLOYMENT_COMPLETED_STATUS_KEY   =
132         KEY_PREFIX + "DeploymentCompletedStatus";
133     
134     /**
135         Key within the Map of a Notification of type
136         DEPLOYMENT_PROGRESS_NOTIFICATION_TYPE, indicating a
137         DeploymentProgress, as a Map.
138         @see Util#getAMXNotificationValue
139      */
140     public final String   NOTIF_DEPLOYMENT_PROGRESS_KEY   =
141         KEY_PREFIX + "DeploymentProgress";
142     
143     
144     /**
145         The type of the Notification emitted when a deployment starts.
146         The user data field contains a Map keyed by NOTIF_*_KEY.
147      */
148     public final String   DEPLOYMENT_STARTED_NOTIFICATION_TYPE    =
149         XTypes.DEPLOYMENT_MGR + ".DeploymentStarted";
150         
151     /**
152         The type of the Notification emitted when a deployment completes.
153         The user data field contains a Map keyed by NOTIF_*_KEY.
154      */
155     public final String   DEPLOYMENT_COMPLETED_NOTIFICATION_TYPE  =
156         XTypes.DEPLOYMENT_MGR + ".DeploymentCompleted";
157         
158     /**
159         The type of the Notification emitted when a deployment is aborted
160         via abortDeploy().
161         The user data field contains a Map keyed by NOTIF_*_KEY.
162      */
163     public final String   DEPLOYMENT_ABORTED_NOTIFICATION_TYPE    =
164         XTypes.DEPLOYMENT_MGR + ".DeploymentAborted";
165         
166     /**
167         The type of the Notification emitted for deployment progress.
168         The user data field contains a Map keyed by NOTIF_*_KEY.
169      */
170     public final String   DEPLOYMENT_PROGRESS_NOTIFICATION_TYPE   =
171         XTypes.DEPLOYMENT_MGR + ".DeploymentProgress";
172     
173     /*
174      Constant file name to use to retrieve the client stubs 
175      jar file after a successful deployment.
176      @see initiateFileDownload(String, String)
177      */
178     public static final String   STUBS_JARFILENAME = "STUBSJAVAFILENAME";
179 
180     /**
181         Key for startDeploy() options--
182         Forcefully (re)deploy the component even if the specified component has
183         already been deployed.  The default value is true. 
184      */
185     public static final String   DEPLOY_OPTION_FORCE_KEY = KEY_PREFIX + "Force";
186     
187     /**
188         Key for undeploy() options--
189         If set to true, it deletes all the connection pools and connector
190         resources associated with the resource adapter (being undeployed).
191         If set to false, the undeploy fails if any pools and resources are still
192         associated with the resource adapter.
193         <p>
194         This option is applicable to connectors(resource adapters) and
195         applications(J2EE apps i.e .ear files can contain the resource adapters *.rar).
196         The default value is false. 
197      */
198     public static final String   DEPLOY_OPTION_CASCADE_KEY = KEY_PREFIX + "Cascade";
199     
200     /**
201         Key for startDeploy() options--
202         If set to true, verify the syntax and semantics of the deployment descriptor.
203         The default value is false. 
204      */
205     public static final String   DEPLOY_OPTION_VERIFY_KEY = KEY_PREFIX + "Verify";
206     
207     /**
208         Key for startDeploy) options--
209         Disables or enables the component after it is deployed.
210         The default value is true.
211      */
212     public static final String   DEPLOY_OPTION_ENABLE_KEY = KEY_PREFIX + "Enable";
213     
214     /**
215         Key for startDeploy) options--
216         The context root of the deployable web component. Only applies to web module. 
217      */
218     public static final String   DEPLOY_OPTION_CONTEXT_ROOT_KEY = KEY_PREFIX + "ContextRoot";
219     
220     /**
221         Key for startDeploy) options--
222         Registration name of the deployble component,
223         its value should be unique across domain. 
224      */
225     public static final String   DEPLOY_OPTION_NAME_KEY = KEY_PREFIX + "Name";
226     
227     /**
228         Key for startDeploy) options--
229         The description of the component being deployed. 
230      */
231     public static final String   DEPLOY_OPTION_DESCRIPTION_KEY = KEY_PREFIX + "Description";
232     
233     /**
234         Key for startDeploy) options--
235         When true, will generate the static RMI-IIOP stubs and put it in the client.jar.
236         Default value for this option is "false".
237      */
238     public static final String   DEPLOY_OPTION_GENERATE_RMI_STUBS_KEY =  KEY_PREFIX + "GenerateRMIStubs";
239 
240     /**
241         Key for startDeploy) options--
242         This option controls whether availability is enabled for SFSB checkpointing
243         (and potentially passivation). When false,
244         then all SFSB checkpointing is disabled for either the given j2ee app
245         or the given ejb module. When true, the j2ee app or stand-alone
246         ejb modules may be enabled. Default value is "false".
247      */
248     public static final String   DEPLOY_OPTION_AVAILABILITY_ENABLED_KEY =   KEY_PREFIX + "AvailabilityEnabled"; 
249   
250   
251     /**
252         Key for startDeploy) options--
253         This option controls whether java web start is enabled. 
254         Applicable for a J2EEApplication or AppClientModule.
255      */
256     public static final String   DEPLOY_OPTION_JAVA_WEB_START_ENABLED_KEY =
257         KEY_PREFIX + "JavaWebStartEnabled"; 
258         
259     /**
260         Key for startDeploy) options--
261         This option specifies additional libraries.
262         Applicable for a J2EEApplication, WebModule, or EJBModule.
263         @see com.sun.appserv.management.config.Libraries
264      */
265     public static final String   DEPLOY_OPTION_LIBRARIES_KEY =
266         KEY_PREFIX + "Libraries"; 
267   
268     /**
269      initiatiate a new deployment operation, the id 
270      returned will be used to transfer the appropriate 
271      files on the server. 
272      *
273      @param totalSize total size of the file to upload
274      @return an identifier describing this file upload
275      */
276     public Object   initiateFileUpload( long totalSize )
277             throws IOException  ;
278             
279             
280     /**
281         This variant allows a name to be specified.
282         
283         @param name name to be used for the temp file
284         @param totalSize total size of the file to upload
285         @return an identifier describing this file upload
286      */
287     public Object   initiateFileUpload( String   name, long totalSize )
288             throws IOException  ;
289     
290     /**
291      For an upload id obtained from initiateFileUpload(), send another
292      chunk of bytes for that upload.
293      
294      @param uploadID the id obtained from initiateFileUpload()
295      @param bytes the bytes to upload
296      @return true if the total upload has been completed, false otherwise
297      */ 
298     public boolean uploadBytes(Object   uploadID, byte[] bytes)
299         throws IOException  ;
300     
301     
302     /**
303         Create a new deploy ID which may be used via startDeploy() to start
304         a new deployment operation.
305        
306         @return an new opaque identifier which can be used in startDeploy()
307      */
308     public Object   initDeploy();
309     
310     /**
311      Start the deployment operation using file(s) previously uploaded
312      by initializeFileUpload() and uploadBytes().
313      <p>
314      When the runtime deployment descriptors  
315      and other server specific configuration are embedded in 
316      the deployable archive, null should be passed for the planUploadID.
317      <p>
318      Legal keys for use within the options Map include:
319      <ul>
320         <li>{@link #DEPLOY_OPTION_FORCE_KEY}</li>
321         <li>{@link #DEPLOY_OPTION_CASCADE_KEY}</li>
322         <li>{@link #DEPLOY_OPTION_VERIFY_KEY}</li>
323         <li>{@link #DEPLOY_OPTION_ENABLE_KEY}</li>
324         <li>{@link #DEPLOY_OPTION_CONTEXT_ROOT_KEY}</li>
325         <li>{@link #DEPLOY_OPTION_NAME_KEY}</li>
326         <li>{@link #DEPLOY_OPTION_DESCRIPTION_KEY}</li>
327         <li>{@link #DEPLOY_OPTION_GENERATE_RMI_STUBS_KEY}</li>
328         <li>{@link #DEPLOY_OPTION_AVAILABILITY_ENABLED_KEY}</li>
329         <li>{@link #DEPLOY_OPTION_JAVA_WEB_START_ENABLED_KEY}</li>
330         <li>{@link #DEPLOY_OPTION_LIBRARIES_KEY}</li>
331      </ul>
332      
333      @param deployID        an id obtained from initDeploy()
334      @param uploadID        an id obtained from initiateFileUpload()
335      @param planUploadID    an id obtained from initiateFileUpload(), may be null
336      @param options contains the list of deployment options
337      */
338     public void startDeploy( Object   deployID, Object   uploadID, Object   planUploadID, Map  <String  ,String  > options);
339     
340     
341     /**
342      Start a new deployment operation given a deployment source 
343      and a list of options. The DeploymentPlan is null 
344      when the runtime deployment descriptors and other 
345      server specific configuration is embedded in the 
346      deployable archive.
347      <p>
348      Legal keys for use within the options Map include:
349      <ul>
350         <li>{@link #DEPLOY_OPTION_FORCE_KEY}</li>
351         <li>{@link #DEPLOY_OPTION_CASCADE_KEY}</li>
352         <li>{@link #DEPLOY_OPTION_VERIFY_KEY}</li>
353         <li>{@link #DEPLOY_OPTION_ENABLE_KEY}</li>
354         <li>{@link #DEPLOY_OPTION_CONTEXT_ROOT_KEY}</li>
355         <li>{@link #DEPLOY_OPTION_NAME_KEY}</li>
356         <li>{@link #DEPLOY_OPTION_DESCRIPTION_KEY}</li>
357         <li>{@link #DEPLOY_OPTION_GENERATE_RMI_STUBS_KEY}</li>
358         <li>{@link #DEPLOY_OPTION_AVAILABILITY_ENABLED_KEY}</li>
359      </ul>
360      
361      @param deployID an id obtained from initDeploy()
362      @param source a DeploymentSource as a Map
363      @param plan will contain the deployment plan for this, may be null
364      deployment operation if the deployable archive is portable 
365      @param options contains the list of deployment options.
366      */
367     public <T1 extends Serializable  ,T2 extends Serializable  > void startDeploy(
368         Object   deployID,
369         Map  <String  ,T1> source,
370         Map  <String  ,T2> plan,
371         Map  <String  ,String  > options);
372     
373     
374     /**
375         Return all Notifications, which have already been sent, but which are
376         also queued waiting for this request.
377         <p>
378         The deployment is done if the last Notification is of type
379         {@link #DEPLOYMENT_COMPLETED_NOTIFICATION_TYPE} or
380         {@link #DEPLOYMENT_ABORTED_NOTIFICATION_TYPE}.
381         The deployment is not otherwise affected; you may still call
382         {@link #getFinalDeploymentStatus}.
383         <p>
384         <b>WARNING: This routine is for internal use only, and may not be supported
385         in the future.  External users should use the standard Notification
386         mechanisms by registering as a listener</b>
387         
388         @param deployID 
389         @return any accumulated Notifications
390         @deprecated
391      */
392     public Notification  [] takeNotifications( final Object     deployID);
393     
394     /**
395      abort a given deployment operation, all modification 
396      to the server must be rollbacked and all resources 
397      cleaned. If the abortion operation cannot be successfully
398      completed (because it's too late for instance), it is the 
399      responsibility of the client to undeploy the application.
400      
401      @param deployID the id obtained from initDeploy()
402      @return true if the operation was successfully aborted
403      
404      */ 
405     public boolean abortDeploy(Object   deployID);
406     
407     /**
408         Return the final DeploymentStatus once the deployment has finished.
409         or null if the deployment has not yet finished.  Once called,
410         the state associated with this deployment is removed, and the
411         deployID is no longer valid.  All outstanding notifications pending
412         for takeNotifications() are also removed and become unavailable.
413         <p>
414         <b>WARNING: This routine is for internal use only, and may not be supported
415         in the future.  External users should use the standard Notification
416         mechanisms by registering as a listener</b>
417      
418         @param deployID the id obtained from initDeploy()
419         @return a DeploymentStatus, as a Map, or null if not yet finished
420      */ 
421     public Map  <String  ,Serializable  > getFinalDeploymentStatus(Object   deployID);
422     
423     
424     /**
425      Undeploys a module or application from the server,
426      cleans all associated resources and removed the
427      module from the list of installed components.
428 
429      @param moduleID the application module ID
430      @param optionalParams  optional parameters
431      @return a DeploymentStatus for the completed operation, as a Map
432      */
433     public Map  <String  ,Serializable  > undeploy(String   moduleID, Map  <String  ,String  > optionalParams); 
434     
435     /**
436      Initiates a file download with the given filename. 
437      The filename is relative to the application or module 
438      URL. If the filename is STUBS_JARFILENAME, the 
439      application client stubs jar file will be downloaded. 
440      This API can also be used for downloading final WSDL files.
441      *
442      @param moduleID the deployed component moduleID this file download 
443      is related to.
444      @param fileName the desired file name corresponding to this module
445      @return the operation id
446      */
447     public Object   initiateFileDownload(String   moduleID, String   fileName)
448         throws IOException  ;
449         
450     /**
451         Get the total length the download will be, in bytes.
452         
453         @param downloadID the file download operation id, from initiateFileDownload()
454      */
455     public long getDownloadLength( final Object   downloadID );
456     
457     
458     /**
459         The maximum allowed transfer size for downloading.
460      */
461     public static final int MAX_DOWNLOAD_CHUNK_SIZE = 5 * 1024 * 1024;
462     
463     /**
464      Download byte chunks from the server using a file 
465      operation id obtained via initiateFileDownload API. 
466      The bufferSize is the requested number of bytes to 
467      be received. If the size of the returned byte[] is less than
468      the requestSize, then the transfer has completed, and the
469      downloadID is no longer valid.  An attempt to read more than
470      the allowed maximum size will throw an exception.  The caller
471      can check the total download size in advance via
472      getDownloadLength().
473      
474      @param downloadID the file download operation id, from initiateFileDownload()
475      @param requestSize
476      @return bytes from the file.
477      */
478     public byte[] downloadBytes( Object   downloadID, int requestSize )
479         throws IOException  ;
480 
481 
482 
483 
484 }
485
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags