From 9be9ed3231f6cf79190128af6eee6dfc2e6b573c Mon Sep 17 00:00:00 2001
From: Mihai Nita <nmihai_2000@yahoo.com>
Date: Fri, 1 Sep 2023 18:20:00 -0700
Subject: [PATCH] ICU-22324 Mavenization, resolve some of the release tasks

---
 .../main/java/com/ibm/icu/util/Calendar.java  |  3 +-
 .../com/ibm/icu/util/ChineseCalendar.java     |  4 +
 .../java/com/ibm/icu/util/HebrewCalendar.java |  2 +
 icu4j/main/localespi/pom.xml                  |  3 -
 icu4j/pom.xml                                 | 62 ++++++++++++-
 icu4j/releases_tools/api_reports.sh           | 90 +++++++++++++++++++
 icu4j/releases_tools/cheatsheet.txt           | 20 +++++
 icu4j/stylesheet8.css                         |  1 +
 8 files changed, 178 insertions(+), 7 deletions(-)
 create mode 100755 icu4j/releases_tools/api_reports.sh
 create mode 100644 icu4j/releases_tools/cheatsheet.txt

diff --git a/icu4j/main/core/src/main/java/com/ibm/icu/util/Calendar.java b/icu4j/main/core/src/main/java/com/ibm/icu/util/Calendar.java
index 42a6c17ddfe..e3c69174281 100644
--- a/icu4j/main/core/src/main/java/com/ibm/icu/util/Calendar.java
+++ b/icu4j/main/core/src/main/java/com/ibm/icu/util/Calendar.java
@@ -2180,7 +2180,7 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
         return (stamp[field] > UNSET) ? fields[field] : defaultValue;
     }
 
-    /*
+    /**
      * @internal
      * @deprecated This API is ICU internal only.
      * Use this function instead of internalGet(MONTH). The implementation
@@ -2189,6 +2189,7 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
      * to MONTH correctly if ORDINAL_MONTH has higher priority.
      * @return the value for the given time field.
      */
