Developing applications for JBoss AS in IntelliJ IDEA Current revision (unreviewed) IntelliJ IDEA Ultimate Edition comes bundled with a plugin for integration with JBoss Application Server (JBoss AS). This plugin, called the JBoss Integration plugin, makes it possible to run and debug applications developed for JBoss AS, and also to fully control JBoss AS from within the IDE. This tutorial shows how to develop and run JBoss AS-oriented applications in IntelliJ IDEA. It offers a set of exercises that cover the overall application development cycle starting from project creation up to running and testing completed application artifacts in the context of JBoss AS. You will learn how to: ▪ Prepare the IDE for developing JBoss-specific applications (sections

“Making sure that the JBoss Integration plugin is enabled” and “Making IntelliJ IDEA aware of JBoss AS”)

▪ Create a new project, add the necessary dependencies for the project module, and develop an application (sections “Creating a new project”, “Adding the dependency on JBoss AS libraries” and “Developing a sample Web application”)

▪ Specify what outcome you want to produce and how you want your application to be run (tested) (sections “Configuring an artifact” and “Creating a Run configuration”)

▪ Run the application to make sure that it performs as intended (section “Running the artifact”)

▪ Produce a deployable WAR for your application (section “Producing a WAR for your application”)

Topics related to debugging applications for JBoss AS in IntelliJ IDEA are discussed separately, in a different document called "Debugging applications for JBoss AS in IntelliJ IDEA".

Contents [hide] 1 Prerequisites 2 Making sure that the JBoss Integration plugin is

enabled 3 Making IntelliJ IDEA aware of JBoss AS 4 Creating a new project 4.1 Exploring the project structure

5 Adding the dependency on JBoss AS libraries 6 Developing a sample Web application 6.1 The logic of the sample application 6.2 The structure of the sample application 6.3 Adding pages to the sample application 7 Configuring an artifact 8 Creating a Run configuration 9 Running the artifact 9.1 Modifying and updating the application while

running it 9.2 Stopping the server 10 Producing a WAR for your application 10.1 Creating the artifact specification 10.2 Building the artifact

Prerequisites To be able to perform the tasks discussed in this tutorial, the following software must be installed on your computer: ▪ IntelliJ IDEA Ultimate Edition, version 9 or later ▪ Java Development Kit (JDK), version 1.5 or later. You can download the

latest version of Sun JDK from http://java.sun.com/javase/downloads/index.jsp.

▪ JBoss Application Server, version 5 or 6. You can download JBoss AS from http://jboss.org/jbossas/downloads/. Find installation instructions in JBoss AS Installation and Getting Started Guide. Important: To be able to integrate IntelliJ IDEA with JBoss AS, you don’t need to set the environment variable JBOSS_HOME as JBoss AS Installation Guide suggests. However, if you set that variable, do that carefully, especially in the case when two or more different versions of JBoss AS are installed on your computer. JBOSS_HOME must point to the version of JBoss AS you are integrating IntelliJ IDEA with.

▪ A Web browser Making sure that the JBoss Integration plugin is enabled To be able to interact with JBoss AS, the JBoss Integration plugin must be enabled in your copy of IntelliJ IDEA. So the first thing to do is to make sure that this is the case. To do that:

1. Start IntelliJ IDEA. If you have just installed IntelliJ IDEA and are now starting it for the first time, the Initial Configuration Wizard will come up at a certain stage of your interaction with the IDE. It will suggest you to select the plugins to be enabled. When you get to the page where you can select the application server plugins, make sure that the check box to the left of JBoss is selected.

Once you’ve done that, you can skip the rest of this section and proceed directly to the next task discussed in this tutorial. Note: The Select Application Server Plugins page of the wizard may be not shown if you have disabled the plugins the application server plugins depend on. These are the JSP Integration, Java EE Integration and Persistence Frameworks Support plugins. If this is the case, enable these plugins first. If it’s not the first time you are starting IntelliJ IDEA and you don’t remember whether you have enabled the JBoss Integration plugin earlier, do the following: 2. Open the Settings dialog (CTRL+ALT+S or File | Settings). 3. In the left-hand part of the dialog under IDE Settings, click Plugins.

