Developing applications for JBoss AS

From IntelliJ-Wiki

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 and develop an application (sections "Creating a new project" and "Developing a sample Web application")
• Run the application to make sure that it performs as intended (sections Exploring an artifact specification, "Exploring a run configuration" and "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".

Before you start

To be able to perform the tasks discussed in this tutorial, make sure that the following software is installed on your computer:

• IntelliJ IDEA Ultimate Edition, version 11.
• Java Development Kit (JDK), version 1.6 (also known as JDK 6). You can download the necessary version of Oracle JDK from the Java SE Downloads page.
• JBoss Application Server, version 5 or later. You can download the necessary version of JBoss AS from the JBoss AS Downloads page.
• 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. This wizard lets you disable the plugins that you are not going to use. (All the plugins bundled with the IDE are enabled by default.)

When you get to the page where the application server plugins are listed, 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.

If it’s not the first time you are starting IntelliJ IDEA and you don’t remember whether you have the JBoss Integration plugin enabled, 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 plugins whose names and descriptions contain jb are shown in the list.

If the check box to the left of JBoss Integration is not selected, select it.

5. Click OK in the Settings dialog.

6. 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 Restart.

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.

(For more information on working with plugins, see Managing Plugins in IntelliJ IDEA Help.)

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 (1).

3. In the right-hand part of the dialog under Application Servers, click Add (2), and then click JBoss Server (3).

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

5. In the JBoss Home Directory dialog, specify the directory where JBoss AS is installed (1), and click OK (2).

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. (To find out why a project is needed, see Project in IntelliJ IDEA Help.)

For the purposes of this tutorial we will create our new project from scratch. When doing so, we will create a Java module. We will also add support for Web application development and integration with JBoss AS.

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 (1)) and the location of the project files in the file system (for example, C:\IdeaProjects\JBossSampleApp (2)).

Because we are going to create a project that already contains a Java module, make sure that the Create module check box is selected (3), and also Java Module is selected under Select type (4).

The default module settings (the name, content root and the location of the module file) 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 so on the next page of the wizard. (If the page discussed below is not shown, you already have a JSDK configured. In this case, proceed to completing the wizard.)

Click Configure.

In the Select Home Directory for JSDK dialog, specify the installation directory of the desired JDK (1) and click OK (2).

As a result, the corresponding JDK appears under Project SDK.

Click Next.

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, you can select the version of the Servlet specification to be supported.

The default version 2.5 will do for our exercises.

We will also need integration with JBoss AS in our project. To add support for this integration, select the Application Server check box. Make sure that the version of JBoss AS you registered in IntelliJ IDEA earlier is selected in the Application Server list.

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

Let’s have a look at the project structure created by IntelliJ IDEA.

There are two top-level nodes in this structure:

• JBossSampleApp. This node represents your module. Within this node:
  • The .idea folder and the file JBossSampleApp.iml are used to store configuration data for your project and module respectively.
  • The src folder is intended for Java source files.
  • The web folder is for your Web application assets such as Web pages, images, style sheets, configuration files, etc. This folder already contains the subdirectory WEB-INF with the Web application deployment descriptor web.xml. Also in the web folder is the file index.jsp. This file is intended as the starting page of your Web application.
• External Libraries. This is a category that represents all the "external" resources necessary for your development work. Currently in this category are the .jar files that make up your JDK and the JBoss AS library files.

(For more information on tool windows in general and the Project tool window in particular, see IntelliJ IDEA Tool Windows and Project Tool Window in IntelliJ IDEA Help.)

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 implementing 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 implementing 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 structures 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 select the file and 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.

Exploring an artifact specification

Because the source code of our application is ready, it looks like it's time to let IntelliJ IDEA know what outcome we want to get or, in IntelliJ IDEA terms, specify the project artifact.

As we are about to see, IntelliJ IDEA has already created a specification for one artifact. And what is more, this specification is optimal for testing our application. Now let's see that this is so.

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 seems to be the best.

The artifact, when built, is placed into <project_folder>\out\artifacts\JBossSampleApp_war_exploded.war. This is specified in the Output directory field.

