I find myself once again in the situation that 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 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 how to do it entirely manually. This comes in handy if you have, for example, Maven integrated in your IDE and the mvn binary not available to yourself in the command line.
The Maven repository
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:
- groupId
- artifactId
- version
Ever 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 following: 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, in this case with JDK 8. However, this number bears no meaning for the actual artifact which is 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 but 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 according 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 that 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 and 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 there is one more task outstanding: 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.
Gerald on IT 