13 Developing Enterprise Applications

This chapter describes how to use NetBeans IDE support for Java EE to develop Web and server side applications.

This chapter contains the following sections:

• Section 13.1, "About Developing Enterprise Applications"

• Section 13.2, "Adding Modules to the Project"

• Section 13.3, "Adding Resources to the Project"

• Section 13.4, "Editing Deployment Descriptors"

• Section 13.5, "Building Enterprise Applications"

• Section 13.6, "Verifying Enterprise Applications"

• Section 13.7, "Deploying Enterprise Applications"

• Section 13.8, "Packaging Enterprise Applications"

13.1 About Developing Enterprise Applications

An enterprise application is a collection of web application and EJB modules that are configured to work together when deployed to a Java EE application server. The enterprise application contains information about how the modules work together.

The enterprise application also contains information about how the modules work with the application server to which the enterprise application is deployed. For example, if any entity beans use container-managed persistence, the enterprise application tells the application server what transaction services are needed.

An enterprise application has no source files of its own. It only contains deployment descriptors and other configuration files. At compile time, the archive files (JAR files and WAR files) for each of the enterprise application's modules are built and assembled into one Enterprise Archive (EAR) file. This file is deployed to the application server.

The following steps outline the basic process of working with enterprise applications:

1. Create the application and module projects:

   1. Register an application server.

   2. Create the project for the enterprise application.

2. Code the modules:

   1. Create web components in the web application modules.

   2. Create new session beans and message-driven beans.

   3. Generate entity classes or entity beans from existing database tables or use the Database Explorer to create database tables.

   4. Call enterprise beans from web application modules and other enterprise beans.

   5. Use server resources like databases and JMS messages.

3. Configure the application as follows:

   1. Edit the enterprise application's deployment descriptors.

   2. Select libraries and other external resources to bundle with the EAR file.

   3. Set runtime options such as the application's default web page and target application server.

4. Build the project by doing either of the following:

   • Set the project as the main project and choose Run > Build Main Project (F11) from the main menu.

   • Right-click the project node in the Projects window and choose Build.

5. Deploy and run the application by doing either of the following:

   • Right-click the enterprise application project and choose Run. Module projects are compiled, new and changed files are copied from module projects' build directories to the EAR's deployment directory. The EAR "client" is triggered (for example, a web application opens in the browser).

   • Right-click any of the application's module projects and choose Run to deploy the individual module without deploying other modules in the application.

13.2 Adding Modules to the Project

EJB or web application modules can be deployed either by themselves or as a part of an enterprise application. Likewise, Java application clients can be either regular Java applications, or can be full Java EE application client modules. Adding an EJB module, web module, or application client module to an enterprise application lets you further configure the way those modules interact with each other.

When you add a module to an enterprise application, the IDE does the following:

• Lists the module under the enterprise application's Java EE Modules node.

• Adds the module project to the enterprise application project's list of required projects. This means that the module project is cleaned and built whenever you clean and build the enterprise application project.

• Adds a module reference to the enterprise application's general deployment descriptors.

• Packages the module's build output (JAR file or WAR file) into the enterprise application's EAR file when building the project.

13.2.1 How to Add a Module to an Existing Project

To add an existing module to an enterprise application:

1. Open the module project and the enterprise application project.

2. In the Projects window, right-click the enterprise application node for the Java EE application and choose Add Java EE Module.

3. In the dialog box, select the module and click OK.

Note:

You can only add standard projects to an enterprise application. You cannot add free-form projects to an enterprise application because the build and deploy process is not controlled by the IDE.

13.3 Adding Resources to the Project

When you package an enterprise application as an EAR file, the default package includes only those files that are part of the enterprise application. To add a file that is external to the enterprise application to the EAR package, use the Project Properties dialog box. External resources might include JAR files, libraries, or other projects that reside outside the enterprise application.

13.3.1 How to Add an External Resource to an EAR File

To add external resources to an EAR file:

1. In the Projects window, right-click the project node and choose Properties.

2. In the left panel, click Packaging.

3. In the Additional content to include section, click Add JAR/Folder, Add Library, or Add Project.

4. (Optional) Exclude content from the project using the Add Filter button.

13.4 Editing Deployment Descriptors

An enterprise application generally includes two types of deployment descriptors. In Java EE enterprise applications, the descriptor files are optional and you can use annotations to specify most deployment settings and resources. J2EE 1.4 enterprise applications will generally require the following descriptor files.

• A general J2EE deployment descriptor that configures deployment settings on any J2EE-compliant implementation. It describes the enterprise application, which components it uses, how the components relate to each other, and which resources they use. The general enterprise application deployment descriptor is called application.xml.

• A server-specific deployment descriptor that configures deployment settings for the application server to which you are deploying. If you are deploying your application to the Sun Java System Application Server or GlassFish, the IDE provides a graphical deployment descriptor editor and automatically updates the deployment descriptor as you edit your files. For all other application servers, you have to write the server-specific deployment descriptors yourself.

Entries in these files are automatically generated when you add a module to the enterprise application. Both deployment descriptors are XML files that are stored in the enterprise application's META-INF folder. You can edit both files in the Source Editor. The glassfish-application.xml file can also be edited in a visual editor, as described below.

13.4.1 How to Edit an Enterprise Application's Deployment Descriptors

To edit an enterprise application's deployment descriptors:

1. In the Projects window, locate the project and expand its Configuration Files node. Alternatively, in the Files window, expand the project's src/conf subfolder.

2. Double-click the node to open the file. The glassfish-application.xml file opens in the glassfish-application.xml Visual Editor. To open it in the Source Editor, right-click it in the Projects window and choose Edit.

3. Edit the elements. You can use code completion features in the Source Editor to ensure that the elements are syntactically correct.

