Spring Extensions 1.1.0 documentation and news item (#145)

content/documentation/reference-guide.md

@@ -16,10 +16,10 @@ parent = "Documentation"
 * API documentation: [JavaDoc](/documentation/stable/api/)
 * [Migration notes](https://github.com/mapstruct/mapstruct/releases/tag/1.5.5.Final)
 
-**Spring Extensions** (August 8th 2023; latest milestone release)
+**Spring Extensions** (September 25th 2023; latest milestone release)
 
 * Reference guide: [HTML](/documentation/spring-extensions/reference/html/)
-* API documentation: [Annotations JavaDoc](/documentation/spring-extensions/api/annotations/) | [Extensions JavaDoc](/documentation/spring-extensions/api/extensions/)
+* API documentation: [Annotations JavaDoc](/documentation/spring-extensions/api/annotations/) | [Extensions JavaDoc](/documentation/spring-extensions/api/extensions/) | [Test Extensions JavaDoc](/documentation/spring-extensions/api/test-extensions/)
 
 **1.4.2.Final** (January 31st 2021)
 

content/news/2023-09-25-mapstruct-spring-extensions-1-1-0-released.md

@@ -0,0 +1,61 @@
+---
+title: "MapStruct Spring Extensions 1.1.0 released"
+author: Raimund Klein
+date: "2023-09-25"
+tags: [ release, news ]
+---
+
+It is my pleasure to announce the next official release of MapStruct Spring Extensions.
+What started out as a [StackOverflow question](https://stackoverflow.com/q/58081224/3361467) turned into its
+own [(sub-)project](https://github.com/mapstruct/mapstruct-spring-extensions) within the MapStruct organization.
+
+Changes in this release:
+
+- New module `test-extensions` which contains a `@ConverterScan` annotation that greatly simplifies the writing of integration tests. Thanks to [Joose Haverinen](https://github.com/joosehav) for the suggestion.
+- New annotation `@AdapterMethodName` which allows a developer to override the default name for generated adapter methods. Thanks to [pw-lehre](https://github.com/pw-lehre) for the inspiration.
+- New annotation `@DelegatingConverter` that will generate a converter calling the one whose method is annotated with this. The intended use is in conjunction with MapStruct Core's `@InheritInverseConfiguration`. Thanks again to [pw-lehre](https://github.com/pw-lehre) for the idea.
+
+Including the annotations and extensions defined in this project will generate a class acting as bridge between
+MapStruct's conventions and Spring'
+s [ConversionService API](https://docs.spring.io/spring-framework/docs/current/reference/html/core.html#core-convert-ConversionService-API)
+that in turn can be added to any Mapper's `uses` attribute. See
+the [examples](https://github.com/mapstruct/mapstruct-spring-extensions/tree/master/examples) for details.
+
+<!--more-->
+
+### Thanks
+
+Thanks to [Sjaak Derksen](https://github.com/sjaakd) for suggesting this solution
+and [Filip Hrisafov](https://github.com/filiphr) for opening the community project.
+Also thanks
+to [Cosimo Damiano Prete](https://github.com/cdprete), [Daniel Shiplett](https://github.com/danielshiplett), [Alexey](https://github.com/PRIESt512), [Olivier Boudet](https://github.com/olivierboudet), [John Kelly](https://github.com/postalservice14), [Myat Min](https://github.com/myatmin), [Hypercube Software](https://github.com/hypercube-software), [coding-guo](https://github.com/coding-guo)
+and [freund17](https://github.com/freund17) for their suggestions and fixes in previous releases.
+If you feel like there's something missing in MapStruct which could make the Spring experience any smoother, please get
+involved!
+
+Also, if your favourite library or framework could use some tweaking with regard to MapStruct, contact us.
+
+Happy coding with MapStruct Spring Extensions!
+
+### Download
+
+You can fetch the release from Maven Central using the following GAV coordinates:
+
+* Annotation
+  JAR: [org.mapstruct.extensions.spring:mapstruct-spring-annotations:1.1.0](http://search.maven.org/#artifactdetails|org.mapstruct.extensions.spring|mapstruct-spring-annotations|1.1.0|jar)
+* Annotation processor
+  JAR: [org.mapstruct.extensions.spring:mapstruct-spring-extensions:1.1.0](http://search.maven.org/#artifactdetails|org.mapstruct.extensions.spring|mapstruct-spring-extensions|1.1.0|jar)
+* Test Extensions with Converter Scan
+  JAR: [org.mapstruct.extensions.spring:mapstruct-spring-extensions:1.1.0](http://search.maven.org/#artifactdetails|org.mapstruct.extensions.spring|mapstruct-spring-test-extensions|1.1.0|jar)
+
+Alternatively, you can get ZIP and TAR.GZ distribution bundles - containing all the JARs, documentation
+etc. - [from GitHub](https://github.com/mapstruct/mapstruct-spring-extensions/releases/tag/v1.1.0).
+
+If you run into any trouble or would like to report a bug, feature request or similar, use the following channels to get
+in touch:
+
+* Get help in our [Gitter room](https://gitter.im/mapstruct/mapstruct-users) or at
+  the [mapstruct-users](https://groups.google.com/forum/?fromgroups#!forum/mapstruct-users) group
+* Report bugs and feature requests via
+  the [issue tracker](https://github.com/mapstruct/mapstruct-spring-extensions/issues)
+* Follow [@GetMapStruct](https://twitter.com/GetMapStruct) on Twitter

static/documentation/spring-extensions/api/annotations/allclasses-index.html

@@ -3,7 +3,7 @@
 <html lang="de">
 <head>
 <!-- Generated by javadoc -->
-<title>All Classes (annotations 1.0.2 API)</title>
+<title>All Classes (annotations 1.1.0 API)</title>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
 <link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">
 <link rel="stylesheet" type="text/css" href="jquery/jquery-ui.css" title="Style">
@@ -20,7 +20,7 @@
 <script type="text/javascript"><!--
     try {
         if (location.href.indexOf('is-external=true') == -1) {
-            parent.document.title="All Classes (annotations 1.0.2 API)";
+            parent.document.title="All Classes (annotations 1.1.0 API)";
         }
     }
     catch(err) {
@@ -103,13 +103,26 @@ <h1 title="All&amp;nbsp;Classes" class="title">All&nbsp;Classes</h1>
 <th class="colLast" scope="col">Description</th>
 </tr>
 <tr id="i0" class="altColor">
+<td class="colFirst"><a href="org/mapstruct/extensions/spring/AdapterMethodName.html" title="annotation in org.mapstruct.extensions.spring">AdapterMethodName</a></td>
+<th class="colLast" scope="row">
+<div class="block">Overrides the default method name generated in the Adapter class.</div>
+</th>
+</tr>
+<tr id="i1" class="rowColor">
+<td class="colFirst"><a href="org/mapstruct/extensions/spring/DelegatingConverter.html" title="annotation in org.mapstruct.extensions.spring">DelegatingConverter</a></td>
+<th class="colLast" scope="row">
+<div class="block">Indicates that the system should generate a delegating <a href="https://docs.spring.io/spring/docs/5.0.0.RELEASE/javadoc-api/org/springframework/core/convert/converter/Converter.html?is-external=true" title="class or interface in org.springframework.core.convert.converter" class="externalLink"><code>Converter</code></a> that will call the annotated method in its
+ own <a href="https://docs.spring.io/spring/docs/5.0.0.RELEASE/javadoc-api/org/springframework/core/convert/converter/Converter.html?is-external=true#convert(S)" title="class or interface in org.springframework.core.convert.converter" class="externalLink"><code>Converter.convert(Object)</code></a>.</div>
+</th>
+</tr>
+<tr id="i2" class="altColor">
 <td class="colFirst"><a href="org/mapstruct/extensions/spring/ExternalConversion.html" title="annotation in org.mapstruct.extensions.spring">ExternalConversion</a></td>
 <th class="colLast" scope="row">
 <div class="block">Allows the specification of a conversion that is available via the <a href="https://docs.spring.io/spring/docs/5.0.0.RELEASE/javadoc-api/org/springframework/core/convert/ConversionService.html?is-external=true" title="class or interface in org.springframework.core.convert" class="externalLink"><code>ConversionService</code></a>, but is <em>not</em>
  declared as a MapStruct mapper within the scope of the <a href="org/mapstruct/extensions/spring/SpringMapperConfig.html" title="annotation in org.mapstruct.extensions.spring"><code>SpringMapperConfig</code></a>.</div>
 </th>
 </tr>
-<tr id="i1" class="rowColor">
+<tr id="i3" class="rowColor">
 <td class="colFirst"><a href="org/mapstruct/extensions/spring/SpringMapperConfig.html" title="annotation in org.mapstruct.extensions.spring">SpringMapperConfig</a></td>
 <th class="colLast" scope="row">
 <div class="block">Marks a class or interface as configuration source for the Spring extension.</div>

static/documentation/spring-extensions/api/annotations/allclasses.html

@@ -3,7 +3,7 @@
 <html lang="de">
 <head>
 <!-- Generated by javadoc -->
-<title>All Classes (annotations 1.0.2 API)</title>
+<title>All Classes (annotations 1.1.0 API)</title>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
 <link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">
 <link rel="stylesheet" type="text/css" href="jquery/jquery-ui.css" title="Style">
@@ -20,6 +20,8 @@
 <h1 class="bar">All&nbsp;Classes</h1>
 <main role="main" class="indexContainer">
 <ul>
+<li><a href="org/mapstruct/extensions/spring/AdapterMethodName.html" title="annotation in org.mapstruct.extensions.spring">AdapterMethodName</a></li>
+<li><a href="org/mapstruct/extensions/spring/DelegatingConverter.html" title="annotation in org.mapstruct.extensions.spring">DelegatingConverter</a></li>
 <li><a href="org/mapstruct/extensions/spring/ExternalConversion.html" title="annotation in org.mapstruct.extensions.spring">ExternalConversion</a></li>
 <li><a href="org/mapstruct/extensions/spring/SpringMapperConfig.html" title="annotation in org.mapstruct.extensions.spring">SpringMapperConfig</a></li>
 </ul>

static/documentation/spring-extensions/api/annotations/allpackages-index.html

@@ -3,7 +3,7 @@
 <html lang="de">
 <head>
 <!-- Generated by javadoc -->
-<title>All Packages (annotations 1.0.2 API)</title>
+<title>All Packages (annotations 1.1.0 API)</title>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
 <link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">
 <link rel="stylesheet" type="text/css" href="jquery/jquery-ui.css" title="Style">
@@ -20,7 +20,7 @@
 <script type="text/javascript"><!--
     try {
         if (location.href.indexOf('is-external=true') == -1) {
-            parent.document.title="All Packages (annotations 1.0.2 API)";
+            parent.document.title="All Packages (annotations 1.1.0 API)";
         }
     }
     catch(err) {

static/documentation/spring-extensions/api/annotations/constant-values.html

@@ -3,7 +3,7 @@
 <html lang="de">
 <head>
 <!-- Generated by javadoc -->
-<title>Constant Field Values (annotations 1.0.2 API)</title>
+<title>Constant Field Values (annotations 1.1.0 API)</title>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
 <link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">
 <link rel="stylesheet" type="text/css" href="jquery/jquery-ui.css" title="Style">
@@ -20,7 +20,7 @@
 <script type="text/javascript"><!--
     try {
         if (location.href.indexOf('is-external=true') == -1) {
-            parent.document.title="Constant Field Values (annotations 1.0.2 API)";
+            parent.document.title="Constant Field Values (annotations 1.1.0 API)";
         }
     }
     catch(err) {

static/documentation/spring-extensions/api/annotations/deprecated-list.html

@@ -3,7 +3,7 @@
 <html lang="de">
 <head>
 <!-- Generated by javadoc -->
-<title>Deprecated List (annotations 1.0.2 API)</title>
+<title>Deprecated List (annotations 1.1.0 API)</title>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
 <link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">
 <link rel="stylesheet" type="text/css" href="jquery/jquery-ui.css" title="Style">
@@ -20,7 +20,7 @@
 <script type="text/javascript"><!--
     try {
         if (location.href.indexOf('is-external=true') == -1) {
-            parent.document.title="Deprecated List (annotations 1.0.2 API)";
+            parent.document.title="Deprecated List (annotations 1.1.0 API)";
         }
     }
     catch(err) {

static/documentation/spring-extensions/api/annotations/help-doc.html

@@ -3,7 +3,7 @@
 <html lang="de">
 <head>
 <!-- Generated by javadoc -->
-<title>API Help (annotations 1.0.2 API)</title>
+<title>API Help (annotations 1.1.0 API)</title>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
 <link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">
 <link rel="stylesheet" type="text/css" href="jquery/jquery-ui.css" title="Style">
@@ -20,7 +20,7 @@
 <script type="text/javascript"><!--
     try {
         if (location.href.indexOf('is-external=true') == -1) {
-            parent.document.title="API Help (annotations 1.0.2 API)";
+            parent.document.title="API Help (annotations 1.1.0 API)";
         }
     }
     catch(err) {

static/documentation/spring-extensions/api/annotations/index-all.html

@@ -3,7 +3,7 @@
 <html lang="de">
 <head>
 <!-- Generated by javadoc -->
-<title>Index (annotations 1.0.2 API)</title>
+<title>Index (annotations 1.1.0 API)</title>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
 <link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">
 <link rel="stylesheet" type="text/css" href="jquery/jquery-ui.css" title="Style">
@@ -20,7 +20,7 @@
 <script type="text/javascript"><!--
     try {
         if (location.href.indexOf('is-external=true') == -1) {
-            parent.document.title="Index (annotations 1.0.2 API)";
+            parent.document.title="Index (annotations 1.1.0 API)";
         }
     }
     catch(err) {
@@ -90,7 +90,19 @@
 </nav>
 </header>
 <main role="main">
-<div class="contentContainer"><a href="#I:C">C</a>&nbsp;<a href="#I:E">E</a>&nbsp;<a href="#I:L">L</a>&nbsp;<a href="#I:O">O</a>&nbsp;<a href="#I:S">S</a>&nbsp;<a href="#I:T">T</a>&nbsp;<br><a href="allclasses-index.html">All&nbsp;Classes</a>&nbsp;<a href="allpackages-index.html">All&nbsp;Packages</a><a id="I:C">
+<div class="contentContainer"><a href="#I:A">A</a>&nbsp;<a href="#I:C">C</a>&nbsp;<a href="#I:D">D</a>&nbsp;<a href="#I:E">E</a>&nbsp;<a href="#I:G">G</a>&nbsp;<a href="#I:L">L</a>&nbsp;<a href="#I:O">O</a>&nbsp;<a href="#I:S">S</a>&nbsp;<a href="#I:T">T</a>&nbsp;<a href="#I:V">V</a>&nbsp;<br><a href="allclasses-index.html">All&nbsp;Classes</a>&nbsp;<a href="allpackages-index.html">All&nbsp;Packages</a><a id="I:A">
+<!--   -->
+</a>
+<h2 class="title">A</h2>
+<dl>
+<dt><span class="memberNameLink"><a href="org/mapstruct/extensions/spring/ExternalConversion.html#adapterMethodName()">adapterMethodName()</a></span> - Method in annotation type org.mapstruct.extensions.spring.<a href="org/mapstruct/extensions/spring/ExternalConversion.html" title="annotation in org.mapstruct.extensions.spring">ExternalConversion</a></dt>
+<dd>&nbsp;</dd>
+<dt><a href="org/mapstruct/extensions/spring/AdapterMethodName.html" title="annotation in org.mapstruct.extensions.spring"><span class="typeNameLink">AdapterMethodName</span></a> - Annotation Type in <a href="org/mapstruct/extensions/spring/package-summary.html">org.mapstruct.extensions.spring</a></dt>
+<dd>
+<div class="block">Overrides the default method name generated in the Adapter class.</div>
+</dd>
+</dl>
+<a id="I:C">
 <!--   -->
 </a>
 <h2 class="title">C</h2>
@@ -108,6 +120,17 @@ <h2 class="title">C</h2>
 <div class="block">The bean name for the Spring <a href="https://docs.spring.io/spring/docs/5.0.0.RELEASE/javadoc-api/org/springframework/core/convert/ConversionService.html?is-external=true" title="class or interface in org.springframework.core.convert" class="externalLink"><code>ConversionService</code></a> to use.</div>
 </dd>
 </dl>
+<a id="I:D">
+<!--   -->
+</a>
+<h2 class="title">D</h2>
+<dl>
+<dt><a href="org/mapstruct/extensions/spring/DelegatingConverter.html" title="annotation in org.mapstruct.extensions.spring"><span class="typeNameLink">DelegatingConverter</span></a> - Annotation Type in <a href="org/mapstruct/extensions/spring/package-summary.html">org.mapstruct.extensions.spring</a></dt>
+<dd>
+<div class="block">Indicates that the system should generate a delegating <a href="https://docs.spring.io/spring/docs/5.0.0.RELEASE/javadoc-api/org/springframework/core/convert/converter/Converter.html?is-external=true" title="class or interface in org.springframework.core.convert.converter" class="externalLink"><code>Converter</code></a> that will call the annotated method in its
+ own <a href="https://docs.spring.io/spring/docs/5.0.0.RELEASE/javadoc-api/org/springframework/core/convert/converter/Converter.html?is-external=true#convert(S)" title="class or interface in org.springframework.core.convert.converter" class="externalLink"><code>Converter.convert(Object)</code></a>.</div>
+</dd>
+</dl>
 <a id="I:E">
 <!--   -->
 </a>
@@ -124,6 +147,16 @@ <h2 class="title">E</h2>
  generated Adapter.</div>
 </dd>
 </dl>
+<a id="I:G">
+<!--   -->
+</a>
+<h2 class="title">G</h2>
+<dl>
+<dt><span class="memberNameLink"><a href="org/mapstruct/extensions/spring/SpringMapperConfig.html#generateConverterScan()">generateConverterScan()</a></span> - Method in annotation type org.mapstruct.extensions.spring.<a href="org/mapstruct/extensions/spring/SpringMapperConfig.html" title="annotation in org.mapstruct.extensions.spring">SpringMapperConfig</a></dt>
+<dd>
+<div class="block">Indicates whether to generate a <code>ConverterScan</code> when using <a href="org/mapstruct/extensions/spring/SpringMapperConfig.html#conversionServiceBeanName()"><code>conversionServiceBeanName()</code></a>.</div>
+</dd>
+</dl>
 <a id="I:L">
 <!--   -->
 </a>
@@ -163,7 +196,17 @@ <h2 class="title">T</h2>
 <dt><span class="memberNameLink"><a href="org/mapstruct/extensions/spring/ExternalConversion.html#targetType()">targetType()</a></span> - Method in annotation type org.mapstruct.extensions.spring.<a href="org/mapstruct/extensions/spring/ExternalConversion.html" title="annotation in org.mapstruct.extensions.spring">ExternalConversion</a></dt>
 <dd>&nbsp;</dd>
 </dl>
-<a href="#I:C">C</a>&nbsp;<a href="#I:E">E</a>&nbsp;<a href="#I:L">L</a>&nbsp;<a href="#I:O">O</a>&nbsp;<a href="#I:S">S</a>&nbsp;<a href="#I:T">T</a>&nbsp;<br><a href="allclasses-index.html">All&nbsp;Classes</a>&nbsp;<a href="allpackages-index.html">All&nbsp;Packages</a></div>
+<a id="I:V">
+<!--   -->
+</a>
+<h2 class="title">V</h2>
+<dl>
+<dt><span class="memberNameLink"><a href="org/mapstruct/extensions/spring/AdapterMethodName.html#value()">value()</a></span> - Method in annotation type org.mapstruct.extensions.spring.<a href="org/mapstruct/extensions/spring/AdapterMethodName.html" title="annotation in org.mapstruct.extensions.spring">AdapterMethodName</a></dt>
+<dd>
+<div class="block">The method name to be used instead of the default.</div>
+</dd>
+</dl>
+<a href="#I:A">A</a>&nbsp;<a href="#I:C">C</a>&nbsp;<a href="#I:D">D</a>&nbsp;<a href="#I:E">E</a>&nbsp;<a href="#I:G">G</a>&nbsp;<a href="#I:L">L</a>&nbsp;<a href="#I:O">O</a>&nbsp;<a href="#I:S">S</a>&nbsp;<a href="#I:T">T</a>&nbsp;<a href="#I:V">V</a>&nbsp;<br><a href="allclasses-index.html">All&nbsp;Classes</a>&nbsp;<a href="allpackages-index.html">All&nbsp;Packages</a></div>
 </main>
 <footer role="contentinfo">
 <nav role="navigation">

static/documentation/spring-extensions/api/annotations/index.html

@@ -2,8 +2,8 @@
 <!-- NewPage -->
 <html lang="de">
 <head>
-<!-- Generated by javadoc (11.0.8) on Tue Aug 08 21:36:17 BST 2023 -->
-<title>annotations 1.0.2 API</title>
+<!-- Generated by javadoc (11.0.8) on Mon Sep 25 10:02:16 BST 2023 -->
+<title>annotations 1.1.0 API</title>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
 <script type="text/javascript">window.location.replace('org/mapstruct/extensions/spring/package-summary.html')</script>
 <noscript>