Deploying applications on JBoss AS standalone
Deploying applications on JBoss AS standalone
Deployment applications on JBoss AS has been traditionally a fairly simple task on JBoss AS, so our readers might argue why we have dedicated a full chapter to it. The answer is that deploying applications on AS 7 can be achieved using several different strategies. The first distinction, which we must account for, is about the automation of the deployment:
Automatic deployment: This is triggered by the deployment scanner when a change happens in one deployed resource
Manual deployment: This does not rely on the deployment scanner to trigger a deployment, but on a set of marker files to decide if the user needs to start/restart an application
Automatic application deployment
Automatic application deployment is a simple process that consists of dropping an application into the deployments folder, which is located in the path JBOSS_HOME\standalone\deployments.
By default, every application archive (WAR, JAR, EAR, and SAR) that is placed into this folder is automatically deployed on the server.
The service that scans for deployed resources is called the deployment scanner , and it is configured within the standalone.xml configuration file.
You can find it by searching for the deployment-scanner domain.
<deployment-scanner name=”default” path=”deployments” scan-interval=”5000″ relative-to=”jboss.server.base.dir”/>
As you can see, by default the server scans in the deployments folder every 5000 ms. This service is, however, customizable in many ways. Let’s see two main changes that we can operate on it.
Deploying applications on a custom folder
If you want to change the default deployment path, you need to operate on the relative-to and path properties. If you provide both properties, the deployment folder will be a sum of both properties. For example, supposing that you have defined the path as7deployment, you can later reference it as a relative path for your deployments:
<path name=”as7deployments” path=”C:/AS7″ />
<deployment-scanner name=”default” path=”deployments” relative-to=”as7deployments” scan-enabled=”true” scan-interval=”5000″ deployment-timeout=”60″/>
In this configuration, the deployment scanner will look for applications under the C:/AS7/deployments folder.
The same effect can be achieved by using an absolute path for your deployments, leaving out the relative-to property and by configuring the path element, as shown in this example:
<deployment-scanner scan-interval=”5000″ path=”C:/AS7/deployments” />
Changing the behavior of the application scanner
As we said, by default every packaged archive that is deployed is automatically activated. Exploded applications, on the other hand, need one more step to be activated (see the section Manual application deployment).
We can, at any time, change the behavior of the deployment scanner. The properties that control the auto-deploy feature are auto-deploy-zipped and auto-deploy-exploded , respectively.
<deployment-scanner scan-interval=”5000″ relative-to=”jboss.server.base.dir”path=”deployments” auto-deploy-zipped=”true” auto-deploy-exploded=”false”/>
For example, you could set the auto-deploy-exploded to true, to achieve automatic redeployment of exploded archives as well:
<deployment-scanner scan-interval=”5000″ relative-to=”jboss.server.base.dir”path=”deployments” auto-deploy-zipped=”true” auto-deploy-exploded=”true”/>
Deploying an application using the CLI
Direct copy of the application archives is the favorite choice for many developers, as it can be performed automatically by the development environment. However, we would like to stress the advantage of using the CLI interface, which offers a wide choice of additional options when deploying and also provides the opportunity to deploy applications remotely.
All it takes to deploy an application archive is logging into the application server, either local or remote, and issuing the deploy shell command. When used without arguments, the deploy command provides the list of applications that are currently deployed:
[disconnected /] connect Connected to standalone controller at localhost:9999 [localhost:9999 /] deploy ExampleApp.war
If you feed to the shell a resource archive, such as .war, it will deploy it on the standalone server right away: [standalone@localhost:9999 /] deploy ../MyApp.war ‘MyApp.war’ deployed successfully.
As you can see from the screenshot, the CLI uses the folder where your deployments were actually launched as their initial location by default JBOSS_HOME/bin). You can, however, use absolute paths when specifying the location of your archives; the CLI expansion facility (using the Tab key) makes this option fairly simple:
[standalone@localhost:9999 /] deploy c:\deployments\MyApp.war ‘MyApp.war’ deployed successfully.
As it is, the application is deployed and activated so that the user can access it. If you want to just perform the deployment of the application and defer to the activation at a later time, you have to add the –disabled switch:
[standalone@localhost:9999 /] deploy ../MyApp.war –disabled ‘MyApp.war’ deployed successfully.
In order to activate the application, simply issue another deploy command without the –disabled switch:
[standalone@localhost:9999 /] deploy -–name=MyApp.war ‘MyApp.war’ deployed successfully.
Noticed the optional –name switch that has been added? As a matter of fact, when using this switch you will be able to use the tab completion feature so that you can automatically find the inactive deployment unit.
Re-deploying the application requires an additional flag to the deploy command. Use the –f argument to force the application redeployment.
[localhost:9999 /] deploy -f ../MyApp.war ‘MyApp.war’ re-deployed successfully.
Un-deploying the application can be done through the undeploy command, which takes as argument the application deployed.
[localhost:9999 /] undeploy MyApp.war ‘MyApp.war’ undeployed successfully.
By checking the configuration file, you will notice that the deployment element for your application has been removed.
Deploying an application using the Web admin console
The previous steps can also be completed by using the other management interface, provided by the application server: the Web admin console. Start the console by launching your browser at the home address: http://localhost:9990/console.
Since JBoss AS 7.1.0 you need to add at least one user to access the Web console. To add a new user execute the add-user.bat/add-user.sh script within the bin folder of your AS 7 installation and enter the requested information. See the chapter 10 for more details about it.
Server deployments are managed by the application server by selecting the “Runtime” (1) upper menu, and choosing the Deployments | Manage Deployments (2) label. If you want to add a new application to AS7, just click on the Add Content (3) button in the mid-right area of your console:
An intuitive wizard will guide you through the selection of the application to be added, including the runtime name that will be assigned to it:
The admin console, by default, deploys the application, but does not enable it for use. By clicking on the Enable button, the application is now finally available:
Deploying an application using the Eclipse environment
Eclipse is the most widely used application development environment for Java developers, and it’s also the favorite IDE for JBoss developers, as the JBoss Tools project (http://www.jboss.org/tools) supports the Eclipse environment by providing a set of plugins for JBoss projects.
In the first chapter of this book, we have shown the installation steps for Eclipse Indigo, which is compatible with the JBoss Tools 3.3.0 M3 release.
This release introduces a server adapter, which allows you to start/stop/debug and deploy applications on JBoss AS 7, using the standalone mode.
Deploying applications to JBoss AS 7 is fairly easy once you have your Eclipse plugin installed. Simply reach the Server tab and right-click on the project you want to deploy. Choose Full Publish to deploy your application:
Choosing the packaging style for Eclipse deployments
If you have installed the JBoss Tools up-to-date release, you’ll see that the Server tab offers more options than the traditional Server menu. By double-clicking on the JBoss 7.0 Runtime, you will have access to a tabbed menu, which contains two options: Overview and Deployment. The Deployment option is specific to JBoss tools and lets you choose the deployment location and the packaging style of deployment:
By checking the option Deploy projects as compressed archives, your application will be compressed and packaged.
If you choose to deploy your application as an exploded archive, Eclipse will add a .dodeploy marker file once the application copying has been completed. This will trigger immediate application deployment. See the next section for more information about marker files.
Manual application deployment
When using this approach, the deployment scanner will not directly deploy the applications that are placed in the deployments folder. Rather, it will use a set of marker files, which are used to trigger application re-deployment and capture the result of the operation.
You might wonder why marker files have been introduced in this release of the application server and chosen as the default server option for exploded deployments.
Actually, there are several reasons behind this choice, and all of them are related to the operating system’s file system, Api: as a matter of fact, exploded archives involve the moving/replacing of files in your file system, which should be performed atomically. By atomic operation, we mean that a file system operation needs to be performed as a single operation. Unfortunately, some operating systems such as Windows don’t treat complex file system operations, such as a file moving, as an atomic operation.
As a proof of concept, most Windows users often experience deployment issues on earlier releases of JBoss AS, because, for example, the JVM refuses to release a file handle to META-INF/application.xml or an EJB descriptor
file. That’s because Windows uses a mandatory file lock, which means that it prevents any application from accessing the file. On the other hand, operating systems, such as UNIX, use an advisory file lock, which means that unless an application checks for a file lock, it will not be prevented from accessing the file. Additionally, one more reason why the deployment needs to be revised is the different structure of Java EE 6 applications, which does not mandate any more file descriptors, for example, the web.xml. Earlier releases of the application server used the file descriptors as a trigger to invoke the re-deployment of applications, so you could barely “touch” one of these files to start re-deployment. Without the need to provide file descriptors, it was necessary that a new solid approach for triggering deployments of applications be adopted, which could solve all these issues.
Finally, by using marker files, the application server is able to solve a common issue related to large deployment files. If you ever tried to deploy a large package unit (especially over a network), you might have experienced deployment errors, because the deployment scanner starts deploying before the copy operation is completed, resulting in partially-completed deployments.
Marker files provide the new default approach for JBoss AS 7 exploded deployments. They consist either in empty files, with a suffix, which are placed by the user, or in files that are added by the container to indicate the outcome of an operation.
The most relevant marker file is the .dodeploy , which triggers application re-deployment. As a matter of fact, when we add an explode the deployment and the auto-deploy-exploded attribute is false on the deployment scanner, the logs in the console warn us that the application is still not activated.
05:48:13,438 INFO [org.jboss.as.deployment]
(DeploymentScanner-threads – 1)Found MyApplication.war in deployment directory. To trigger deployment create a file called MyApplication.war.dodeploy
Unix users can trigger deployment by simply using the touch command:
Windows users do not have an equivalent touch command. You have some viable alternatives: one of these is installing the cygwin shell, which provides a Linux look-and-feel environment for Windows.
If you don’t feel worthy using cygwin, then you could simply use a DOS command to copy/replace the .dodeploy file in the deployments folder:
If you feel more adventurous, you can use an advanced syntax of the copy command, which allows you to update the timestamp of an existing file:
copy /b MyApplication.war.dodeploy +,,
Once you have started the deployment process, the application server will reply with two possible outcomes. A deployed marker file (for example, MyApplication.war.deployed) will be placed by the deployment scanner service to indicate that the given content has been deployed into the runtime, and your logs should confirm the outcome:
(DeploymentScanner-threads – 2)