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 }