Creating an Enterprise Application Using Maven
This tutorial demonstrates how to create a simple enterprise application using NetBeans IDE and Maven archetypes. The tutorial also provides some explanations and tips on using the IDE to create and build Maven applications.
In this tutorial you create an enterprise application that is packaged as an EAR archive and deployed to GlassFish Server Open Source Edition 3. You create the application using the Maven Enterprise Application archetype in the New Project wizard. The application contains an EJB project that contains a persistent entity class, a message-driven bean and a session bean facade for the entity. The application also contains a web project that contains two servlets.
To follow this tutorial, you need the following software and resources.
This document assumes you have some basic knowledge of, or programming experience with, the following technologies:
Before starting this tutorial you may want to familiarize yourself with the following documentation.
You can download a zip archive of the finished project.
Using Maven in the IDE
Support for Maven is fully integrated in NetBeans IDE. Developing a project that uses the Maven framework is nearly identical to developing a project in Ant. However, there are some differences that are related to the way Maven builds projects and works with dependencies. The following tips can help you avoid some problems if you are creating a Maven application for the first time.
Check your Maven settings
If this is your first Maven project you will want to check the Maven configuration settings in the Options window. Starting with NetBeans IDE 7.0, Maven is bundled with the IDE and installed when you install the IDE.
Update your Maven repositories
Local and remote Maven repositories are used for code completion and when building projects. You should update the indexes for the Maven remote repositories to ensure that any artifacts you may need are readily available when you develop your project. You can configure how often the IDE checks for updates in the Maven tab of the Options window. You can perform an immediate check for updates and explore your local and remote Maven repositories in the Services window.
When you click Update Indexes, the IDE will check and download the most recent index for each of your Maven remote repositories. An index represents the current state of the artifacts located in the repository and is used to provide a reference to the artifacts that are available to your application. By default, the IDE does not download an artifact from a repository until the artifact is explicitly required.
You can search for an artifact by right-clicking the Maven Repositories node in the Services window and choosing Find.
For more details about using Maven in NetBeans IDE, see the section on Configuring Maven in the Creating a Maven Swing Application Using Hibernate tutorial and also Best Practices for Apache Maven in NetBeans IDE.
Creating the Maven Enterprise Application Project
The goal of this exercise is to create an enterprise application project using the Maven Enterprise Application archetype bundled with the IDE. The enterprise application archetype will also create an EJB project and a webapp project.
The IDE includes several Maven archetypes in the New Project wizard to help you quickly create common NetBeans project types such as enterprise application projects (EAR), web application projects (WAR) and EJB module projects (JAR). The wizard also enables you to create projects from archetypes in registered remote repositories.
When you click Finish, the IDE creates the following projects from the Maven Enterprise Application archetype.
After you create the enterprise application project, the enterprise application project will be badged if any dependencies are unavailable. If you expand the Dependencies node for the MavenEnterpriseApp-ear project, you can see if any required libraries are missing or not on the classpath. The enterprise application project has dependencies on the JAR and WAR that will be packaged and available after you compile the EJB project and the web project. You can see that MavenEnterpriseApp-ejb and MavenEnterpriseApp-web are listed as dependencies.
In some cases you will see a Maven icon in the status bar that you can click to run a priming build and resolve missing dependencies.
Specify the target server (NetBeans IDE 7.0)
In NetBeans IDE 7.0 you need to set the target server in the project's Properties window.
When developing Maven applications you typically do not need to specify an application server until you build the application. However, to take advantage of some of the code generation features in the IDE, it is recommended that you set the target server before you start writing your code. By setting the deployment server, the IDE is able to recognize the technologies supported by the server and enable various options in some wizards to generate code that is optimized for that server.
By specifying GlassFish as the deployment server before coding, the IDE will enable the option of selecting JTA in the wizard for creating the persistence unit. You can also select to use any of the datasources registered with the server.
Note. If you do not specify GlassFish Server 3, the default transaction type when you create the persistence unit will be RESOURCE-LOCAL. You will need to edit the persistence.xml file manually to specify JTA if you want the container to manage the transactions. You will also need to specify a database connection instead of a registered data source in the New Persistence Unit wizard.
Coding the EJB Project
The EJB project contains the business logic of the application. In this application the GlassFish container will manage transactions using the Java Transaction API (JTA). In this tutorial you will create an entity class, a message-driven bean and a session facade for the entity class in the EJB project.
Creating the Persistence Unit
In this exercise you create a persistence unit in the EJB project. The persistence unit specifies the database connection details and specifies how transactions are managed. For this application you will specify JTA in the New Persistence Unit wizard because you want the GlassFish server to manage the transactions.
To create the persistence unit, perform the following steps.
When you click Finish, the IDE creates the XML file persistence.xml and opens the file in the editor. In the Projects window, you can see that the file was created in the Other Sources > src/main/resources > META-INF directory. The file contains details about connecting to the database and how transactions are managed. If you click the Source tab in the editor, you can see the following details about the persistence unit.
... <persistence-unit name="com.mycompany_MavenEnterpriseApp-ejb_ejb_1.0-SNAPSHOTPU" transaction-type="JTA"> <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider> <jta-data-source>jdbc/sample</jta-data-source> <exclude-unlisted-classes>false</exclude-unlisted-classes> <properties> <property name="eclipselink.ddl-generation" value="create-tables"/> </properties> </persistence-unit>
You can see that JTA is specified as the transaction type and that the application will use the registered datasource jdbc/sample.
Creating the Entity Class
In this exercise you will create an entity class in the EJB project to represent the objects that will be persisted to the database. To create the NewsEntity entity class, perform the following steps.
When you click Finish, the entity class NewsEntity.java opens in the Source Editor. In the Source Editor, add some fields by performing the following steps.
Creating the Message-Driven Bean
In this exercise you will create a message-driven bean in the EJB project. A message-driven bean is an enterprise bean that enables the asynchronous exchange of messages. The NewsApp application uses a message-driven bean to receive and process messages sent to the queue by a servlet in the web module.
To use a message-driven bean in an application, the connector resources used by the bean need to be registered with the server. When you are deploying to the GlassFish server, you can create the resources directly on the server through the Admin Console or you can create the resources on deployment by specifying the details in the glassfish-resources.xml descriptor file. When the application is deployed to the server, the server registers the resources based on the descriptor file. When you use the New File wizard in the IDE to create a message-driven bean, the IDE will generate the elements in the descriptor file for you.
In a Maven project, the glassfish-resources.xml file is located in the src/main/setup directory under the project node in the Files window.
Creating the Session Bean
In this exercise you will use a wizard to create a session bean facade for the NewsEntity entity class. The wizard will generate create, edit and find methods that will be accessed from the servlets in the webapp project.
When you click Finish the IDE generates two session facade classes: AbstractFacade.java, and NewsEntityFacade.java which extends the abstract facade class. The abstract facade class defines several methods that are commonly used with entity classes.
Interfaces are optional in Java EE 6 and Java EE 7. The local interface is optional and the servlet in the web module can access the session bean directly via a no-interface facade.
Coding the Web Application
In this section you will create two servlets in the webapp project.
Creating the ListNews Servlet
In this exercise you will create the ListNews servlet that will be used to display a list of posted messages. You will use annotations to inject the session facade and access the findAll method and retrieve the posted messages.
Creating the PostMessage Servlet
In this exercise you will create the PostMessage servlet that will be used to post messages. You will use annotations to inject the JMS resources you created directly into the servlet, specifying the variable name and the name to which it is mapped. You will then add the code to send the JMS message and the code for the HTML form for adding a message.
Building the Application with Maven
Now that you are finished coding the application, you can use Maven to build the enterprise application. In this section you will build and package the projects in an EAR archive. The EAR archive will contain an EJB JAR archive and a WAR archive. After you create the EAR archive you can deploy the archive to the target server.
Working With Project Dependencies
In this exercise you will examine the POM (pom.xml) of the web project and modify the POM to prevent unnecessary artifacts from being included in the WAR when packaging. Each Maven project contains a pom.xml file that contains details about the contents of archives. Any external libraries that are required by the project are listed as dependencies in the POM. You can modify the POM to specify the dependencies that need to be included or should be excluded when packaging the archive.
In this application, the EJB JAR and the WAR archives will be packaged in an EAR archive. If you look at the pom.xml of the MavenEnterpriseApp-ear project, you can see that the EJB and WAR are declared as dependencies.
If you look at the pom.xml of the web project in the editor you can see that the EJB archive is declared as a dependency and the scope is specified as provided. When the value of the scope element of an artifact is provided, the artifact will not be included during packaging. The web project requires the EJB archive as a dependency, but for this application you do not want the EJB archive to be included in the WAR during packaging because the EJB archive will be available and provided as part of the EAR archive.
You can open pom.xml in the editor and click the Graph tab to see a visual representation of the project dependencies. If you are using an older version of the IDE you can right-click in pom.xml in the editor and choose Show Dependency Graph. You can place your cursor over an artifact to display a tooltip with the artifact details.
Perform the following steps to modify the POM of the web project to add a scope element to the dependency on the javaee-api artifact.
Building with Dependencies
The Maven build framework proceeds through a specific sequence of phases, and each phase consists of one or more goals and can be configured to use various Maven plugins. The Build with Dependencies menu item is mapped to the install phase of the Maven build lifecycle and is configured to use the Reactor plugin. When you choose Build with Dependencies in the popup menu, Maven builds the application and any required dependencies and copies the build artifacts to the local repository.
You can modify how Maven phases and goals are mapped to menu actions in the Actions panel of the project's Properties dialog box.
To build the EAR archive, perform the following step.
When you build the EAR project using the Reactor plugin, the sub-projects that are dependencies of the EAR project are built before the EAR project is built. The Output window displays the build order.
The results of the build are also displayed in the Output window.
After you build the EAR project, you can see the final EAR archive inside the target directory under the EAR project node in the Files window.
If you used the default artifact name com.mycompany, you can use the Maven Repository Browser to view the build artifacts by expanding com.mycompany in the Local Repository.
Deploying and Running the Application
This section describes two methods for deploying the EAR archive to the server. You can deploy the application to the GlassFish server by using a menu action in the IDE or by using the Deploy tool in the GlassFish Admin Console.
Deploying and Running the Application from the IDE
In this exercise you will use the Run action to deploy the EAR archive to the the GlassFish server. After you deploy the application you will open the ListNews page of the application in your browser and add a message.
When you add a message with the PostMessage servlet, the message is sent to the message-driven bean for writing to persistent storage, and the ListNews servlet is called to display the messages in the database. The list of messages in the database retrieved by ListNews often does not yet contain the new message because our message service is asynchronous.
Compile on Save and Deploy on Save are enable by default on Maven projects that specify GlassFish server as the target server. For example, if you modify a save a servlet, you can reload the servlet in the browser and view the changes without redeploying the application.
Note if you are using NetBeans IDE 7.0.
Deploying From the GlassFish Admin Console
In this exercise you will deploy the EAR archive using the Deploy tool in the GlassFish Admin Console.
When you click OK, the GlassFish deploy tool deploys the application.
Note. If you deploy the application using the deploy tool in the GlassFish Admin Console, you will also need to manually create the resources that are required by the application if they do not exist.
Downloading the Solution Project
You can download the solution to this tutorial as a project in the following ways.
For more information about using NetBeans IDE to develop Java EE applications, see the following resources:
You can find more information about using Enterprise Beans in the Java EE 7 Tutorial.
To send comments and suggestions, get support, and keep informed on the latest developments on the NetBeans IDE Java EE development features, join the nbj2ee mailing list.