- Update: Removed unnecessary eclipselink dependency 2017-02-27 14:46
- Update: Changed skipTests value to false in Surefire dependency in the complete pom file 2017-02-27 15:18
If you are not using Maven then you should. If you are using Maven then you are likely cutting and pasting snippets of pom.xml file examples and hoping for the best. In this article I will present the pom.xml file that I require my students to use in an e-commerce project course. Not everything in it is required and you likely have libraries you need that are not in my example. After reviewing my pom.xml you should be able to make all the changes you need. You can find the complete file at the end of this article.
This is my third article on the pom.xml file that I have written. The last time I wrote about it was two years ago and while Maven has not changed I have learned more about the pom.xml. If you are not using Maven because a practical explanation of the elements required in the real world are rare, then hopefully this will change your mind.
Whether you work from the command line or with an IDE such as NetBeans (my favourite) one issue comes up over and over again. How do I make sure all the libraries I need get included in my project? It used to be for me that I needed to track down the web site for every library I wanted to use, download the jar and manually paste it into a location on the classpath or a specific folder in IDE. Packaging an application for distribution was also an issue because I needed to ensure that all the right jars were included in the uber archive, jar or war, I planned to distribute.
There is more to Maven than just including libraries. I use it to upload Java programs to my Raspberry Pi and execute them. I use Maven to control when I want unit testing to occur. There is much, much more it can do. The one task that drives my continual writing about Maven is that I use it in the classroom. I teach software development at Dawson College in the final year of the program. I like teaching coding but I am not fond of teaching the necessary plumbing to make systems work. I use NetBeans in my courses because it does not need to be managed the way Eclipse or IntelliJ needs to be. I use Maven for the same reason. I provide my students with a standard Maven pom.xml file that ensures that they all begin from the same baseline. Here is that pom.xml file.
Every XML document should begin with an XML declaration. While the version has remained 1.0, it is the encoding attribute that is important. UTF-8 means that this document is encoded using the Unicode standard in which the first 128 characters map to Unicode. For more information on UTF-8 I recommend http://www.fileformat.info/info/unicode/utf8.htm
This is the root tag for this XML document. An XML document must be well formed and valid. Well formed means that all tags are properly nested and have a matching closing tag. Valid means that the tags and attributes you are using are part of this specific XML language. Testing for validity requires a schema and that is what is referred to in the root project tag. The schema is also used by the IDE to validate while you enter the tags into the file.
As the comment says, its always 4.0.0.
Maven manages the thousands of libraries available by using the combination of the groupId and artifactId as a unique identifier for each library. This is commonly called the GAV. These are usually expressed using the naming convention for Java packages or as a reverse domain name but they can be anything. You’ll see a non-package name for the MySQL dependency. When a library is a dependency for a project it is identified by this combination. This is also the directory in your local repository where this jar or other file type is stored.
The version number for a project is an important piece of data that you should be updating during development. Over time there may may be many versions of a project and other developers may depend on a specific version. The most recent version may contain changes that could break the work of other developers who have a dependency on your work. Two special optional terms are SNAPSHOT for a project in development and FINAL for a production ready project.
Select the appropriate archive packaging type, either jar, war or ear.
I like to use the artifactId for the project name but you can use any name you want. Notice that you can refer to a tag in the file using substitution notation and by appending it to the term ‘project’.
The three sections above are used to identify you. They are optional if you are an amateur. If you are a professional they are mandatory.
Properties represent data that another section of the pom may need access to. This way this data can be stored in one place and not repeated where it is needed. Endorsed represents a directory where files with the same name and type as those present in the Java installation are stored. This way the file in the endorsed folder will be used rather than the one supplied in the Java installation. The encoding of the project appears here as does the version of Java you will be using.
When using Arquillian there are numerous libraries that may be required. Exactly what they are may change from version to version. A dependencyManagement section refers to special files classifid as bill of materials that in turn will include the necessary Arquillian libraries.
As my comment above says, the dependencies are libraries that must be available to your project. They will all be downloaded to your local repository. This will allow your IDE to ensure you are using classes and methods from these libraries correctly. They are further classified by the scope tag. If there is no scope tag then the file associated with the dependency will be added to your final archive file. If the scope tag shows ‘provided’ then the required files are in the container you will be running in, such as Glassfish/Payara, and do not need to be added to your archive. If the scope is ‘test’ then the files are only added to an archive used for testing such as what Arquillian produces.
The metamodel generator dependency invokes a process to create meta model classes dynamically. This will allow you to use identifiers rather than strings in certain types of JPA queries so that refactoring (renaming) is supported.
Thanks to BillyTheKid for pointing out that the dependency for eclipselink, now removed, is not needed, only the metamodel dependency is required.
Not every required Arquillian dependency that my students need is in one of the two bom dependencyManagement entries so we need to add these two dependencies. If you are using Arquillian then you need these too.
For the first time I will be having my students use Selenium as part of their testing. Selenium is actually an independent system that can even be placed in a Java desktop application. Here it will be run as a unit test. Selenium requires, in addition to the Java library, a standalone executable program to connect it to a specific browser. I found this extremely convenient library, webdrivermanager, that will download all the required executables and run them as required.
Selenium uses slf4j as the interface to log4j. That is why these dependencies are all listed as test scope. A student recently ran into a problem when a library they were using in their project also needed slf4j. The solution was to remove scope so that the libraries were added to both the production and test archive files.
Here in the build section of the pom.xml. Here you can identify filesor folders folders that are required but are not part of a standard Maven project.
Plugins are modules that add features to Maven. The Maven war plugin is used when we wish to modify how the war file is built. It is not required for the projects my students build. Unfortunately, leaving this plugin out results in a warning that reads “Warning: selected war files include a WEB-INF/web.xml which will be ignored”. This statement is false and the project’s web.xml is properly processed. Adding this plugin without any settings eliminates the warning message.
The Surefire pligin controls running tests and it allows me to easily turn on or off testing with the skipTests tag.
In preparing this article I removed two plugins that proved to be redundant and removed unnecessary tags from a third. These plugins were there because the articles that I read in researching Maven showed them. These Maven entries continue to appear on StackOverflow and in other articles. May I suggest that when writing about Maven or answering a question you consider testing your code by removing plugins. Otherwise we will propagate inflated Maven pom.xml files.
Here is the full pom.xml.