Skip to content

Building a Driver JAR with Dependencies

Jump to bottom
Terry Chow edited this page Jun 21, 2023 · 6 revisions

Remove unwanted dependencies before building (Optional step)

Dependencies are managed within the pom.xml file. The file is found at the root of the driver project. In the pom.xml file, look for the <dependencies></dependencies> tag pair. Within this tag pair are the driver's listed dependencies. Each dependency is denoted by a <dependency></dependency> tag pair. Remove unwanted dependencies by removing the <dependency>....</dependency> per dependency.

  1. Navigate to the project root and open the pom.xml in a text editor.

  2. Look for the <dependencies></dependencies> tag pair. Within here, there should be dependencies listed and denoted within <dependency></dependency> tag pairs.

  3. Identify and remove any unwanted dependencies and then save the pom.xml file.

For example, the start of the dependency list within the pom.xml file should look something like the following:

	<dependencies>
		<dependency>
			<groupId>com.azure</groupId>
			<artifactId>azure-security-keyvault-keys</artifactId>
			<version>${azure-security-keyvault-keys.version}</version>
			<optional>true</optional>
		</dependency>
		<dependency>
			<groupId>com.azure</groupId>
			<artifactId>azure-identity</artifactId>
			<version>${azure-identity.version}</version>
			<optional>true</optional>
			<exclusions>
				<exclusion>
					<groupId>stax</groupId>
					<artifactId>stax-api</artifactId>
				</exclusion>
			</exclusions>
		</dependency>
		<dependency>
			<groupId>com.microsoft.azure</groupId>
			<artifactId>msal4j</artifactId>
			<version>1.13.3</version>
			<optional>true</optional>
		</dependency>
                ...
                ...
                ...
                ...
                ...
	</dependencies>

If the azure-security-keyvault-keys dependency is removed, the resulting list should now look like the following:

	<dependencies>
		<dependency>
			<groupId>com.azure</groupId>
			<artifactId>azure-identity</artifactId>
			<version>${azure-identity.version}</version>
			<optional>true</optional>
			<exclusions>
				<exclusion>
					<groupId>stax</groupId>
					<artifactId>stax-api</artifactId>
				</exclusion>
			</exclusions>
		</dependency>
		<dependency>
			<groupId>com.microsoft.azure</groupId>
			<artifactId>msal4j</artifactId>
			<version>1.13.3</version>
			<optional>true</optional>
		</dependency>
                ...
                ...
                ...
                ...
                ...
	</dependencies>

Building the shaded driver (Building a driver JAR with dependencies)

Building a shaded driver JAR builds a single JAR files with all dependencies embedded in it. Make sure you have git, maven and an appropriate JDK version installed on your machine and you have cloned the source repository:

git clone https://github.com/microsoft/mssql-jdbc.git

Next, we'll need to checkout the version of the driver to build. For example, the current stable release version of the driver JAR (as of writing this guide) is 12.2.0 but that will change in the future. The driver versioning for the checkout process is named according to v<major-version>.<minor-version>.<patch-version>. In order to checkout 12.2.0 version of the driver and future driver versions, navigate to the root of the cloned driver repository and execute the following git command for the driver versions you want:

git checkout v<major-version>.<minor-version>.<patch-version>

ie. For a driver versioned 12.2.0: 

git checkout v12.2.0

Next, we'll add a build profile to the pom.xml of the driver project. To do so, we'll need to copy and paste one of the following build profiles into the pom.xml file. Specifically, to add our shaded driver JAR build profile, we need to paste the profile within the <profiles></profiles> tag pair in the pom.xml file. After the profile is added, we can then build the driver project with the following command (note that this example uses the jre11 shaded profile):

mvn clean install -DskipTests -T C1 -Pshadedjre11

The profiles are shadedjre8 and shadedjre11 as listed below.

For clarity, the exact steps are the following:

  1. Clone the driver project.
git clone https://github.com/microsoft/mssql-jdbc.git
  1. Navigate to the root of the cloned driver repository. Checkout the version of the driver you want. If you want driver version 12.2.0, prepend a 'v' to the driver version and supply that to the command below. Eg. use v12.2.0 in the command below.
git checkout <driver-version>