4. In the right-hand part of the dialog under Plugins, type JB in the search box. As a result, only the JBoss Integration plugin is shown in the list of plugins. If the Enable check box to the left of the plugin name is not selected, select it.

Click OK in the Settings dialog. 5. If the JBoss Integration plugin was not initially enabled, and you have selected to enable it, IntelliJ IDEA needs to restart for the changes to take effect. In this case the following dialog is displayed.

Confirm that you’d like to restart IntelliJ IDEA by clicking Yes.

Now that you’ve made sure that the JBoss Integration plugin is enabled, you should make IntelliJ IDEA aware of JBoss AS and its location.

Making IntelliJ IDEA aware of JBoss AS To make IntelliJ IDEA aware of JBoss AS and its location: 1. Open the Settings dialog (CTRL+ALT+S or File | Settings). 2. In the left-hand part of the dialog under IDE Settings, click Application Servers. 3. In the right-hand part of the dialog under Application Servers, click Add, and then click JBoss Server.

4. In the JBoss Server dialog, click to the right of the JBoss Home field.

5. In the Select Path dialog, specify the path to the directory where JBoss AS is installed, and click OK.

6. Click OK in the JBoss Server dialog.

IntelliJ IDEA registers the libraries necessary for integration with JBoss AS. You can see their list under Libraries in the Settings dialog.

7. Click OK in the Settings dialog.

Creating a new project Any new development in IntelliJ IDEA starts with creating a project. For the purposes of this tutorial we will create our new project from scratch. When doing so, we will create a Java module, and also add support for Web application development. To create a new project: 1. Select File | New Project. 2. Make sure that Create project from scratch is selected on the first page of the New Project wizard.

Click Next. 3. On the next page of the wizard, specify the name of your new project (for example, JBossSampleApp) and the location of the project file in the file system (for example, C:\SampleProjects\JBossSampleApp).

Note: The path examples in this tutorial are Windows paths. If you are using a Unix-like operating system, you have to translate the paths provided here as examples into the format appropriate for the operating system that you are using. Because we are going to create a project that already contains a Java module, make sure that the Create module check box is selected, and also Java Module is selected under Select type. The default module settings (the name, content root and the location of the module files) will do for our exercises and don’t need to be changed. Click Next. 4. On the next page of the wizard, choose the Create source directory option and accept the default name src.

Click Next. 5. If you have never specified a JDK in your copy of IntelliJ IDEA, you’ll be asked to do that on the next page of the wizard. If this is the case, do the following: Click Configure.

In the Select Path dialog, specify the home directory of the desired JDK and click OK.

Then click Next on the current page of the wizard. 6. On the next page of the wizard, select the technologies to be supported in the project. Because we will be developing a Java Web application, select the Web Application check box. Once you’ve done that, IntelliJ IDEA suggests you to select the desired version of the deployment descriptor file web.xml.

In our exercises, we are not going to work with this file. However, the default version 2.5 will be appropriate for most of the cases. Click Finish to complete the wizard.

Wait while IntelliJ IDEA is creating the necessary project structures. When this process is complete, you can see the structure of your new project in the Project tool window.

Exploring the project structure Of most interest to us is the folder web that represents the root of a Web application that we are going to develop. Let’s have a look at its contents.

As you can see, a very basic starter’s kit is already there. There is a subdirectory called WEB-INF with your web application’s deployment descriptor web.xml and also the file index.jsp intended as the starting page of your application. Soon, we will edit this page, and also add one more page to form a working Web application. Before that, however, we should add the necessary dependencies to our project module.