The artifact layout is shown in the left-hand panel of the Output Layout tab.

The <output root> at the top represents the output directory (<project_folder>\out\artifacts\JBossSampleApp_war_exploded.war). The rest of the elements shown have the following meanings (and are directly related to corresponding source directories and resources that we have already seen in the Project tool window when exploring the project structure):

• The WEB-INF directory corresponds to the project directory WEB-INF with all its contents. (When the artifact is built, the project directory WEB-INF with all its contents is copied into the output directory.)
• 'JBossSampleApp' compile output represents compiled Java classes whose sources are located in the src project directory. As you can see, these are placed into WEB-INF\classes in the output directory.
• 'Web' facet resources represent your Web pages, images, style sheets, configuration files, etc. contained in the project folder web.

To see a more detailed picture of the artifact configuration, select the Show content of elements check box.

So, the artifact specification looks fine.

3. Click OK in the Project Structure dialog.

Now it’s time to see how our application is going to be run.

Exploring a run configuration

Applications in IntelliJ IDEA are run according to what is called run/debug configurations. Such configurations, generally, should be created prior to running an application. (For more information, see Running, Debugging and Testing in IntelliJ IDEA Help.)

In our case, we don't need to create a run configuration. IntelliJ IDEA has already created one for us for running the application artifact in the context of JBoss AS. Let's take a quick look at this run configuration.

1. Open the Run/Debug Configurations dialog (Run | Edit Configurations).

The only existing run configuration (which has the name of the version of JBoss AS that you are using) is selected and its settings are shown in the right-hand part of the dialog.

Note that the Start browser check box is selected under Open browser and the Startup page field contains http://localhost:8080/JBossSampleApp_war_exploded. This means that when you run your application artifact, the default Web browser on your computer will start automatically and go to the specified URL. (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.)

The On 'Update' action and On frame deactivation options define how and when your application is updated when being run. (Frame deactivation means switching from IntelliJ IDEA to a different application, for example, a Web browser.) Since these options may be controlled when running the application (in the Run tool window), we'll postpone the discussion of these options until then. At the moment, just make sure that the Show dialog option is on. This will let you select the necessary update option prior to actually performing the update.

The server settings are shown under JBoss Server Settings. By default, the user name and password are not specified. If necessary, specify the user name and password.

The Before launch options define the actions to be performed when the run configuration is activated (i.e. run or rerun). As you can see, IntelliJ IDEA will build your application artifact (JBossSampleApp:war exploded) 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 switch to the Deployment tab, you'll see that the IDE will deploy (or redeploy) the application artifact each time the server is started or restarted.

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

Running the artifact

To run the application artifact:

• Click to the right of the run configuration selector on the toolbar, 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 then update the application artifact on the server. There are two different ways of doing that in the Run tool window. You can initiate the application update yourself by performing the Update action. In addition to that, there is an option of auto-updating the artifact on frame deactivation, that is, on switching from IntelliJ IDEA to a different application, for example, a Web browser.

To update the application artifact by performing the Update action:

1. After you’ve made changes in one or more of your source files, click .

2. In the Update dialog, select the necessary update action and click OK. (If you are using JBoss AS 5 or 6, the Update resources option will suffice for the sample application. In the case of JBoss AS 7, use the Redeploy option.)

1. After you’ve made changes in one or more of your source files, click the Update Resource on Frame Deactivation button . (This button is a toggle which turns the corresponding option on or off.)

2. Switch to the browser window.

3. 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.)

Stopping the server

When you have finished testing your artifact, stop the server. To do that, you have the following alternatives:

• press CTRL+F2.
• click in the Run tool window.
• 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 (1), click Web Application: Archive (2), and then click For ‘JBossSampleApp: war exploded’ (3).

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

4. Click OK in the Project Structure dialog.

Building the artifact

To build the artifact:

1. Select Build | Build Artifacts.

2. In the Build Artifact menu, select the desired artifact and then select Build.

Now if you go to the artifact output directory (in our example this is the directory C:\IdeaProjects\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.