Manually Installing a Maven Artifact in Your Local Repository

I find myself once again in the situation where I have to install the Oracle JDBC driver into my local Maven repository. Usually, this is easily accomplished via:

mvn install:install-file -Dfile=<path-to-file> -DgroupId=<group-id> -DartifactId=<artifact-id> -Dversion=<version> -Dpackaging=<packaging>

See Maven's Guide to installing 3rd party JARs for more details on that. However, this time, I was thinking to go the extra mile and actually figure out a way of doing it entirely manually. This comes in handy if you have, for example, Maven integrated in your IDE and the mvn binary is not available in the command line.

Repository Structure

By default, Maven will store all artifacts and associated files in your home directory under .m2 on Linux and Mac. In there, you will find one or more folders, depending on your Maven setup. However, the only one of interest regarding manual artifact installation is the repository folder. The structure within that folder is rather simple and looks like this:

repository/
|--- <groupId>/[<groupId>]/...
|    |--- <artifactId>/
|         |--- <version>/
|              |--- <artifactId>-<version>.jar
|              |--- <artifactId>-<version>.sha1
|              |--- <artifactId>-<version>.pom
|              |--- <artifactId>-<version>.pom.sha1

There are only three main elements in that structure:

1. groupId
2. artifactId
3. version

Every Maven artifact is grouped into a groupId, which is in itself very similar to Java package names and their organization on disk. In my example, I would like to use the groupId com.oracle for my JDBC driver. To reflect the groupId structure on disk accordingly, where com is the top level groupId and oracle the second level groupId (you can have as many levels as you like), it will have to be nested in subfolders on disk and look like: com/oracle.

Next is the artifactId itself. The Oracle JDBC driver is named ojdbc8.jar. The file extension is not carried along in the artifactId, meaning that the .jar falls away, leaving only ojdbc8 as the artifactId. The 8 in that name reflects with which JDK the Oracle JDBC driver has been compiled with, in this case with JDK 8. However, this number bears no meaning for the actual artifact — the Oracle JDBC driver — so I’m going to drop the number 8 and only use ojdbc as my artifactId.

Last in the directory structure is the version of the driver. Although there was the number 8 in the driver name, it does not reflect the actual version of the driver, just the JDK version for compilation as mentioned above. It is therefore not a good value for the version for my artifact. The actual version of the driver is 12.2.0.1 which is what I’m going to use. In the end, my elements for the driver are:

groupId: com.oracle
artifactId: ojdbc
version: 12.2.0.1

The directory structure looks as follows:

/Users/gvenzl/.m2/repository/com/oracle/ojdbc/12.2.0.1/

Once again, note that the artifactId has no number any longer and the version is indeed 12.2.0.1 — no sign of the 8 any longer.

Copying the JAR file

Now that I have my directory structure, it is time to copy the actual file into the target folder. Maven expects the artifact itself to be named <artifact>-<version>.jar, so my ojdbc8.jar has to become ojdbc-12.2.0.1.jar. That one is easy, I can just copy and rename the file to that:

cp ~/Downloads/ojdbc8.jar /Users/gvenzl/.m2/repository/com/oracle/ojdbc/12.2.0.1/ojdbc-12.2.0.1.jar

Generating the POM File

Now that my JAR file is in place, there is one more file to generate, which is the .pom file, short for “Project Object Model”. It resembles the fundamental unit of work in Maven and without it, Maven won’t pick up the JAR file itself. The .pom file is an XML file with the same name as the .jar file and contains information about the artifact and its dependencies. In the case of the Oracle JDBC driver, there are no dependencies. The content of the XML file just reflects in XML what we already have in the directory structure and looks as follows:

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.oracle</groupId>
    <artifactId>ojdbc</artifactId>
    <version>12.2.0.1</version>
   
    <name>Oracle JDBC Driver</name>
    <description>The Oracle Database JDBC Driver</description>
</project>

See Introduction to the POM – Minimal POM for more details on this.

The modelVersion specifies the version of the XML model used within the file. It is information used internally by Maven — you can and should just leave it at 4.0.0. The groupId, artifactId and version contain the very same information that we have already specified with the directory structure layout: com.oracle, ojdbc, and 12.2.0.1. The name and description are optional, but while we are at it, why not just add a bit more information for future reference? Once you have saved that file as ojdbc-12.2.0.1.pom, you are good to go and can now use the Oracle JDBC driver as a dependency in your Maven projects.

Optional: Generating .sha1 files

For completion's sake, there is one more task left: The generation of the .sha1 files that we have seen in the repository structure above. Those .sha1 files contain checksums of their parent files and are used to verify the integrity of the parent files. In case a file would, for whatever reason, get corrupt, Maven will detect a mismatch of the checksum and complain or download the file again from the remote repository. Generating those files is actually rather easy on Mac, you can just use the shasum command to generate the checksums. In order to complete my setup, I will go ahead and generate the SHA checksum for the .jar and .pom files and store them in the associated .sha1 files:

gvenzl:12.2.0.1: ls -al
total 7896
drwxr-xr-x  4 gvenzl wheel     128 18 Mar 21:54 .
drwxr-xr-x  3 gvenzl wheel      96 18 Mar 21:10 ..
-rw-r--r--@ 1 gvenzl wheel 4036257 18 Mar 21:11 ojdbc-12.2.0.1.jar
-rw-r--r--  1 gvenzl wheel     255 18 Mar 21:41 ojdbc-12.2.0.1.pom
 
gvenzl:12.2.0.1: shasum ojdbc-12.2.0.1.jar
60f439fd01536508df32658d0a416c49ac6f07fb ojdbc-12.2.0.1.jar
gvenzl:12.2.0.1: echo 60f439fd01536508df32658d0a416c49ac6f07fb > ojdbc-12.2.0.1.jar.sha1
 
gvenzl:12.2.0.1: shasum ojdbc-12.2.0.1.pom
2b6459ca12d3d60f6753ea0bc58da6ba8067a983 ojdbc-12.2.0.1.pom
gvenzl:12.2.0.1: echo 2b6459ca12d3d60f6753ea0bc58da6ba8067a983 > ojdbc-12.2.0.1.pom.sha1
 
gvenzl:12.2.0.1: ls -al
total 7912
drwxr-xr-x  6 gvenzl wheel     192 18 Mar 21:55 .
drwxr-xr-x  3 gvenzl wheel      96 18 Mar 21:10 ..
-rw-r--r--@ 1 gvenzl wheel 4036257 18 Mar 21:11 ojdbc-12.2.0.1.jar
-rw-r--r--  1 gvenzl wheel      41 18 Mar 21:55 ojdbc-12.2.0.1.jar.sha1
-rw-r--r--  1 gvenzl wheel     255 18 Mar 21:41 ojdbc-12.2.0.1.pom
-rw-r--r--  1 gvenzl wheel      41 18 Mar 21:55 ojdbc-12.2.0.1.pom.sha1

After this last step, I’m all set now and ready to use the Oracle JDBC driver in my Maven projects.