ICU-23091 Add Java source formatting configs and automated checks

Author: echeran

.github/workflows/icu4j.yml

@@ -64,6 +64,33 @@ jobs:
           cd icu4j;
           mvn ${SHARED_MVN_ARGS} dependency:go-offline -P '!old_jdk_taglet'
 
+  # Using the Java style formatter google-java-style provided by the Spotless
+  # plugin configured in the root pom.xml using 4-space indents (AOSP style).
+  # Spotless is configured to run only on files in this branch (PR) that differ
+  # from origin/main
+  formatter:
+    name: Formatter + Style checker
+    needs: icu4j-mvn-init-cache
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout and setup
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # fetch all branches so that Spotless can resolve `origin/main`
+      - name: Restore read-only cache of local Maven repository
+        uses: actions/cache/restore@v4
+        id: cache
+        with:
+          path: ~/.m2/repository
+          key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
+          restore-keys: |
+            ${{ runner.os }}-maven-
+          lookup-only: true
+      - name: Check Java style
+        run: |
+          cd icu4j;
+          mvn spotless:check || (echo "Style checker failed. Formatting changes can be applied by 'mvn spotless:apply'" && exit 1)
+
   # ICU4J build and unit test using Maven
   # https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-java-with-maven
   icu4j-mvn-build-and-test:

docs/userguide/dev/codingguidelines.md

@@ -1449,6 +1449,20 @@ ICU Java classes and methods.
 
 ### Code style
 
+ICU uses a source formatter to ensure a consistent code style automatically,
+and it uses a single common formatter to avoid spurious diff noise in code reviews.
+This is now enforced via a
+[formatter](https://github.com/google/google-java-format)
+that is configured in the Maven build
+via a [Maven plugin](https://github.com/diffplug/spotless/tree/main/plugin-maven)
+and checked by continuous integration on pull requests.
+
+When creating pull requests, you can check the formatting locally using the command `mvn spotless:check`. You can apply the formatter's changes using the command `mvn spotless:apply`. Continuous integration errors for formatting can be fixed by committing the changes resulting from applying the formatter locally and pushing the new commit.
+
+The following are further guidelines for code style,
+but they will be superceded by the automated formatter in CI that is mentioned above
+if the guidelines differ in style.
+
 The standard order for modifier keywords on APIs is:
 
 * `public static final synchronized strictfp`

icu4j/pom.xml

@@ -116,6 +116,9 @@
     <mf.Manifest-Version>1.0</mf.Manifest-Version>
     <mf.Bundle-ManifestVersion>2</mf.Bundle-ManifestVersion>
     <mf.Bundle-Copyright>© 2016 and later: Unicode, Inc. and others. License &amp; terms of use: http://www.unicode.org/copyright.html</mf.Bundle-Copyright>
+
+    <formatter.plugin.spotless.version>2.43.0</formatter.plugin.spotless.version>
+    <formatter.google-java-style.version>1.22.0</formatter.google-java-style.version>
   </properties>
 
   <licenses>
@@ -466,6 +469,33 @@
           <artifactId>exec-maven-plugin</artifactId>
           <version>3.4.1</version>
         </plugin>
+        <!-- 
+          Spotless info:
+            - How to preview what `mvn spotless:apply` will do: https://github.com/diffplug/spotless/tree/main/plugin-maven#how-do-i-preview-what-mvn-spotlessapply-will-do
+            - Apply Spotless to specific files: https://github.com/diffplug/spotless/tree/main/plugin-maven#can-i-apply-spotless-to-specific-files
+        -->
+        <plugin>
+          <groupId>com.diffplug.spotless</groupId>
+          <artifactId>spotless-maven-plugin</artifactId>
+          <version>${formatter.plugin.spotless.version}</version>
+          <configuration>
+            <!-- optional: limit format enforcement to just the files changed by this feature branch -->
+            <!-- You can explicitly disable ratchet functionality by providing the value 'NONE': -->
+            <ratchetFrom>NONE</ratchetFrom>
+            <!-- define a language-specific format -->
+            <java>
+              <toggleOffOn />
+              <!-- no need to specify files, inferred automatically, but you can if you want -->
+              <!-- apply a specific flavor of google-java-format and reflow long strings -->
+              <googleJavaFormat>
+                <!-- version of google-java-style -->
+                <version>${google-java-style.version}</version>
+                <style>AOSP</style>
+                <reflowLongStrings>false</reflowLongStrings>
+              </googleJavaFormat>
+            </java>
+          </configuration>
+        </plugin>
       </plugins>
     </pluginManagement>