+    @Deprecated
     protected int internalGetMonth()
     {
         if (resolveFields(MONTH_PRECEDENCE) == MONTH) {
diff --git a/icu4j/main/core/src/main/java/com/ibm/icu/util/ChineseCalendar.java b/icu4j/main/core/src/main/java/com/ibm/icu/util/ChineseCalendar.java
index 069b6271e56..c21f02833e4 100644
--- a/icu4j/main/core/src/main/java/com/ibm/icu/util/ChineseCalendar.java
+++ b/icu4j/main/core/src/main/java/com/ibm/icu/util/ChineseCalendar.java
@@ -1140,7 +1140,9 @@ public class ChineseCalendar extends Calendar {
     /**
      * {@inheritDoc}
      * @internal
+     * @deprecated This API is ICU internal only.
      */
+    @Deprecated
     protected int internalGetMonth()
     {
         if (resolveFields(MONTH_PRECEDENCE) == MONTH) {
@@ -1161,7 +1163,9 @@ public class ChineseCalendar extends Calendar {
     /**
      * {@inheritDoc}
      * @internal
+     * @deprecated This API is ICU internal only.
      */
+    @Deprecated
     protected int internalGetMonth(int defaultValue)
     {
         if (resolveFields(MONTH_PRECEDENCE) == MONTH) {
diff --git a/icu4j/main/core/src/main/java/com/ibm/icu/util/HebrewCalendar.java b/icu4j/main/core/src/main/java/com/ibm/icu/util/HebrewCalendar.java
index fb07b7b6927..d600a1cb554 100644
--- a/icu4j/main/core/src/main/java/com/ibm/icu/util/HebrewCalendar.java
+++ b/icu4j/main/core/src/main/java/com/ibm/icu/util/HebrewCalendar.java
@@ -966,7 +966,9 @@ public class HebrewCalendar extends Calendar {
     /**
      * {@inheritDoc}
      * @internal
+     * @deprecated This API is ICU internal only.
      */
+    @Deprecated
     protected int internalGetMonth()
     {
         if (resolveFields(MONTH_PRECEDENCE) == ORDINAL_MONTH) {
diff --git a/icu4j/main/localespi/pom.xml b/icu4j/main/localespi/pom.xml
index ae4b1364512..3d4dd2de7fa 100644
--- a/icu4j/main/localespi/pom.xml
+++ b/icu4j/main/localespi/pom.xml
@@ -93,7 +93,6 @@
         classpath is to be used instead.
       -->
       <plugin>
-        <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-dependency-plugin</artifactId>
         <executions>
           <execution>
@@ -125,9 +124,7 @@
       </plugin>
 
       <plugin>
-        <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-failsafe-plugin</artifactId>
-        <version>3.1.2</version>
         <executions>
           <execution>
             <goals>
diff --git a/icu4j/pom.xml b/icu4j/pom.xml
index cceab0065bd..6e3cfda99a1 100644
--- a/icu4j/pom.xml
+++ b/icu4j/pom.xml
@@ -46,6 +46,7 @@
     <icu4j.api.doc.copyright.footer>&lt;font size=-1&gt;Copyright © 2016 Unicode, Inc. and others.&lt;/font&gt;</icu4j.api.doc.copyright.footer>
     <!-- Needs to be overriden in sub-modules -->
     <icu4j.api.doc.root.dir>${project.basedir}</icu4j.api.doc.root.dir>
+    <icu4j.api.report.version>74</icu4j.api.report.version>
 
     <!-- Used for the .jar Manifest files -->
 
@@ -170,15 +171,17 @@
             <taglets>
               <taglet>
                 <tagletClass>com.ibm.icu.dev.tool.docs.ICUTaglet</tagletClass>
-                <!-- We can use `tagletArtifact` instead of `tagletpath`,
-                     but then we must `mvn install` the `tools_build` artifact. -->
-                <tagletpath>${icu4j.api.doc.root.dir}/tools/build/target/classes</tagletpath>
               </taglet>
               <taglet>
                 <tagletClass>ch.arrenbrecht.jcite.JCiteTaglet</tagletClass>
               </taglet>
             </taglets>
             <tagletArtifacts>
+              <tagletArtifact>
+                <groupId>com.ibm.icu</groupId>
+                <artifactId>tools_build</artifactId>
+                <version>${project.version}</version>
+              </tagletArtifact>
               <tagletArtifact>
                 <groupId>org.mcraig</groupId>
                 <artifactId>jcite</artifactId>
@@ -328,6 +331,59 @@
       </build>
     </profile>
 
+    <!-- This is used to gather API data used to generate API reports
+      (regular, draft, deprecated, status consistency, etc.)
+      To run it:
+        mvn install -DskipITs -DskipTests
+        mvn site -DskipITs -DskipTests -P gatherapi
+    -->
+    <profile>
+      <id>gatherapi</id>
+      <build>
+        <plugins>
+          <plugin>
+            <artifactId>maven-javadoc-plugin</artifactId>
+            <executions>
+              <execution>
+                <id>aggregate</id>
+                <phase>site</phase>
+                <goals>
+                  <goal>aggregate</goal>
+                </goals>
+              </execution>
+            </executions>
+            <configuration>
+              <!-- For incomplete doc tags javadoc fails with:
+                  ```
+                  Error while creating javadoc report:
+                  Exit code: 1
+                  Command line was: ...
+                  Refer to the generated Javadoc files in '...' dir.
+                  ```
+                But in most cases these are not related to what we do here, which is API reporting.
+                We ignore them so that we can progess with what we really care.
+              -->
+              <failOnError>false</failOnError>
+              <useStandardDocletOptions>false</useStandardDocletOptions>
+              <doclet>com.ibm.icu.dev.tool.docs.GatherAPIData</doclet>
+              <docletArtifact>
+                <groupId>com.ibm.icu</groupId>
+                <artifactId>tools_build</artifactId>
+                <version>${project.version}</version>
+              </docletArtifact>
+              <additionalOptions>
+                <additionalOption>-name 'ICU4J ${mf.Implementation-Version}'</additionalOption>
+                <additionalOption>-output ${project.build.directory}/icu4j${icu4j.api.report.version}.api3</additionalOption>
+                <additionalOption>-internal</additionalOption>
+                <additionalOption>-version</additionalOption>
+                <additionalOption>-gzip</additionalOption>
+              </additionalOptions>
+            </configuration>
+          </plugin>
+        </plugins>
+      </build>
+    </profile>
+
     <!-- The tools/build module depends on the old tools.jar (jdk 1.8)
       The com.sun.javadoc package was deprecated in Java 11, and has been removed for Java 17.
       JDK 11 does not include tools.jar anymore. The code must be updated, see migration guide at
diff --git a/icu4j/releases_tools/api_reports.sh b/icu4j/releases_tools/api_reports.sh
new file mode 100755
index 00000000000..d9c8fe5bf1b
--- /dev/null
+++ b/icu4j/releases_tools/api_reports.sh
@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# Copyright (C) 2023 and later: Unicode, Inc. and others.
+# License & terms of use: http://www.unicode.org/copyright.html
+
+export MAVEN_ARGS='--no-transfer-progress'
+
+export artifact_version='74.0.1-SNAPSHOT'
+export api_report_version='74'
+export api_report_prev_version='73'
+export out_dir=target
+
+function copyArtifacts() {
+  rm   -fr ${out_dir}/lib/
+  mkdir -p ${out_dir}/lib/
+
+  mvn dependency:copy -q -Dartifact=com.ibm.icu:tools_build:${artifact_version}   -DoutputDirectory=${out_dir}/lib/
+  mvn dependency:copy -q -Dartifact=com.ibm.icu:core:${artifact_version}          -DoutputDirectory=${out_dir}/lib/
+  mvn dependency:copy -q -Dartifact=com.ibm.icu:collate:${artifact_version}       -DoutputDirectory=${out_dir}/lib/
+  mvn dependency:copy -q -Dartifact=com.ibm.icu:icu4j-charset:${artifact_version} -DoutputDirectory=${out_dir}/lib/
+  mvn dependency:copy -q -Dartifact=com.ibm.icu:currdata:${artifact_version}      -DoutputDirectory=${out_dir}/lib/
+  mvn dependency:copy -q -Dartifact=com.ibm.icu:langdata:${artifact_version}      -DoutputDirectory=${out_dir}/lib/
+  mvn dependency:copy -q -Dartifact=com.ibm.icu:regiondata:${artifact_version}    -DoutputDirectory=${out_dir}/lib/
+  mvn dependency:copy -q -Dartifact=com.ibm.icu:translit:${artifact_version}      -DoutputDirectory=${out_dir}/lib/
+}
+
+function reportTitle() {
+  echo "=============================================="
+  echo $*
+  echo "=============================================="
+}
+
+# Build everything
+mvn install -DskipITs -DskipTests
+# Gather API info
+mvn site -q -DskipITs -DskipTests -P gatherapi
+
+copyArtifacts
+
+export toolcp=${out_dir}/lib/collate-74.0.1-SNAPSHOT.jar:${out_dir}/lib/core-74.0.1-SNAPSHOT.jar:${out_dir}/lib/currdata-74.0.1-SNAPSHOT.jar:${out_dir}/lib/icu4j-charset-74.0.1-SNAPSHOT.jar:${out_dir}/lib/langdata-74.0.1-SNAPSHOT.jar:${out_dir}/lib/regiondata-74.0.1-SNAPSHOT.jar:${out_dir}/lib/tools_build-74.0.1-SNAPSHOT.jar:${out_dir}/lib/translit-74.0.1-SNAPSHOT.jar
+
+# ====================================================================================
+
+reportTitle apireport :: Run API report generator tool
+
+java -cp $toolcp \
+    com.ibm.icu.dev.tool.docs.ReportAPI \
+    -old: tools/build/icu4j${api_report_prev_version}.api3.gz \
+    -new: ${out_dir}/icu4j${api_report_version}.api3.gz \
+    -html \
+    -out: ${out_dir}/icu4j_compare_${api_report_prev_version}_${api_report_version}.html
+
+# ====================================================================================
+
+reportTitle checkDeprecated :: Check consistency between javadoc @deprecated and @Deprecated annotation
+
+java -cp $toolcp \
+    com.ibm.icu.dev.tool.docs.DeprecatedAPIChecker \
+        ${out_dir}/icu4j${api_report_version}.api3.gz
+
+# ====================================================================================
+
+reportTitle checkAPIStatusConsistency :: Check consistency between API class status and methods overriding java.lang.Object
+
+# If you need classes excluded from this check, define following property in build-local.properties.
+# e.g. checkAPIStatusConsistency.skip.classes=com.ibm.icu.text.Normalizer;com.ibm.icu.util.ULocale
+
+java -cp $toolcp \
+    com.ibm.icu.dev.tool.docs.APIStatusConsistencyChecker \
+        ${out_dir}/icu4j${api_report_version}.api3.gz \
+        checkAPIStatusConsistency.skip.classes=
+
+# ====================================================================================
+
+reportTitle draftAPIs :: Run API collector tool and generate draft API report in html
+
+java -cp $toolcp \
+    com.ibm.icu.dev.tool.docs.CollectAPI \
+        -f Draft \
+        -o ${out_dir}/draftAPIs.html \
+        ${out_dir}/icu4j${api_report_version}.api3.gz
+
+# ====================================================================================
+
+reportTitle draftAPIsTSV :: Run API collector tool and generate draft API report in TSV
+
+java -cp $toolcp \
+    com.ibm.icu.dev.tool.docs.CollectAPI \
+        -f Draft \
+        -o ${out_dir}/draftAPIs.tsv \
+        -t ${out_dir}/icu4j${api_report_version}.api3.gz
diff --git a/icu4j/releases_tools/cheatsheet.txt b/icu4j/releases_tools/cheatsheet.txt
new file mode 100644
index 00000000000..60c7a48bee7
--- /dev/null
+++ b/icu4j/releases_tools/cheatsheet.txt
@@ -0,0 +1,20 @@
+# Copyright (C) 2023 and later: Unicode, Inc. and others.
+# License & terms of use: http://www.unicode.org/copyright.html
+
+====
+
+Build all artifacts, with sources and javadoc, ready to deploy
+
+mvn site -DskipITs -DskipTests -P with_sources,with_javadoc
+
+====
+
+Build the unified javadoc (public site), combining the javadocs from all public artifacts.
+
+mvn site -DskipITs -DskipTests -P with_full_javadoc
+
+====
+
+Run API reports
+
+api_reports.sh
diff --git a/icu4j/stylesheet8.css b/icu4j/stylesheet8.css
index 9f43c662f91..598b0a475b3 100644
--- a/icu4j/stylesheet8.css
+++ b/icu4j/stylesheet8.css
@@ -584,6 +584,7 @@ pre.java /* container for citations */
     border-width: 1px;
     border-color: DarkGray;
     margin: 1.5em 1.5em 1.5em 1.5em;
+    padding: 1em;
     background-color: cornsilk;
     }