Developing applications for JBoss AS

From IntelliJ-Wiki

Jump to: navigation, search

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 intended 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:

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

Contents

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 12.
  • Java Development Kit (JDK), version 1.6 (also referred to as 6) or later. 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.

File:I12JB01InitConfigWizardJBoss.png

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 (e.g. by pressing CTRL+ALT+S).

3. In the left-hand part of the dialog under IDE Settings, click Plugins.

File:I12GF02SettingsPlugins.png

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.

File:I12JB02SettingsPluginsJBoss.png

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.

File:I12GF04RestartIDEA.png

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 register JBoss AS in the IDE.

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

Registering JBoss AS in IntelliJ IDEA

To register JBoss AS in IntelliJ IDEA:

1. Open the Settings dialog (CTRL+ALT+S).

2. In the left-hand part of the dialog under IDE Settings, click Application Servers.

File:I12GF05SettingsAppServers.png

3. In the right-hand part of the dialog under Application Servers, click File:I12IconAdd.png (1), and then click JBoss Server (2).

File:I12JB03SettingsAppServersPlusJBoss.png

4. In the JBoss Server dialog, click File:icon_ellipsis.png to the right of the JBoss Home field.

File:I12JB04JBossServerDialogInitial.png

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

File:I12JB05JBossHomeDirDialog.png

6. Click OK in the JBoss Server dialog.

File:I12JB06JBossServerDialogFinal.png

IntelliJ IDEA registers the .jar files necessary for working with JBoss AS. You can see their list under Libraries. (An application server library that contains the corresponding files is created.)

File:I12JB07SettingsAppServersFinal.png

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

So now we are going to create a project with a Java module, and support for Web application development and integration with JBoss AS.

To create such a project:

1. If no project is currently open in IntelliJ IDEA, click Create New Project on the Welcome screen. Otherwise, select New Project from the File menu.

As a result, the New Project wizard opens.

2. In the left-hand pane, select Java Module (1).

3. In the right-hand part of the page, in the Project name field, type JBossSampleApp (2).

File:I12JB08NewProjectName.png

4. If you have never configured a JDK in IntelliJ IDEA (in such a case <None> is shown the Project SDK field), you should do it now.

Click New (1) and select JDK (2).

File:I12SetUpProjectSDKWithSteps.png

In the Select Home Directory for JDK dialog that opens, select the directory in which you have the desired JDK installed (1), and click OK (2).

File:I12GF12JDKHome.png

The JDK you have just specified is shown in the Project SDK field.

File:I12JB09NewProjectJDKSet.png

5. On the next page of the wizard, select the technologies to be supported in the project.

To add support for Web application development, select the Web Application check box.

Once you’ve done that, you can select the version of the Servlet specification to be supported.

File:I12GF14NewProjectWebApp.png

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.

File:I12JB10NewProjectServerSet.png

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.

File:I12JB11InitialProjectStructure.png

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.

File:10_jb_010_sample_application_logic.png

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.

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, replace all the file contents with the following:

<%@ 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.

File:I12JB12LightBulb.png

Click the light bulb, or press ALT+ENTER, to see the quick fix.

File:I12JB13CreateMissingFile.png

Select Create File process_name.jsp.

The new file is created and opened in the editor.

Note: The quick fix may be unavailable if the HTML Tools plugin is disabled. Enable this plugin if you want to use advanced HTML/CSS editing features. To do that, use the procedure similar to that for enabling the JBoss Integration plugin.

2. Copy the following 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>
        <%
            String headingText = "Oops!";
            String messageText = "You forgot to specify your name.";
            String linkText = "Back to logon page";
            String name = request.getParameter( "username" );
            if (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>

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.

File:I12GF19ProjectStructureArtifacts.png

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

File:I12JB14ArtifactLayout.png

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 pane 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.

File:I12JB15ArtifactLayoutDetailed.png

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.

File:I12JB16RunConfig.png

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

File:I12JB17RunConfigBrowser.png

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.

File:I12JB18RunConfigUpdates.png

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.

File:I12JB19RunConfigServer.png

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

File:I12JB20RunConfigBeforeLaunch.png

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.

File:I12JB21RunConfigDeployment.png

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

Running the artifact

To run the application artifact:

  • Click File:I12RunIcon.png to the right of the run configuration selector on the toolbar, or press SHIFT+F10.

File:I12JB22Run.png

IntelliJ IDEA builds the artifact, starts JBoss AS and deploys the artifact onto the server. You can monitor this process in the Run tool window that opens in the lower part of your workspace.

File:I12JB23RunToolWindow1.png

Then, 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.

File:002AppInBrowserE1JB.png

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 File:00_icon_update.png.

File:I12JB24RunToolWindowUpdate.png

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 or JBoss EAP 6, use the Redeploy option.)

File:I12JB25UpdateDialog.png

To enable the application auto-update on frame deactivation and observe the corresponding changes in the browser:

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

File:I12JB26RunToolWindowUpdateOnFD.png

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

Note: This way of updating the application may not work for JBoss AS 7 or JBoss EAP 6. In such a case, use the Update action with the Redeploy option.

When you have finished testing your application, stop the server and close the Run tool window.

Stopping the server

To stop the server, do one of the following:

  • Click File:I12StopIcon.png in the Run tool window.
  • Select Run | Stop.
  • Press CTRL+F2.

Closing the Run tool window

To close the Run tool window, do one of the following:

  • Click File:I12CloseIcon.png.
  • Press CTRL+F4.

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

2. Select Artifacts.

File:I12GF19ProjectStructureArtifacts.png

3. Click File:I12IconAdd.png (1), point to Web Application: Archive (2), and then click For 'JBossSampleApp: war exploded' (3).

File:I12JB27CreateWarArtifact.png

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

File:I12JB28WarArtifactSettings.png

5. Click OK in the Project Structure dialog.

Building the artifact

To build the artifact:

1. Select Build | Build Artifacts (1, 2).

File:I12GF39BuildArtifacts.png

2. In the Build Artifact menu, point to the artifact of interest (1) and then select Build (2).

File:I12JB29BuildArtifact.png

Now if you go to the artifact output directory (<project_folder>\out\artifacts\JBossSampleApp_war\, by default), you’ll find the artifact there (the file JBossSampleApp_war.war). This WAR is ready for distribution and deployment to production JBoss server.

What's next?

Now that you have an idea of how to develop applications for JBoss AS in IntelliJ IDEA, you may be interested in studying the following tutorial:

Personal tools