NetBeans Platform CRUD Tutorial Using Maven

This tutorial needs a review. You can edit it in GitHub following these contribution guidelines.

This tutorial demonstrates how to use the Maven build framework to create a simple NetBeans Platform application that can read from and write to a database. In this document you will use Maven archetypes to create the NetBeans Platform application and module, and the Swing UI toolkit and "Matisse" GUI Builder to create window components.

This document is based on the Ant-based NetBeans Platform CRUD Application Tutorial and can be used to understand some of the differences between using Ant and Maven to develop NetBeans Platform applications. After you understand how Maven is different from Ant, you can easily proceed through other tutorials on the NetBeans Platform Learning Trail.

You do not need to download Maven because it is bundled with the IDE. Optionally, use your own download of Maven, in which case use the Options window to configure your Maven settings.
This is not a beginners tutorial. Before starting this tutorial, it is important that you familiarize yourself with the following introductory Maven documentation:

Watch this YouTube movie before beginning to work on the tutorial because it shows the steps you will take below:

Creating and Running the Sample Application

In this section, you set up a sample application provided by NetBeans IDE. The sample application access data and displays data in a Maven-based NetBeans Platform application, similar to the application you create in this tutorial. Successfully running the sample application and displaying data will be useful in determining whether the database connection is set up correctly.

  1. Choose File > New Project (Ctrl-Shift-N) to open the New Project wizard. Select the Samples | Maven category and then select "CRUD Sample Application":

maven crud 72 sample 1
Figure 1. screenshot

Click Next.

  1. Specify a location:

maven crud 72 sample 2
Figure 2. screenshot

Click Next.

  1. Change, if needed, the location of libraries that the sample will use:

maven crud 72 sample 3
Figure 3. screenshot

Click Finish.

Once the project is opened, if you see projects with [unloadable] in the display name, that means something is wrong with the POM file or that plugins are missing:

maven crud 72 setup 2
Figure 4. screenshot

Developers seeing the above in the IDE are typically new to Maven or are setting up Maven for the first time on their system.

If you see the above, wait for the Maven dependencies to download, which is a process that you can follow by looking in the status bar of the IDE. Once the downloading has completed, and not before, right-click each project and choose "Build with Dependencies". Also see this issue if problems relating to missing plexus-utils.jar occur. If problems continue, refer to the links at the start of this document, to set up your Maven repository correctly.

  1. Examine the project structure:

maven crud 72 sample 4
Figure 5. screenshot

The project structure above is explained here:

  • maven crud 72 Maven2Icon NetBeans Platform Application. This project is a Maven reactor project for the NetBeans Platform application, which lists the modules to include and the location of the project’s repositories. This project does not contain any sources. The IDE generates the modules containing the sources and resources in sub-directories of this project.

  • maven crud 72 suiteicon NetBeans Platform based application. The NetBeans Platform application project enumerates included modules; permits interactive runs; produces various kinds of packaging, such as ZIP by default, but optionally JNLP, NBMs; holds functional tests. Each module project specifies its own compile dependencies, while the app project’s dependencies are anything additional that should be present at runtime. For example, that includes, by default, the whole platform cluster, that is, the set of modules constituting the "platform" cluster. The app project could include other clusters, or subsets of clusters, or whatever plugins you want included in your app which are not used as compilation dependencies. At a minimum, core.startup and its transitive dependencies are included.

  • maven crud 72 nbmicon Platform application branding resources. This project contains the global resources used for branding the application, such as the splash screen.

  • maven crud 72 nbmicon sample NetBeans Module. The project that contains the source code for accessing the database and displaying it in a window.

1. You need to have access to a database server. This tutorial uses the JavaDB database server, together with a sample database. Before continuing, start the JavaDB server in the Services window by connecting to the sample database. Right-click on the connection node shown below and choose Connect:

maven crud 72 sample 5
Figure 6. screenshot

If it is not already available, an easy way to make the JavaDB database server available is to register an instance of GlassFish that is bundled with the IDE. The JavaDB database server and a sample database are included with the GlassFish server.

  1. Right-click the NetBeans Platform based application ( maven crud 72 suiteicon) and choose Run. The application starts up and should show the following:

maven crud 72 sample 6
Figure 7. screenshot

Use Window | Customer to open the Customer window, wait a few seconds, and you should see your data displayed:

maven crud 72 sample 7
Figure 8. screenshot

  1. Open the editor window and notice that the selected customer’s details are shown in the editor. Make changes in the editor and save them and then notice that the viewer is automatically updated. Changes you make are stored in the database.

If you were not able to complete the above steps, do not continue with the rest of the tutorial. If you encountered problems relating to Maven repositories and unresolved Maven dependencies, refer to the introductory Maven links at the start of this document.

