Developing applications for GlassFish Server

From IntelliJ-Wiki

IntelliJ IDEA Ultimate Edition comes bundled with a plugin for integration with GlassFish Server. With this plugin, called the Glassfish Integration plugin, you can run and debug applications developed for GlassFish Server, and also fully control the server from within the IDE.

This tutorial shows how to develop and run GlassFish-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 GlassFish Server.

You will learn how to:

• Prepare the IDE for developing GlassFish-specific applications (sections "Making sure that the Glassfish Integration plugin is enabled" and "Registering GlassFish Server in IntelliJ IDEA")
• 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 GlassFish Server in IntelliJ IDEA are discussed separately, in a different document called “Debugging applications for GlassFish Server”.

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.
• GlassFish Server, version 3.0.1 or later. You can download the latest version of GlassFish Server from the GlassFish Community Downloads page.
• A Web browser.

Making sure that the Glassfish Integration plugin is enabled

To be able to interact with GlassFish Server, the Glassfish 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 running 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 Glassfish 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 Glassfish Integration 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 gl in the search box. As a result, only the plugins whose names and descriptions contain gl are shown in the list of plugins.

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

5. Click OK in the Settings dialog.

6. If the Glassfish 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 Glassfish Integration plugin is enabled, you should register GlassFish Server in the IDE.

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

Registering GlassFish Server in IntelliJ IDEA

To register GlassFish Server in IntelliJ IDEA:

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 Glassfish Server (3).

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

5. In the Glassfish Home Directory dialog, select the directory where GlassFish Server is installed (1), and click OK (2).

6. Click OK in the Glassfish Server dialog.

IntelliJ IDEA registers the libraries necessary for integration with GlassFish Server. 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 GlassFish Server.

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, MeterToInchesConverter (1) (we are going to develop an application that converts meters into inches)) and the location of the project files in the file system (for example, C:\IdeaProjects\MeterToInchesConverter (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 JDK.

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

We will also need integration with GlassFish Server in our project. To add support for this integration, select the Application Server check box. Make sure that the version of GlassFish Server 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:

• MetersToInchesConverter. This node represents your module. Within this node:
  • The .idea folder and the file MetersToInchesConverter.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 GlassFish 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 GlassFish Server, we have prepared two sample Web pages (.jsp) that form a working Web application.

The logic of the sample application

The suggested sample application converts meters into inches.

A user is asked to input the number of meters for conversion into inches (screen 1). If a valid number is entered, the application performs the conversion and shows the result (screen 2a). If the user provides no input or specifies anything other than a number, he or she gets an error screen (screens 2b and 2c).

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 number of meters and submitting this number to the server (to the page result.jsp).
• result.jsp implementing screens 2a, 2b and 2c. This page will analyze the information provided by the user, and depending on the result, will generate three 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 press F4. Then, copy the following code into the file:

<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<html>
    <head>
        <title>Meters to inches</title>
        <style type="text/css">
            body {
                font-family: verdana, tahoma, sans-serif;
                color: #333366;
                text-align: center;
                margin-top: 50px;
            }
        </style>
    </head>
    <body>
        <p>METERS TO INCHES CONVERSION</p>
        <form method=post action="result.jsp">
            <p>Enter amount in meters (m):
                <input type=text name=meters size=16>
            </p>
            <p><input type=submit value="Convert into inches"></p>
        </form>
    </body>
</html>

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

If you now place the insertion point somewhere within result.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 result.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>Meters to inches</title>
        <style type="text/css">
            body {
                font-family: verdana, tahoma, sans-serif;
                color: #333366;
                text-align: center;
                margin-top: 50px;
            }
        </style>
    </head>
    <body>
        <%
            String headingText;
            String messageText;
            String linkText;
            double conversionFactor = 39.37;
            String metersToConvertString = request.getParameter( "meters" );
            try {
                double metersToConvertDouble = Double.parseDouble(metersToConvertString);
                double inchesDouble = metersToConvertDouble*conversionFactor;
                String inchesString = Double.toString(inchesDouble);
                headingText = "CONVERSION RESULT";
                messageText = metersToConvertString + " m = " + inchesString + " inches";
                linkText = "Convert another number";
            } catch (NumberFormatException nfe) {
                headingText = "CONVERSION FAILED";
                if (metersToConvertString == "") {
                    messageText = "You forgot to specify the number of meters.";
                } else {
                    messageText = "\"" + metersToConvertString + "\" is not a number.";
                }
                linkText = "Try once more";
            }
        %>
        <p><%= headingText %></p>
        <p><%= 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 MetersToInchesConverter:war exploded. The settings for this artifact are shown in the right-hand part of the dialog under Artifact ‘MetersToInchesConverter: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\MetersToInchesConverter_war_exploded. 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\MetersToInchesConverter_war_exploded). 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.)
• 'MetersToInches' 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 GlassFish Server. 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 GlassFish Server 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/MetersToInchesConverter_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 MetersToInchesConverter_war_exploded, that is, the name of the artifact root directory.)

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.

The server settings are shown under Glassfish Server Settings.

By default, the server domain domain1 is selected. (The term server domain is used to refer to an instance of GlassFish Server. When the server is installed, only one domain called domain1 is created.)

The default user name is admin, and the password is not specified. You don't need to change these settings if when installing GlassFish Server, you didn't change the default domain administrator’s name (admin) and didn't specify any password. Otherwise, provide the appropriate settings.

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 (MetersToInchesConverter: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 GlassFish Server, deploys and runs the artifact. If all is well, your default Web browser starts and goes to http://localhost:8080/MeterToInchesConverter_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. (The Update resources option will suffice for the sample application.)

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

Undeploying the artifact and stopping the server

When you have finished testing your application, undeploy the artifact and stop the server:

1. To undeploy the artifact, click the artifact, and then click the Undeploy icon .

2. Then, to stop the server, press CTRL+F2 or click the Stop icon .

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 ‘MetersToInchesConverter: war exploded’.

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 (1) and then select Build (2).

Now if you go to the artifact output directory (in our example this is the directory C:\IdeaProjects\MetersToInchesConverter\out\artifacts\MetersToInchesConverter_war\), you’ll find the artifact there (in our example this is the file MetersToInchesConverter_war.war). This WAR is ready for distribution and deployment to production GlassFish Server.