IntelliJ IDEA and Maven Notes

Russell Bateman
July 2019

This is part of an introduction to practical IntelliJ IDEA. Some of the exercises and notes below assume, for concrete examples, the use of sample code linked from Developing using HAPI—By Example, in particular, source code ExampleParseMessages.java and EncapsulatedData.java.


How to add missing libraries to an IDEA/Maven project

This is done by creating a new <dependency> in the <dependencies> paragraph in pom.xml.


How to find the right Maven dependencies?

(What's exposed here is an explanation that helps with JARs of all kinds and not just HAPI. However, many JARs are not arranged in such organized fashion.)

If you know the name of the library, which is a Java archive or JAR, you can just add it. To get the <dependency> statement correct, Google for it this way. Let's use the base library of James Agnew's HL7 application programming interface for HL7 v2.x (HAPI v2). Search for:

maven hapi hl7 v2

In the results, we see ca.uhn.hapi - Maven Repository. (In the package name, UHN stands for University Health Network, it's a teaching hospital in Canada that James Agnew, software author, works or maybe worked for.)

When we click to see this Maven repository, we see a list of JARs:

  • ca.uhn.hapi.fhir (FHIR is HL7 v4.x; we don't want that)
  • ca.uhn.hapi hapi-base
  • ca.uhn.hapi hapi-structures-v25 (HL7 v2.5)
  • ca.uhn.hapi hapi-structures-v24 (HL7 v2.4)
  • etc...

For our present purposes, we think that, whatever other libraries we'll need, we will certainly need the base library. So, we click on the hyper link, hapi-base.

This takes us to a list of versions. Typically, we will want to choose the latest, possible version that is not also an alpha or beta release. In our case, we see that the latest released libraries for HL7 v2 work came out in June, 2017. We click on the hypertext link, 2.3.

We're using Maven in our build. There's a tab containing the correct dependency groupId, artifactId and version. We can scrape that to include it in our pom.xml (but we don't want the comment with it):

<dependency>
  <groupId>ca.uhn.hapi</groupId>
  <artifactId>hapi-base</artifactId>
  <version>2.3</version>
</dependency>

We copy this, then find the <dependencies> paragraph in pom.xml, and paste it in. We choose a place ahead of very utilitiarian libraries like JUnit. In our case, this time, we'll choose to drop it in just before the sub-paragraph for junit.

Because we want to make pom.xml easy to maintain and we want to be able to change the versions of JARs we get easily in one place instead of having to search all dependencies and edit them, we create a macro, ${hapi_v2.version} in the <properties> paragraph:

  <properties>
    <hapi_v2.version>2.3</hapi_v2.version>
    .
    .
    .

Then, our dependency becomes:

<dependency>
  <groupId>ca.uhn.hapi</groupId>
  <artifactId>hapi-base</artifactId>
  <version>${hapi_v2.version}</version>
</dependency>

When you make changes to pom.xml, IDEA will pop up a dialog to confirm that you that "Maven projects need to be imported." You can click Import Changes or Enable Auto-Import to make this happen (or make it happen automatically from now on).


Once a library dependency has been added to pom.xml, ...

...how to get IntelliJ IDEA to see and use it in the code?

Bring up the Java editor on the code exhibiting red errors. If you already had valid import statemens in Java, you will quickly see red disappear. If not, then you'll begin seeing little pop-ups near identifiers that are in red in the code because missing. You can (Alt+Enter) react to those pop-ups by confirming them which will cause IDEA to add import statements.

Caution: when you confirm and the symbol is ambiguous (meaning, there is more than one option or library from which the symbol can be satisfied), you must be careful to choose exactly the right one—by name and by package path. See How to recover from a mistake made in [this] method below.


How to find a package or symbol whose JAR you don't know?

When you cannot easily resolve a symbol because you don't know the name of the JAR or you don't even know what collection (like HAPI above) to go looking for it in, you should use "find jar":

Let's assume you don't know what to put into pom.xml in order to get a symbol and package path named javax.mail.MessagingException.

Bring up a browser search engine, like Google. Type

find jar javax.mail.MessagingException

You might get results like:

javax.mail.MessagingException — findJAR.com

...and many others. Use the search results similarly to how you did the longer exercise above on how to find the right Maven dependencies. The result should, ultimately, give you the name of a JAR, in this case, mail.jar. That's what you should go looking for using the earlier explanation.


How to recover from a mistake made in the method just above?

The trick is to find just the right one and just the right version. This can be very hard and trial and error may be needed. Trial and error might include doing what we demonstrated to get a new dependency above only to discover that what you've done...

  • ...doesn't resolve all missing symbols you suspect should be in that library,
  • ...doesn't offer the signatures (method name plus arguments—and you still get compiler errors),
  • ...crashes when run (because the method called is broken in your context, etc.).