Adding the dependency on JBoss AS libraries The application that we are going to develop will run on JBoss AS and so will use the resources available on the application server. Now we will make IntelliJ IDEA aware of that by adding the necessary dependencies for our module: 1. Open the Project Structure dialog (CTRL+ALT+SHIFT+S or File | Project Structure).

2. Under Project Settings, select Modules.

3. In the right-hand part of the dialog under Module ‘JBossSampleApp’, click the Dependencies tab.

4. Click Add, and then click Application Server Library.

5. In the Configure Application Server Libraries dialog, make sure that

JBoss <version_number> is selected, and click OK.

The new dependency (that is, the dependency on the JBoss AS libraries) is shown in the Project Structure dialog. 6. Now let’s change the dependency scope from Compile to Provided. To do that, click Compile within the line where the dependency on JBoss AS libraries is shown, and then click Provided.

(The dependency scope Provided means that the dependency exists only at the stage of compilation but not at runtime. Because the application that we are going to develop will run in the context of JBoss AS, the server will itself support the dependency at runtime.) 7. Click OK in the Project Structure dialog.

Now we are ready to start developing our sample application.

Developing a sample Web application To demonstrate how IntelliJ IDEA integrates with JBoss, we have prepared two sample Web pages (.jsp) that form a working Web application.

The logic of the sample application The suggested sample application implements a very basic logon facility that could be used at the entrance to a Web site.

A site visitor is asked for a name (screen 1). If the name is specified (any non-empty string is accepted), the visitor gets access to the site home page where he or she sees a personalized greeting (screen 2). The text of this greeting includes the name that the visitor entered on screen 1. If the visitor attempts to log on without specifying anything as the name on screen 1, he or she gets an error screen (screen 3).

The structure of the sample application As already mentioned, the sample application will contain two JSP pages, namely: ▪ index.jsp that implements screen 1. This page will contain a form for

entering the user name and submitting this name to the server (to the page process_name.jsp).

▪ process_name.jsp that implements screens 2 and 3. This page will

analyze the information provided by the user, and depending on the result, will generate two different versions of the same page. Additionally, if the user has specified a non-empty string as the logon name, this string will be saved in a session object. Thus, this name will be accessible not only from process_name.jsp but also from other pages that may potentially be added to the application.