Since your database is being accessed correctly and your Maven dependencies have been correctly resolved, you are now ready to continue creating your own CRUD application.

Creating the NetBeans Platform Application

In this section you use the New Project wizard to create a NetBeans Platform application from a Maven archetype.

  1. If it is still open, close the sample application you created in the previous section. You do not need the sample anymore and leaving it open may cause confusion while you work on your real application.

  1. Choose File > New Project (Ctrl-Shift-N) to open the New Project wizard. Select NetBeans Application from the Maven category:

maven crud 72 pic1
Figure 9. screenshot

Click Next.

  1. Type MavenPlatformCRUDApp for the Project Name and set the Project Location:

maven crud 72 pic2
Figure 10. screenshot

Click Next.

  1. Select the version of the NetBeans APIs you’d like to use and type the name of a NetBeans module that you’d like to be created together with the application, in this case MavenPlatformCRUDApp-dbaccess:

maven crud 72 pic3
Figure 11. screenshot

Click Finish.

Depending on the availability of JARs as specified by Maven dependencies in your repository, the IDE will spend some time downloading Maven dependencies. Once the downloading of Maven dependencies is completed, you should see the following:

maven crud 72 pic4
Figure 12. screenshot

The above project structure is explained here:

  • maven crud 72 Maven2Icon app. This project is a Maven reactor project for the NetBeans Platform application, which lists the modules to include and the location of the project’s repositories. This project does not contain any sources. The IDE generates the modules containing the sources and resources in sub-directories of this project.

  • maven crud 72 nbmicon branding. This project contains the global resources used for branding the application, such as the splash screen.

  • maven crud 72 nbmicon dbaccess. The project that will contain the Java sources you will create in the next section.

  • maven crud 72 suiteicon parent. The NetBeans Platform application project enumerates included modules; permits interactive runs; produces various kinds of packaging, such as ZIP by default, but optionally JNLP, NBMs; holds functional tests. Each module project specifies its own compile dependencies, while the app project’s dependencies are anything additional that should be present at runtime. For example, that includes, by default, the whole platform cluster, that is, the set of modules constituting the "platform" cluster. The app project could include other clusters, or subsets of clusters, or whatever plugins you want included in your app which are not used as compilation dependencies. At a minimum, core.startup and its transitive dependencies are included.

1. Right-click the "parent" project and choose "Build with Dependencies". After the process has completed, right-click the "app" project and choose Run. You should see the default splash screen and then the main window of the application:

maven crud 72 result 1

You have successfully set up the application and are now ready to begin generating the application’s model classes.

Creating the Model

In this section you generate Java Persistence API (JPA) entity classes from tables in the Java DB database. To create the entity classes and to use JPA in your application, you need to have access to a database server and the JPA persistence provider libraries.

Though this tutorial uses the JavaDB database server, you can later configure the application to use other database servers.

Generating Entity Classes From the Database

In this section you use a wizard to generate entity classes in the dbaccess module.

  1. Right-click the Source Packages of the dbaccess module and choose New > Other. Select Entity Classes from Database in the Persistence category:

maven crud 72 generate 1
Figure 13. screenshot

Click Next.

  1. Select the Java DB sample database from the Database Connection drop-down list. Select the Customer table from the Available Tables list and click Add. When you click Add, the related tables, such as DiscountCode, which could vary depending on your version of the database, are also added to the list of Selected Tables list:

maven crud 72 generate 2
Figure 14. screenshot

Click Next.

  1. Leave the package name as suggested, that is, com.mycompany.mavenplatformcrudapp. Make sure that the Create Perisistence Unit and Generate Named Query Annotations are selected:

maven crud 72 generate 3
Figure 15. screenshot

  1. Click Finish. When you click Finish, the IDE generates an entity class for each selected table. The IDE also generates the persistence.xml file in the META-INF package under the Other Sources node in the src/main/resources directory:

maven crud 72 generate 4
Figure 16. screenshot

  1. Right-click the dbaccess module and choose Build. Depending on their availability in your repository, several JARs may now start to be downloaded.

Adding the DerbyClient as a Runtime Dependency

In this section you will add derbyclient.jar library as a dependency.

  1. Right-click the Dependencies node of the dbaccess module and choose Add Dependency:

maven crud 72 derby 1
Figure 17. screenshot

The Add Library dialog appears.

  1. Specify the library by typing org.apache.derby for the "Group ID", derbyclient for the "Artifact ID", select runtime from the Scope drop-down, and choose the latest version available:

maven crud 72 derby 3
Figure 18. screenshot

Notice that you can use code completion to help you throughout the above dialog:

maven crud 72 derby 2
Figure 19. screenshot

