#979: overhaul of the updates logger

.gitignore

@@ -7,3 +7,4 @@ target
 .vscode
 .checkstyle
 /.factorypath
+/hs_err_pid*.log

pom.xml

@@ -148,6 +148,17 @@
     <invoker.parallelThreads>0.75C</invoker.parallelThreads>
     <!-- mono-module doesn't require site:stage for scm-publish -->
     <project.build.outputTimestamp>2025-11-24T17:49:22Z</project.build.outputTimestamp>
+
+    <!-- dependencies for version changes model -->
+    <jaxbApi.version>2.3.1</jaxbApi.version>
+    <jaxbRuntime.version>2.3.9</jaxbRuntime.version>
+    <jacksonDatabind.version>2.20.0</jacksonDatabind.version>
+    <jacksonDataformatXml.version>2.20.0</jacksonDataformatXml.version>
+    <jaxb2MavenPlugin.version>2.5.0</jaxb2MavenPlugin.version>
+    <jaxb2FluentApi.version>3.0</jaxb2FluentApi.version>
+    <jaxb2BasicsAnnotate.version>1.1.0</jaxb2BasicsAnnotate.version>
+    <jacksonDataformatCsv.version>2.17.2</jacksonDataformatCsv.version>
+    <jacksonDatatypeJsr310.version>2.19.0</jacksonDatatypeJsr310.version>
   </properties>
 
   <dependencyManagement>
@@ -388,6 +399,37 @@
         <artifactId>wagon-provider-api</artifactId>
         <version>3.5.3</version>
       </dependency>
+      <dependency>
+        <groupId>org.glassfish.jaxb</groupId>
+        <artifactId>jaxb-runtime</artifactId>
+        <version>${jaxbRuntime.version}</version>
+        <scope>runtime</scope>
+      </dependency>
+      <dependency>
+        <groupId>com.fasterxml.jackson.core</groupId>
+        <artifactId>jackson-databind</artifactId>
+        <version>${jacksonDatabind.version}</version>
+      </dependency>
+      <dependency>
+        <groupId>com.fasterxml.jackson.dataformat</groupId>
+        <artifactId>jackson-dataformat-xml</artifactId>
+        <version>${jacksonDataformatXml.version}</version>
+      </dependency>
+      <dependency>
+        <groupId>javax.xml.bind</groupId>
+        <artifactId>jaxb-api</artifactId>
+        <version>${jaxbApi.version}</version>
+      </dependency>
+      <dependency>
+        <groupId>com.fasterxml.jackson.dataformat</groupId>
+        <artifactId>jackson-dataformat-csv</artifactId>
+        <version>${jacksonDataformatCsv.version}</version>
+      </dependency>
+      <dependency>
+        <groupId>com.fasterxml.jackson.datatype</groupId>
+        <artifactId>jackson-datatype-jsr310</artifactId>
+        <version>${jacksonDatatypeJsr310.version}</version>
+      </dependency>
     </dependencies>
   </dependencyManagement>
 

versions-api/pom.xml

@@ -12,6 +12,19 @@
   <name>Versions API</name>
   <description>Extension API for Versions Plugin</description>
 
+  <dependencies>
+    <dependency>
+      <groupId>org.codehaus.mojo.versions</groupId>
+      <artifactId>versions-model</artifactId>
+      <version>${project.version}</version>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.maven</groupId>
+      <artifactId>maven-core</artifactId>
+      <scope>provided</scope>
+    </dependency>
+  </dependencies>
+
   <reporting>
     <plugins>
       <plugin>

versions-api/src/main/java/org/codehaus/mojo/versions/api/change/DependencyVersionChange.java

@@ -22,7 +22,9 @@
  *
  * @author Slawomir Jaranowski
  * @since 2.14.0
+ * @deprecated use classes from {@code versions-model}
  */