eg. git checkout v12.2.0

  1. Next, navigate to the root of the project directory. In here should be a file called pom.xml. Open this file in your favorite text editor.

  2. Copy your desired shaded driver build profile. In other words, copy the desired build profile that builds the driver with dependencies for your desired JDK version (shadedjre11 can be used for JDK 11 or higher). Again, the corresponding profiles are listed below within code blocks.

  3. Paste your copied profile within the <profiles></profiles> tag pair eg. paste your profile on a new line under the first <profiles> tag. (Note that it's <profiles> and not <profile> -- there is a 's'. If you do a search eg. CTRL-F for <profiles>, place your copied profile right under the first match.

  4. Save the pom.xml file.

  5. Run mvn clean install -DskipTests -T C1 -P<your-shaded-profile>. The resulting JAR file will be in the target subfolder.

  • To build shadedjre8, run mvn clean install -DskipTests -T C1 -Pshadedjre8
  • To build shadedjre11, run mvn clean install -DskipTests -T C1 -Pshadedjre11

shadedjre8

		<profile>
			<id>shadedjre8</id>
			<build>
				<finalName>${project.artifactId}-${project.version}.jre8${releaseExt}</finalName>
				<plugins>
					<plugin>
						<groupId>org.apache.maven.plugins</groupId>
						<artifactId>maven-compiler-plugin</artifactId>
						<version>3.8.0</version>
						<configuration>
							<excludes>
								<exclude>**/com/microsoft/sqlserver/jdbc/ISQLServerConnection43.java</exclude>
								<exclude>**/com/microsoft/sqlserver/jdbc/SQLServerConnection43.java</exclude>
								<exclude>**/com/microsoft/sqlserver/jdbc/SQLServerJdbc43.java</exclude>
							</excludes>
							<testExcludes>
								<exclude>**/com/microsoft/sqlserver/jdbc/connection/ConnectionWrapper43Test.java</exclude>
								<exclude>**/com/microsoft/sqlserver/jdbc/connection/RequestBoundaryMethodsTest.java</exclude>
								<exclude>**/com/microsoft/sqlserver/jdbc/JDBC43Test.java</exclude>
							</testExcludes>
							<source>1.8</source>
							<target>1.8</target>
						</configuration>
					</plugin>
					<plugin>
						<groupId>org.apache.maven.plugins</groupId>
						<artifactId>maven-javadoc-plugin</artifactId>
						<configuration>
							<source>8</source>
						</configuration>
					</plugin>
					<plugin>
						<groupId>org.apache.maven.plugins</groupId>
						<artifactId>maven-jar-plugin</artifactId>
						<version>3.1.1</version>
						<configuration>
							<archive>
								<manifestFile>${project.build.outputDirectory}/META-INF/MANIFEST.MF</manifestFile>
							</archive>
						</configuration>
					</plugin>
					<plugin>
						<groupId>org.apache.maven.plugins</groupId>
						<artifactId>maven-surefire-plugin</artifactId>
						<version>3.0.0-M1</version>
						<configuration>
							<!-- Exclude [xJDBC42] For tests not compatible with JDBC 4.2 Specifications -->
							<excludedGroups>${excludedGroups}, xJDBC42</excludedGroups>
						</configuration>
					</plugin>
					<plugin>
                		<groupId>org.apache.maven.plugins</groupId>
                		<artifactId>maven-assembly-plugin</artifactId>
                		<version>3.1.1</version>

                		<configuration>
                		    <descriptorRefs>
                		        <descriptorRef>jar-with-dependencies</descriptorRef>
                		    </descriptorRefs>
                		</configuration>

                		<executions>
                		    <execution>
                		        <id>make-assembly</id>
                		        <phase>package</phase>
                		        <goals>
                		            <goal>single</goal>
                		        </goals>
                		    </execution>
                		</executions>
            		</plugin>
				</plugins>
			</build>
		</profile>

shadedjre11

		<profile>
			<id>shadedjre11</id>
			<build>
				<finalName>${project.artifactId}-${project.version}.jre11${releaseExt}</finalName>
				<plugins>
					<plugin>
						<groupId>org.apache.maven.plugins</groupId>
						<artifactId>maven-compiler-plugin</artifactId>
						<version>3.8.0</version>
						<configuration>
							<excludes>
								<exclude>**/com/microsoft/sqlserver/jdbc/SQLServerJdbc42.java</exclude>
							</excludes>
							<source>11</source>
							<target>11</target>
						</configuration>
					</plugin>
					<plugin>
						<groupId>org.apache.maven.plugins</groupId>
						<artifactId>maven-jar-plugin</artifactId>
						<version>3.1.1</version>
						<configuration>
							<archive>
								<manifestFile>${project.build.outputDirectory}/META-INF/MANIFEST.MF</manifestFile>
								<manifestEntries>
									<Automatic-Module-Name>com.microsoft.sqlserver.jdbc</Automatic-Module-Name>
								</manifestEntries>
							</archive>
						</configuration>
					</plugin>
					<plugin>
                		<groupId>org.apache.maven.plugins</groupId>
                		<artifactId>maven-assembly-plugin</artifactId>
                		<version>3.1.1</version>

                		<configuration>
                		    <descriptorRefs>
                		        <descriptorRef>jar-with-dependencies</descriptorRef>
                		    </descriptorRefs>
                		</configuration>

                		<executions>
                		    <execution>
                		        <id>make-assembly</id>
                		        <phase>package</phase>
                		        <goals>
                		            <goal>single</goal>
                		        </goals>
                		    </execution>
                		</executions>
            		</plugin>
				</plugins>
			</build>
		</profile>
Clone this wiki locally