4. (Optional) Right-click in the Source Editor and choose Validate from the contextual menu to verify that the document follows the XML schema for web deployment descriptors.

Note:

If you have a Java EE 5 or Java EE 6 enterprise application that is deployed to a Java EE container, you can specify most deployment settings using annotations. However, you have the option of using XML descriptors as an alternative to annotations or to supplement or override some annotations.

13.5 Building Enterprise Applications

You can build an enterprise application project from the main menu or an individual project from its popup menu.

13.5.1 How to Build an Enterprise Application Project and Sub-Projects

To build an enterprise application project and its modules:

1. Select the enterprise application project in the Projects window.

2. Choose Run > Build Project (F11) from the main menu.

   Alternatively, you can right-click the project node in the Projects window and choose Build.

Note:

If the enterprise application project is set as the main project, you can choose Run > Build Main Project (F11) from the main menu. You can set a project as the main project by right-clicking a project in the Projects window and choosing Set as Main Project or by choosing Run > Set Main Project from the main menu and selecting the project in the sub-menu.

To build an individual enterprise application project and its modules:

Right-click the project's node in the Projects window and choose Build.

When you build an EJB module as part of an enterprise application, the IDE does the following:

• Compiles the classes for each of the enterprise application's modules to the module projects' build/ear-module folder.

• Places any JAR files, libraries, or directories that are on the classpath of the module projects and are scheduled for inclusion in deployment in the enterprise project's build folder.

• Builds each module's JAR file or WAR file to the module project's dist folder and copies it to the enterprise application project's build folder. The module JAR files and WAR files do not contain any of the module's classpath elements.

• Puts a Class-path entry in each of the modules' manifest file for all included JAR files and puts a . entry if there is at least one directory on the project's classpath scheduled for inclusion in deployment. This mechanism ensures that the JAR files and directories can be used from the modules even if they reside in the EAR project and not in the modules themselves.

• Builds the enterprise application EAR file to the enterprise application project's dist folder.

13.6 Verifying Enterprise Applications

Before you deploy an enterprise application or any stand-alone web or EJB module to the application server, you should verify it, to ensure it is properly implemented to the Java EE specification. When the target server for the project is the Sun Java System Application Server or GlassFish application server, you can use the verifier tool to validate both Java EE and application server-specific deployment descriptors against their corresponding DTD files and display errors and warnings if a module or application is not compliant. You can verify deployment descriptors in EAR, WAR, RAR, and JAR files.

13.6.1 How to Verify a Project's Deployment Descriptors

The verifier tool is not simply an XML syntax verifier. Rules and interdependencies between various elements in the deployment descriptors are verified. Where needed, classes in your module are examined to ensure that what is referred to in the deployment descriptors actually exists and will work when deployed.

To verify a project deployment descriptors:

1. Right-click any web application module, EJB module, or enterprise application project in the Projects window and choose Verify.

   The Verifier window opens and displays all the results.

2. Filter the results according to your needs:

   • Click Failures Only to display only failures.

   • Click Failures and Warnings Only to display only failures and warnings.

3. Make appropriate changes, if any, and verify the project again.

Note:

Not all failures to comply with the Java EE specification will cause the application to fail. However, modules that fail to comply with the specification may not be portable between application servers. The verifier tool helps you ensure your code is not locked into running only on a specific application server.

13.7 Deploying Enterprise Applications

Unless your EJB modules and web application modules are designed to be deployed as stand-alone modules, you should always deploy them by deploying the enterprise application that contains them. If you run the Run or Deploy commands on an individual module that is part of an enterprise application, the IDE only deploys that module itself. Any changes you have made in the other modules in the project are not propagated to the server.

13.7.1 How to Run an Enterprise Application

To run an enterprise application:

In the Projects window, right-click the enterprise application project and choose Run.

1. Sub-projects are compiled.

2. New and changed files are copied from a sub-project's build directory to the EAR's deployment directory.

3. The target application server and domain start.

4. The EAR's deployment directory is used to redeploy the application.

5. The "client" for the EAR is triggered (i.e., a web application opens in the IDE's default browser).

13.7.2 How to Deploy an Enterprise Application

To deploy an enterprise application:

In the Projects window, right-click the enterprise application project and choose Deploy.

1. Sub-projects are compiled.

2. The target application server and domain start.

3. If the application has already been deployed, any active sessions and processes are terminated, and the application is undeployed from the server.

4. The EAR project's deployment directory is cleared (all content is deleted).

5. All the files in the build directories for each of the sub-projects get copied into the EAR's deployment directory.

6. The EAR's deployment directory is used to redeploy the application to the target application server and domain.

13.7.3 How to Undeploy an Enterprise Application

To undeploy an enterprise application (GlassFish):

1. In the Services window, expand the Servers > GlassFish node.

   Note:

   The server must be running and registered with the IDE.

2. Expand the Applications node and locate the enterprise application you want to undeploy.

3. Right-click the enterprise application node and choose Undeploy.

13.8 Packaging Enterprise Applications

Packaging lets you define the JARs, folders, libraries, and projects that are packaged in the EAR file when you build your enterprise application. You can set up a filter to exclude files from the EAR file.

Right-click any standard enterprise application project and choose Properties to specify packaging options for the project.

13.8.1 How to Redeploy a Project to a Different Server

If you are deploying to a different application server, you have to configure the server-specific deployment descriptors and the server resources.

Each project has a target server. The target server is the server that is used when the project is run. You can set the target server to any server which has been registered in the IDE.

To change the target server:

1. Right-click the project node in the Projects window and choose Properties.

2. Select Run in the Project Properties dialog box.

3. Select the new target server from the Server drop-down menu and click OK.