examples: Document how to preserve META-INF/services in uber jars

ejona86 · ejona86 · commit 97695d523eef · 2025-11-23T21:12:07.000-08:00
diff --git a/examples/build.gradle b/examples/build.gradle
@@ -51,6 +51,15 @@ protobuf {
     }
 }
 
+// gRPC uses java.util.ServiceLoader, which reads class names from
+// META-INF/services in jars. If you package your application as a "fat" jar
+// that includes dependencies, you need to make sure the packaging tool
+// concatenates duplicate files in META-INF/services.
+//
+// For the Shadow Gradle Plugin, use call mergeServiceFiles() within the
+// shadowJar task.
+// https://gradleup.com/shadow/configuration/merging/#merging-service-descriptor-files
+
 startScripts.enabled = false
 
 // Creates start scripts for a class name and adds it to the distribution. The
diff --git a/examples/maven-assembly-jar-with-dependencies.xml b/examples/maven-assembly-jar-with-dependencies.xml
@@ -0,0 +1,27 @@
+<assembly xmlns="http://maven.apache.org/ASSEMBLY/2.2.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/2.2.0 https://maven.apache.org/xsd/assembly-2.2.0.xsd">
+<!--
+This is jar-with-dependencies with the metaInf-services handler added.
+https://maven.apache.org/plugins/maven-assembly-plugin/descriptor-refs.html#jar-with-dependencies
+https://maven.apache.org/plugins/maven-assembly-plugin/examples/single/using-container-descriptor-handlers.html
+-->
+  <id>jar-with-dependencies</id>
+  <formats>
+    <format>jar</format>
+  </formats>
+  <includeBaseDirectory>false</includeBaseDirectory>
+  <dependencySets>
+    <dependencySet>
+      <outputDirectory>/</outputDirectory>
+      <useProjectArtifact>true</useProjectArtifact>
+      <unpack>true</unpack>
+      <scope>runtime</scope>
+    </dependencySet>
+  </dependencySets>
+  <containerDescriptorHandlers>
+    <containerDescriptorHandler>
+      <handlerName>metaInf-services</handlerName>
+    </containerDescriptorHandler>
+  </containerDescriptorHandlers>
+</assembly>
diff --git a/examples/pom.xml b/examples/pom.xml
@@ -124,6 +124,35 @@
           </execution>
         </executions>
       </plugin>
+
+      <!-- gRPC uses java.util.ServiceLoader, which reads class names from
+        META-INF/services in jars. If you package your application as a "fat"
+        jar that includes dependencies, you need to make sure the packaging tool
+        concatenates duplicate files in META-INF/services. -->
+
+      <!-- If using maven-shade-plugin, use ServicesResourceTransformer, as
+        documented by maven-shade-plugin.
+        https://maven.apache.org/plugins/maven-shade-plugin/examples/resource-transformers.html#ServicesResourceTransformer -->
+
+      <!-- If using maven-assembly-plugin, you need to add the metaInf-services
+        handler to the descriptor, which requires making a copy of
+        jar-with-dependencies. -->
+      <plugin>
+        <artifactId>maven-assembly-plugin</artifactId>
+        <version>3.7.1</version>
+        <configuration>
+          <descriptors>${project.basedir}/maven-assembly-jar-with-dependencies.xml</descriptors>
+        </configuration>
+        <executions>
+          <execution>
+            <id>make-assembly</id>
+            <phase>package</phase>
+            <goals>
+              <goal>single</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
     </plugins>
   </build>
 </project>

Original file line number	Diff line number	Diff line change
`@@ -51,6 +51,15 @@ protobuf {`
`51`	`51`	`}`
`52`	`52`	`}`
`53`	`53`
	`54`	`+// gRPC uses java.util.ServiceLoader, which reads class names from`
	`55`	`+// META-INF/services in jars. If you package your application as a "fat" jar`
	`56`	`+// that includes dependencies, you need to make sure the packaging tool`
	`57`	`+// concatenates duplicate files in META-INF/services.`
	`58`	`+//`
	`59`	`+// For the Shadow Gradle Plugin, use call mergeServiceFiles() within the`
	`60`	`+// shadowJar task.`
	`61`	`+// https://gradleup.com/shadow/configuration/merging/#merging-service-descriptor-files`
	`62`	`+`
`54`	`63`	`startScripts.enabled = false`
`55`	`64`
`56`	`65`	`// Creates start scripts for a class name and adds it to the distribution. The`