[MRESOLVER-633] Document caching of unresolvable artifacts

Author: kwin

src/site/markdown/local-repository.md

@@ -18,6 +18,8 @@ specific language governing permissions and limitations
 under the License.
 -->
 
+<!--MACRO{toc|fromDepth=1}-->
+
 Maven Resolver implements a "local repository" (that is used by Maven itself
 as well), that since the beginning of time was a "mixed bag of beans", 
 it served twofold purposes: to cache the artifacts downloaded from 
@@ -188,3 +190,19 @@ available, providing out of the box lock implementations for cases like:
 
 For details see [Named Locks module](maven-resolver-named-locks/).
 
+## Error Handling and Caching
+
+By default each artifact which cannot be resolved leads to an error either classified as 
+
+1. *not found* error or
+2. (any) *other* error (for authentication issues, timeouts etc.)
+
+The caching behavior for both types can be be configured programmatically via `org.eclipse.aether.DefaultRepositorySystemSession.setResolutionErrorPolicy(...)`.
+
+In case caching is enabled for any of the two classifications a Java Properties file is created/updated (with the same filename as the cached artifact in the success case would get but with the additional suffix `.lastUpdated`) in the local repository. Within that file the key `<canonical-remote-url>.error` is updated/added. Its value either contains the error message (for type 2 resolver errors) or is empty (for type 1 resolver errors).
+
+### Configuration in Maven
+
+In Maven 3 resolver errors of **type 1** are **always cached** and the ones of **type 2** are **never cached**.
+
+With [Maven 4](https://issues.apache.org/jira/browse/MNG-7653) the caching of type 1 errors can be disabled with CLI option `-canf false` (still enabled by default). However, the caching of type 2 errors is disabled without any way to override that policy even in Maven 4.