Click Add.

  1. Expand the Runtime Dependencies node in the Projects window and you can see that the derbyclient library is listed as a dependency:

maven crud 72 derby 4
Figure 20. screenshot

You have now registered the Derby database dependency for your module.

In this section, you created a module that now contains entity classes for the tables you’d like to access, together with a persistence.xml file providing the data access information, and new dependency declarations in the project’s POM file.

Creating the Viewer

In this section, we create a simple prototype GUI component that accesses our data and displays it.

  1. Right-click the dbaccess module and choose New | Window. Define the window to be opened in the "explorer" position and let it open when the application starts:

maven crud 72 new window 1
Figure 21. screenshot

Click Next.

  1. Set "Viewer" as the class name prefix.

maven crud 72 new window 2
Figure 22. screenshot

Click Finish.

  1. In the Source tab of the new window, redefine the constructor as follows:

public ViewerTopComponent() {

    initComponents();

    setName(Bundle.CTL_ViewerTopComponent());
    setToolTipText(Bundle.HINT_ViewerTopComponent());

    setLayout(new BorderLayout());
    JTextArea area = new JTextArea();
    add(area, BorderLayout.CENTER);

    EntityManager entityManager = Persistence.createEntityManagerFactory("com.mycompany_MavenPlatformCRUDApp-dbaccess_nbm_1.0-SNAPSHOTPU").createEntityManager();
    Query query = entityManager.createNamedQuery("Customer.findAll");
    List<Customer> resultList = query.getResultList();
    for (Customer c : resultList) {
        area.append(c.getName() + " (" + c.getCity() + ")" + "\n");
    }

}

  1. Right-click in the editor and choose Fix Imports (Ctrl-Shift-I). Make the choices below in the dialog that appears:

maven crud 72 dep 1
Figure 23. screenshot

Click OK. The import statements at the top of the class should now be as follows:

import java.awt.BorderLayout;
import java.util.List;
import javax.persistence.EntityManager;
import javax.persistence.Persistence;
import javax.persistence.Query;
import javax.swing.JTextArea;
import org.netbeans.api.settings.ConvertAsProperties;
import org.openide.awt.ActionID;
import org.openide.awt.ActionReference;
import org.openide.util.NbBundle.Messages;
import org.openide.windows.TopComponent;

  1. Right-click the parent project and choose Clean. Right-click the app project and choose Build with Dependencies and, once the process has completed, right-click it again and choose Run.

After the splash screen is shown, you should see this:

maven crud 72 result 2
Figure 24. screenshot

The simple prototype is finished. You’re using very few NetBeans APIs at the moment, but you’re able to retrieve data from your database and display it in your view component.

Creating the Editor

In this section, you add the start of an editor module to the application. You then continue with the instructions in the Ant based NetBeans Platform application tutorial to set up and listen to the selection and populate the editor with objects found there.

  1. In the New Project dialog, choose NetBeans Module in the Maven category:

maven crud 72 new editor 1
Figure 25. screenshot

Click Next.

  1. Name the module MavenPlatformCRUDApp-editor. On the next page, set the project location to the folder where the other modules are found, which is within the parent folder. Click Next.

  1. Deselect the OSGi checkbox:

maven crud 72 new editor 2
Figure 26. screenshot

Click Finish. Because you set the project location to be the folder where the parent project is found, you see that the new module is created and visible within the parent project:

maven crud 72 new editor 3
Figure 27. screenshot

  1. Though the new module is now part of the parent project, it is not part of the app project yet. Therefore, when you run the application, your module will currently not be included. Let’s include it now. In the app project, right-click Dependencies, click Add Dependency, select the Open Projects tab, and choose the editor module.

1. In the same way as you did in the previous section, create a new window, in the editor module. This time, it should be opened at start up in the "editor" position, with "Editor" as its class name prefix.

  1. Right-click the parent project and choose Clean. Right-click the app project and choose Build with Dependencies and, once the process has completed, right-click it again and choose Run.

After the splash screen is shown, you should see this:

maven crud 72 new editor 4
Figure 28. screenshot

  1. Now that you have completed the steps above, you can refer to the Ant-based NetBeans Platform CRUD Application Tutorial, since all the Java code in that tutorial is applicable to the application you are creating here.

You have a basic understanding of how developing with Maven is different from Ant. You can easily proceed through other tutorials on the NetBeans Platform Learning Trail and apply them to your Maven scenarios.

Send Us Your Feedback

See Also

This concludes the CRUD Tutorial. This document has described how to use the Maven build framework to create a new NetBeans Platform application with CRUD functionality. For more information about creating and developing applications, see the following resources.

If you have any questions about the NetBeans Platform, feel free to write to the mailing list, dev@platform.netbeans.org, or view the NetBeans Platform mailing list archive.