Adding pages to the sample application Because our application is going to be very simple, we’ll place all the files in the same folder (the web folder where the index.jsp file is located). When developing more complex applications you can create more complex structure to store your application resources in. For example, you may want to create the images subdirectory to store image files, the css subdirectory for stylesheets, and so on. 1. We already have the index.jsp file created for us by IntelliJ IDEA. Let’s open this file in the editor. To do that, double-click this file in the Project tool window, or press F4. Then, copy the following code into the file: <%@ page contentType="text/html;charset=UTF-8" language="java" %> <html> <head> <title>Welcome</title> <style type="text/css"> body { font-family: verdana, tahoma, sans-serif; text-align: center; } h1 { margin-top: 50px; color: #cc6666; } .message_text { color: #996666; } </style> </head> <body> <h1>Welcome!</h1> <form method=post action="process_name.jsp"> <p class="message_text">To access our home page, type your name<br /> in the box underneath and click Log on.</p> <p>User name: <input type=text name=username size=20> <input type=submit value="Log on"></p> </form> </body> </html>

Have a look at the result. Note that process_name.jsp in <form method=post action="process_name.jsp"> is highlighted. If you now hover over the highlighted text, you’ll see a warning reading Cannot resolve file

‘process_name.jsp’ which means that a non-existing file is referenced. If you now place the insertion point somewhere within process_name.jsp, you will see a yellow light bulb (which means that a quick fix is available). Click the light bulb, or press ALT+ENTER, to see the quick fix.

Select to create the file process_name.jsp. The new file is created and opened in the editor. 2. Copy the following code into the file: <%@ page contentType="text/html;charset=UTF-8" language="java" %> <html> <head> <title></title> <style type="text/css"> body { font-family: verdana, tahoma, sans-serif; text-align: center; } h1 { margin-top: 50px; color: #cc6666; } .message_text { color: #996666; } </style> </head> <body> <% String headingText = "Oops!"; String messageText = "You forgot to specify your name."; String linkText = "Back to logon page"; String name = request.getParameter( "username" ); if (name != "") { session.setAttribute( "visitorName", name ); headingText = "Hi, " + name + "!"; messageText = "Thank you for visiting our home page."; linkText = "Log out"; } %> <h1><%= headingText %></h1> <p class="message_text"><%= messageText %></p> <p><a href="index.jsp"><%= linkText %></a></p> </body> </html>

3. Press CTRL+S or select File | Save All to save the changes.

Configuring an artifact Because the source code of our application is ready, it’s time to let IntelliJ IDEA know what outcome we want to get. In other words, it’s time to start specifying the project artifact. As we will see soon, IntelliJ IDEA has already created a specification for one artifact. Now we are going to adjust this specification to our needs, or, in other words, configure the artifact. 1. Open the Project Structure dialog (CTRL+ALT+SHIFT+S or File | Project Structure). 2. Under Project Settings, select Artifacts.

As you can see, one artifact specification already exists, the one for the artifact called JBossSampleApp:war exploded. The settings for this artifact are shown in the right-hand part of the dialog under Artifact ‘JBossSampleApp:war exploded’.

The artifact type is Web Application: Exploded. This type corresponds to a decompressed Web application archive (WAR), a directory structure that is ready for deployment on a Web server.

For the purposes of testing our sample application, this output format is optimal. Let’s now look at the output directory suggested by the IDE. The part of the path C:\SampleProjects\JBossSampleApp\out\artifacts\ is OK. (This is where the corresponding artifact, when built, will go.) What follows (currently JBossSampleApp_war_exploded) corresponds to the application root on a Web server. Even though this is a directory (rather than an archive file), to be deployable on JBoss, its name must end in .war. So let’s add .war at the end.

Important: If you want the artifacts of the Web Application: Exploded type to be deployable on JBoss AS, always make sure that the names of the corresponding application root directories end in .war. This is, basically, it for the artifact specification. 3. Click OK in the Project Structure dialog. Now it’s time to make sure that our application performs as intended. To do that, we will create an appropriate Run configuration, and then run the artifact.

Creating a Run configuration Now we are going to create the Run configuration appropriate for running our artifact in the context of JBoss AS and specify the associated settings. 1. Open the Run/Debug Configurations dialog (Run | Edit Configurations). 2. Click , click JBoss Server, and then click Local.

Note: Don’t select Remote because currently (20.07.2010) IntelliJ IDEA does not support integration with JBoss AS running on a remote computer. 3. Specify the name of the new Run configuration (for example, SampleJBossConfig) by editing the text in the Name field.

4. Make sure that the Start browser check box is selected under Open browser. (When you run your application artifact using this configuration, the default Web browser on your computer will start automatically and go to the URL specified in the Startup page field.) In the Startup page field, specify the following URL: http://localhost:8080/JBossSampleApp_war_exploded/. (Because we have

not specified the context root for our web application artifact explicitly, the context root will default to JBossSampleApp_war_exploded, that is, the name of the artifact root directory but without the extension .war.)

5. Select the Update resources on frame deactivation check box. (Your application artifact will be automatically updated each time when you switch from the IDE to a different application, for example, a Web browser. Note that this feature is available only for the artifacts of the Web Application: Exploded type.)

6. Under JBoss Server Settings, select default from the Server Instance list. (The server instance in IntelliJ IDEA UI corresponds to what is called a server configuration in JBoss AS documentation. We are going to use the default server configuration.)

Note that now there is a warning displayed in the lower part of the dialog:

Let the IDE fix the problem for you:

7. Click . IntelliJ IDEA switches to the Deployment tab to show that the JBossSampleApp:war exploded artifact will be deployed to the server at JBoss AS startup. Also note that the Build ‘JBossSampleApp:war exploded’

artifact check box under Before launch is now selected. This is fine: the IDE will build the artifact each time before running it. For example, if you make changes to your source code, IntelliJ IDEA will build all the files affected by these changes before running the application.

If you are using version 5 of JBoss AS, the Run configuration at this step is ready. Click OK in the Run/Debug Configurations dialog and proceed to running the artifact. For JBoss AS6 you, additionally, have to change the settings for the server shutdown script: 8. Click the Startup/Connection tab. The default settings for the startup script are OK. You don’t need to change them. (The Startup script field should contain <JBoss_directory>\bin\run.bat –c default or <JBoss_directory>\bin\run.bat. Both these commands start the default configuration of JBoss AS.) The shutdown script should be <JBoss_directory>\bin\shutdown.bat –S. So the defaults for this script must be changed. To do that:

Clear the Use default check box, and then click .

In the Select Path dialog, select the shutdown.bat file and click OK. (If you

are using a Unix-like operating system, you should select shutdown.sh instead. The files shutdown.bat and shutdown.sh are both located in the <JBoss_directory>\bin directory.)

Edit the text in the Shutdown script field: after shutdown.bat (or shutdown.sh), type a blank space and then –S (the letter case is important!). Finally, the Shutdown script field should contain <JBoss_directory>\bin\shutdown.bat –S. Click the Parameters button .

In the Configure VM and Program Parameters dialog, delete the text in the Program Parameters field and click OK.

9. Click OK in the Run/Debug Configurations dialog.

Running the artifact To run the artifact using the Run configuration that you have just created: ▪ Make sure that the SampleJBossConfig Run configuration is shown in

the corresponding box on the toolbar. Click to the right of this box or press SHIFT+F10.

IntelliJ IDEA starts JBoss AS and runs the artifact in its context. If all is well, your default Web browser starts and goes to http://localhost:8080/JBossSampleApp_war_exploded/. Thus, you see the starting screen of your application.

Play with the application in the browser for a little while to make sure that it works fine.

Modifying and updating the application while running it While the server is running you can modify the source code of your application and observe the corresponding changes in the browser: 1. After you’ve made changes in one or more of your source files, switch to the browser window. 2. Use the reload (or refresh) command in the browser. (To be able to see the changes in the application behavior or appearance, you have to make

sure that your browser does not cache your pages.) (Your application artifact is updated automatically each time when you switch from the IDE to a different application. This happens because you selected the Update resources on frame deactivation option when creating your Run configuration. Note that you can turn this option on and off right in the Run tool window. This is done by clicking the Update Resource On Frame Deactivation icon .)

Stopping the server When you have finished testing your artifact, stop the server. To do that, press CTRL+F2 or select Run | Stop.

Producing a WAR for your application When you get to the stage when you are happy with your application, you may want to place it in a WAR which you will then distribute. To do that in IntelliJ IDEA, you should: 1. Create an appropriate artifact specification 2. Build the artifact

Creating the artifact specification To create the artifact specification: 1. Open the Project Structure dialog (CTRL+ALT+SHIFT+S or File | Project Structure), and select Artifacts.

2. Click , click Web Application: Archive, and then click For ‘JBossSampleApp: war exploded’.

3. If necessary, change the artifact settings in the right-hand part of the dialog.

(We’ve made no changes to the settings suggested by the IDE.) 4. Click OK in the Project Structure dialog.

Building the artifact To build the artifact: 1. Select Build | Build Artifacts.

2. In the Choose Artifact to Build dialog, select the desired artifact and click OK.

Now if you go to the artifact output directory (in our example this is the directory C:\SampleProjects\JBossSampleApp\out\artifacts\JBossSampleApp_war\), you’ll find the artifact there (in our example this is the file JBossSampleApp_war.war). This WAR is ready for distribution and deployment to production JBoss server.