Developing applications for JBoss AS in IntelliJ IDEA 10

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

After developing the sample application, we will have a look at an artifact specification and a Run configuration that IntelliJ IDEA has created for you (sections “Checking an artifact specification” and “Checking a Run configuration”). (Artifact specifications define the outcome to be produced; Run configurations specify how the applications are to be run.)

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 9 or 10".

Contents

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 10
  • 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.

File:10_jb_010_initial_config_wizard.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.

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.

File:10_jb_011_settings_select_plugins.png

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.

File:10_jb_012_settings_enable_jboss_integration.png

5. If certain plugins that the JBoss Integration plugin depends on are currently disabled, IntelliJ IDEA suggests to enable them.

File:10_jb_013_enable_dependant_plugins.png

Click OK to confirm that you'd like to enable the listed plugins.

6. Click OK in the Settings dialog.

7. 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:10_jb_014_restart.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 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 File:icon_new.png Add, and then click File:icon_new.png JBoss Server.

File:10_jb_010_add_jboss.png

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

File:10_jb_011_jboss_home_1.png

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

File:10_jb_011_jboss_home_2.png

6. Click OK in the JBoss Server dialog.

File:10_jb_011_jboss_home_3.png

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

File:10_jb_012_jboss_libraries.png

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

File:10_jb_010_new_project_from_scratch.png

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:\IdeaProjects\JBossSampleApp).

File:10_jb_011_new_project_name_and_location.png

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.

File:10_jb_012_new_project_source_directory.png

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.

File:10_jb_013_new_project_add_jdk.png

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

File:10_jb_014_new_project_select_jdk_home.png

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

File:10_jb_015_new_project_jdk_set.png

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.

File:10_jb_016_new_project_web_app_support.png

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.

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:10_jb_017_new_project_app_server_support.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

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.

File:10_jb_018_initial_project_structure.png

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.

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

File:023_quick_fix_create_file_process_name.png

Select to create the 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 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.

Checking 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. However, this isn't necessary in IntelliJ IDEA 10.

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:10_jb_010_project_structure_select_artifact.png

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

File:10_jb_011_artifact_name_type_output_dir.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.

Let’s now look at the output directory suggested by the IDE.

The artifact, when built, will be placed into C:\IdeaProjects\JBossSampleApp\out\artifacts\JBossSampleApp_war_exploded.war. The part JBossSampleApp_war_exploded corresponds to the application root on a Web server.

Note the .war at the end. Even though JBossSampleApp_war_exploded.war is a directory (rather than an archive file), to be deployable on JBoss, its name must end in .war.

So, the artifact specification looks fine.

3. Click OK or Cancel in the Project Structure dialog.

Now it’s time to make sure that our application performs as intended.

Checking a Run configuration

To be able to run (or debug) our application artifact in the context of JBoss AS, we need an appropriate Run configuration. Let's see that IntelliJ IDEA has already created one for us.

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:10_jb_010_run_config_initial_state.png

Let's have a quick look at those settings.

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:10_jb_011_run_config_browser_settings.png

The Perform 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:10_jb_012_run_config_update_settings.png

The server settings are shown under JBoss Server Settings. By default, the server instance default is selected; the (server) user and password are not specified. (The server instance in IntelliJ IDEA UI corresponds to what is called a server configuration in JBoss AS documentation.) If necessary, select a different server configuration and specify the user name and password.

File:10_jb_013_run_config_server_settings.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:10_jb_014_run_config_before_launch_options.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:10_jb_015_run_config_deployment.png

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

Running the artifact

To run the application artifact:

  • Make sure that the corresponding Run configuration is shown in the Run configuration selection box on the toolbar. Click File:icon_run.png to the right of this box or press SHIFT+F10.

File:10_jb_010_run.png

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.

File:10_jb_011_starting_page_in_browser.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:10_jb_010_update_button.png

2. In the Update dialog, select Update resources and click OK.

File:10_jb_011_update_dialog.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:10_jb_012_update_on_frame_deactivation.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.)

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

File:10_jb_010_create_war_select_artifacts.png

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

File:10_jb_011_create_war_new_artifact.png

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

File:10_jb_012_create_war_artifact_settings.png

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

File:10_jb_013_create_war_build_artifacts.png

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

File:10_jb_014_create_war_choose_artifacts.png

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.

Personal tools