+@Deprecated
 public interface DependencyVersionChange extends VersionChange {
     /**
      * Returns the groupId of the dependency

versions-api/src/main/java/org/codehaus/mojo/versions/api/change/PropertyVersionChange.java

@@ -22,7 +22,9 @@
  *
  * @author Andrzej Jarmoniuk
  * @since 2.15.0
+ * @deprecated use classes from {@code versions-model}
  */
+@Deprecated
 public interface PropertyVersionChange extends VersionChange {
 
     /**

versions-api/src/main/java/org/codehaus/mojo/versions/api/recording/ChangeRecord.java

@@ -25,7 +25,9 @@
  * @author Slawomir Jaranowski
  * @since 2.14.0
  * @param <T> concrete {@link VersionChange} sub-interface
+ * @deprecated use classes from {@code versions-model}
  */
+@Deprecated
 public interface ChangeRecord<T extends VersionChange> {
     /**
      * Returns the details about changed item

versions-api/src/main/java/org/codehaus/mojo/versions/api/recording/ChangeRecorder.java

@@ -25,7 +25,9 @@
  *
  * @author Slawomir Jaranowski
  * @since 2.14.0
+ * @deprecated use {@link VersionChangeRecorder} and {@code versions-model}
  */
+@Deprecated
 public interface ChangeRecorder {
     /**
      * Record that a dependency was updated.

versions-api/src/main/java/org/codehaus/mojo/versions/api/recording/DependencyChangeRecord.java

@@ -24,7 +24,9 @@
  *
  * @author Slawomir Jaranowski
  * @since 2.14.0
+ * @deprecated use classes from {@code versions-model}
  */
+@Deprecated
 public interface DependencyChangeRecord extends ChangeRecord<DependencyVersionChange> {
     /**
      * Describes where version item is updated.

versions-api/src/main/java/org/codehaus/mojo/versions/api/recording/PropertyChangeRecord.java

@@ -24,5 +24,7 @@
  *
  * @author Slawomir Jaranowski
  * @since 2.14.0
+ * @deprecated use classes from {@code versions-model}
  */
+@Deprecated
 public interface PropertyChangeRecord extends ChangeRecord<PropertyVersionChange> {}

versions-api/src/main/java/org/codehaus/mojo/versions/api/recording/VersionChangeRecorder.java

@@ -0,0 +1,59 @@
+package org.codehaus.mojo.versions.api.recording;
+
+/*
+ * Copyright MojoHaus and Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+import java.io.IOException;
+import java.nio.file.Path;
+
+import org.codehaus.mojo.versions.model.VersionChange;
+
+/**
+ * Interface for implement a recorder of version changes.
+ *
+ * @since 2.20.0
+ */
+public interface VersionChangeRecorder {
+    /**
+     * Record that a version change
+     *
+     * @param versionChange a {@link VersionChange} object describing the change
+     * @since 2.20.0
+     */
+    void recordChange(VersionChange versionChange);
+
+    /**
+     * Write the current set of changes to the given output path.
+     * <p>
+     * Implementation is responsible for creating all missing directories.
+     * <p>
+     * Output should not be created for empty record sets.
+     *
+     * @param outputPath The output path, can be null, provided by <code>changeRecorderOutputFile</code>
+     *                   plugin parameters
+     * @throws IOException On write and/or I/O errors
+     * @since 2.20.0
+     */
+    void writeReport(Path outputPath) throws IOException;
+
+    /**
+     * Provides the default output file name
+     *
+     * @return default file name
+     */
+    String getDefaultFileName();
+}

versions-api/src/main/java/org/codehaus/mojo/versions/api/recording/VersionChangeRecorderFactory.java

@@ -0,0 +1,38 @@
+package org.codehaus.mojo.versions.api.recording;
+
+import java.util.Map;
+import java.util.Properties;
+
+import org.apache.maven.execution.MavenSession;
+import org.apache.maven.plugin.MojoExecution;
+import org.apache.maven.plugin.logging.Log;
+
+/**
+ * A factory for version change recorders.
+ */
+public interface VersionChangeRecorderFactory {
+
+    /**
+     * Creates a new {@link VersionChangeRecorder} instance. Convenience method without any changeRendererOptions.
+     *
+     * @param mavenSession  {@link MavenSession} instance
+     * @param mojoExecution {@link MojoExecution} instance
+     * @param log           {@link Log} instance
+     * @return a new {@link VersionChangeRecorder} instance
+     */
+    default VersionChangeRecorder create(MavenSession mavenSession, MojoExecution mojoExecution, Log log) {
+        return create(mavenSession, mojoExecution, log, null);
+    }
+
+    /**
+     * Creates a new {@link VersionChangeRecorder} instance.
+     *
+     * @param mavenSession          {@link MavenSession} instance
+     * @param mojoExecution         {@link MojoExecution} instance
+     * @param log                   {@link Log} instance
+     * @param changeRendererOptions {@link Properties} custom properties to pass to the renderer
+     * @return a new {@link VersionChangeRecorder} instance
+     */
+    VersionChangeRecorder create(
+            MavenSession mavenSession, MojoExecution mojoExecution, Log log, Map<String, String> changeRendererOptions);
+}

versions-api/src/site/markdown/change-recorder.md.vm

@@ -1,49 +1,75 @@
-title: Writing a own ChangeRecorder
-author: Slawomir Jaranowski
-date: 2022-11-20
+title: Providing a custom VersionsChangeRecorder
+date: 2025-10-04
 
-Writing an own ChangeRecorder
-============================
+Providing a custom VersionsChangeRecorder
+=========================================
 
-In order to create an own ChangeRecorder you must implement [ChangeRecorder](apidocs/org/codehaus/mojo/versions/api/recording/ChangeRecorder.html) interface.
+A change recorder is a component responsible for outputting version changes. Currently, it is only being used for
+recording changes for plugins that change the project. Out of the box, the following recorders are provided:
 
-Write code
-----------
+| Name | Description                                                                                                                                                                                                                                                          |
+|------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| none | An "empty" recorder that will not output any changes                                                                                                                                                                                                                 |
+| xml  | A recorder writing to an XML file conforming to the legacy http://www.mojohaus.org/versions-maven-plugin/schema/updates/2.0 namespace, or to the http://www.mojohaus.org/versions-maven-plugin/schema/updates/3.0 namespace if `legacy=false` is provided as options |     
+| json | A recorder writing to a Json file                                                                                                                                                                                                                                    |
+| csv  | A recorder writing to a CSV file                                                                                                                                                                                                                                     | 
+
+In order to create an own VersionChangeRecorder you must implement [VersionChangeRecorder](apidocs/org/codehaus/mojo/versions/api/recording/VersionsChangeRecorder.html) interface as well as a factory
+implementing [VersionChangeRecorderFactory](apidocs/org/codehaus/mojo/versions/api/recording/VersionsChangeRecorderFactory.html).
+
+Create the recorder
+------------------
+
+The below class will create a factory instantiating an anonymous class implementing the interface.
 
 ```java
-import java.io.IOException;
 import javax.inject.Named;
 
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
 import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
 
-import org.codehaus.mojo.versions.api.recording.DependencyChangeRecord;
-import org.codehaus.mojo.versions.api.recording.PropertyChangeRecord;
-import org.codehaus.mojo.versions.api.recording.ChangeRecorder;
+import org.apache.maven.execution.MavenSession;
+import org.apache.maven.plugin.MojoExecution;
+import org.codehaus.mojo.versions.api.recording.VersionChangeRecorder;
+import org.codehaus.mojo.versions.api.recording.VersionChangeRecorderFactory;
+import org.codehaus.mojo.versions.model.VersionChange;
 
 @Named("my-recorder")
-public class MyChangeRecorder implements ChangeRecorder {
-
+public class ExampleChangeRecorderFactory implements VersionChangeRecorderFactory {
     @Override
-    public final void recordChange(DependencyChangeRecord changeRecord) {
-        // your code here
-    }
-
-    @Override
-    public final void recordChange(PropertyChangeRecord changeRecord) {
-        // your code here
-    }
-
-    @Override
-    public final void writeReport(Path outputPath) throws IOException {
-        // your code here
+    public VersionChangeRecorder create(
+            MavenSession mavenSession, MojoExecution mojoExecution, Map<String, String> ignored) {
+        return new VersionChangeRecorder() {
+            final List<String> versionChanges = new ArrayList<>();
+
+            @Override
+            public void recordChange(VersionChange versionChange) {
+                versionChanges.add(versionChange.toString());
+            }
+
+            @Override
+            public void writeReport(Path outputPath) throws IOException {
+                Files.write(outputPath, versionChanges, StandardCharsets.UTF_8);
+            }
+
+            @Override
+            public String getDefaultFileName() {
+                return "versions-changes.log";
+            }
+        };
     }
 }
 ```
 
-`Changerecoder` is stateful component, so you must not add `Singleton` annotation to it.
+As `VersionChangeRecorder` is stateful, so you must not add the `Singleton` annotation to it.
 
-Using extension
----------------
+Using the custom recorder
+-------------------------
 
 Plugin configuration:
 
@@ -56,7 +82,7 @@ Plugin configuration:
 
   <groupId>your.group</groupId>
   <artifactId>your-project</artifactId>
-  
+
   <build>
     <pluginManagement>
       <plugins>
@@ -67,7 +93,6 @@ Plugin configuration:
           <configuration>
             <!-- your component name -->
             <changeRecorderFormat>my-recorder</changeRecorderFormat>
-            <changeRecorderOutputFile>\${project.build.directory}/my-versions-changes.txt</changeRecorderOutputFile>
           </configuration>
           <dependencies>
             <dependency>

versions-common/pom.xml

@@ -87,6 +87,29 @@
       <artifactId>maven-resolver-util</artifactId>
       <scope>provided</scope>
     </dependency>
+
+    <!-- Necessary for serializing and deserializing the version changes model -->
+    <dependency>
+      <groupId>org.glassfish.jaxb</groupId>
+      <artifactId>jaxb-runtime</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>com.fasterxml.jackson.core</groupId>
+      <artifactId>jackson-databind</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>com.fasterxml.jackson.dataformat</groupId>
+      <artifactId>jackson-dataformat-xml</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>com.fasterxml.jackson.dataformat</groupId>
+      <artifactId>jackson-dataformat-csv</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>com.fasterxml.jackson.datatype</groupId>
+      <artifactId>jackson-datatype-jsr310</artifactId>
+    </dependency>
+
     <dependency>
       <groupId>org.junit.jupiter</groupId>
       <artifactId>junit-jupiter-api</artifactId>