docs: add pages for jackson and spring (#112)

Co-authored-by: Philipp Heuer <[email protected]>

docs/versioned_docs/version-0.x/integration/_category_.yml

@@ -0,0 +1,7 @@
+position: 4
+label: 'Integrations'
+collapsible: true
+collapsed: true
+link:
+  type: generated-index
+  title: Integrations

docs/versioned_docs/version-0.x/integration/jackson.mdx

@@ -0,0 +1,86 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import Alert from '@mui/material/Alert';
+import { JavaDependency } from '@philippheuer/docusaurus-components';
+
+# Jackson
+
+> added in: Xanthic v0.5.0
+
+> requires: Jackson v2.16+
+
+## Description
+
+Jackson relies upon [caching](https://javadoc.io/static/com.fasterxml.jackson.core/jackson-databind/2.16.0/com/fasterxml/jackson/databind/cfg/CacheProvider.html) during [serialization](https://javadoc.io/static/com.fasterxml.jackson.core/jackson-databind/2.16.0/com/fasterxml/jackson/databind/ser/SerializerCache.html), [deserialization](https://javadoc.io/static/com.fasterxml.jackson.core/jackson-databind/2.16.0/com/fasterxml/jackson/databind/deser/DeserializerCache.html), and [type resolution](https://javadoc.io/static/com.fasterxml.jackson.core/jackson-databind/2.16.0/com/fasterxml/jackson/databind/type/TypeFactory.html).
+
+By default, Jackson relies upon [`LRUMap`](https://github.com/FasterXML/jackson-databind/blob/2.16/src/main/java/com/fasterxml/jackson/databind/util/LRUMap.java),
+which utilizes a [modified](https://github.com/FasterXML/jackson-databind/blob/2.16/src/main/java/com/fasterxml/jackson/databind/util/internal/PrivateMaxEntriesMap.java) [`ConcurrentLinkedHashMap`](https://github.com/ben-manes/concurrentlinkedhashmap) (CLHM) implementation.
+CLHM has not been updated in nearly a decade, and its author suggests alternatives such as [Caffeine](/provider/caffeine3).
+
+This module allows you to easily delegate Jackson's caching to your [preferred Xanthic cache implementation](/provider/).
+
+## Installation
+
+<JavaDependency group="io.github.xanthic.cache" name="cache-jackson" scope="implementation" />
+
+<Alert severity="info" variant="outlined">Versions are managed by the <a href="/getting-started/installation">xanthic-bom</a>!</Alert>
+
+## Usage
+
+When building a Jackson Mapper, simply specify [`cacheProvider`](https://javadoc.io/static/com.fasterxml.jackson.core/jackson-databind/2.16.0/com/fasterxml/jackson/databind/cfg/MapperBuilder.html#cacheProvider-com.fasterxml.jackson.databind.cfg.CacheProvider-) with an instance of [`XanthicJacksonCacheProvider`](https://javadoc.io/doc/io.github.xanthic.cache/cache-jackson/latest/io/github/xanthic/jackson/XanthicJacksonCacheProvider.html).
+
+In addition, you must have a [backing cache implementation](/provider/) on your classpath for Xanthic to utilize.
+
+### Defaults
+
+[`XanthicJacksonCacheProvider`'s default instance](https://javadoc.io/static/io.github.xanthic.cache/cache-jackson/0.5.0/io/github/xanthic/jackson/XanthicJacksonCacheProvider.html#defaultInstance()) uses the recommended maximum cache sizes defined by Jackson developers:
+
+```java
+ObjectMapper mapper = JsonMapper.builder()
+    .cacheProvider(XanthicJacksonCacheProvider.defaultInstance())
+    .build();
+```
+
+Here, Xanthic will use the [default cache provider](/#default-cache-provider)
+stored within [`CacheApiSettings`](https://javadoc.io/doc/io.github.xanthic.cache/cache-core/latest/io/github/xanthic/cache/core/CacheApiSettings.html).
+
+### Custom
+
+Alternatively, you can customize the cache specifications used for the deserializer cache, serializer cache, and type factory.
+
+
+In the simplest case, this customization can take the form of different maximum cache sizes:
+```java
+long deserCapacity = 2048;
+long serCapacity = 4096;
+long typesCapacity = 256;
+
+ObjectMapper mapper = JsonMapper.builder()
+    .cacheProvider(new XanthicJacksonCacheProvider(deserCapacity, serCapacity, typesCapacity))
+    .build();
+```
+
+&nbsp;
+
+Alternatively, your customization can involve more complex adjustments like entry expiry and removal listeners.
+Theoretically, you could even mix-and-match different backing implementations via [`spec.provider`](https://javadoc.io/doc/io.github.xanthic.cache/cache-core/latest/io/github/xanthic/cache/core/CacheApiSpec.html).
+```java
+CacheProvider provider = new XanthicJacksonCacheProvider(
+    // for deserialization
+    spec -> spec.maxSize(2048L)
+        .expiryType(ExpiryType.POST_ACCESS)
+        .expiryTime(Duration.ofMinutes(4)),
+    // for serialization
+    spec -> spec.maxSize(4096L)
+        .expiryType(ExpiryType.POST_WRITE)
+        .expiryTime(Duration.ofMinutes(5)),
+    // for type factory
+    spec -> spec.maxSize(256L)
+        .removalListener((key, value, cause) -> {})
+);
+
+ObjectMapper mapper = JsonMapper.builder()
+    .cacheProvider(provider)
+    .build();
+```
+<Alert severity="info" variant="outlined">This example is simply included for illustration purposes (and may not be optimally parameterized for your use case).</Alert>

docs/versioned_docs/version-0.x/integration/spring.mdx

@@ -0,0 +1,112 @@
+import Alert from '@mui/material/Alert';
+import { JavaDependency } from '@philippheuer/docusaurus-components';
+
+# Spring
+
+> added in: Xanthic v0.3.0
+
+## Description
+
+This module provides a integration between Spring's [Cache Abstraction](https://docs.spring.io/spring-framework/reference/integration/cache.html) and Xanthic.
+It provides a [`CacheManager`](https://docs.spring.io/spring-framework/docs/6.1.0/javadoc-api/org/springframework/cache/CacheManager.html) implementation to delegate Spring's caching to your [preferred Xanthic cache implementation](/provider/).
+
+## Installation
+
+<JavaDependency group="io.github.xanthic.cache" name="cache-spring-java17" scope="implementation" />
+
+<details>
+  <summary>For SpringBoot 2.x / Spring 5.x, use this dependency instead</summary>
+  <JavaDependency group="io.github.xanthic.cache" name="cache-spring" scope="implementation" />
+</details>
+
+<Alert severity="info" variant="outlined">Versions are managed by the <a href="/getting-started/installation">xanthic-bom</a>!</Alert>
+
+## Usage
+
+Configure a [`CacheManager`](https://docs.spring.io/spring-framework/docs/6.1.0/javadoc-api/org/springframework/cache/CacheManager.html) bean with Xanthic's [`XanthicSpringCacheManager`](https://javadoc.io/doc/io.github.xanthic.cache/cache-spring-java17/latest/io/github/xanthic/cache/springjdk17/XanthicSpringCacheManager.html) implementation.
+
+The [`XanthicSpringCacheManager`](https://javadoc.io/doc/io.github.xanthic.cache/cache-spring-java17/latest/io/github/xanthic/cache/springjdk17/XanthicSpringCacheManager.html) supports the following modes of operation:
+
+- [Dynamic](#cachemanager-dynamic): Caches are created on demand with the default configuration or can be registered manually.
+- [Static](#cachemanager-static): The manually provided cache names are registered on startup and no further caches can be registered.
+
+<Alert severity="info" variant="outlined">Please ensure that you have a [backing cache implementation](/provider/) on your classpath for Xanthic to utilize.</Alert>
+
+### Dynamic {#cachemanager-dynamic}
+
+#### Configure the [`XanthicSpringCacheManager`](https://javadoc.io/doc/io.github.xanthic.cache/cache-spring-java17/latest/io/github/xanthic/cache/springjdk17/XanthicSpringCacheManager.html)
+
+```java
+@Configuration
+@EnableCaching
+public class CachingConfig {
+
+    @Bean
+    public CacheManager cacheManager() {
+        XanthicSpringCacheManager cacheManager = new XanthicSpringCacheManager(spec -> {
+            spec.maxSize(1000L); // customize the settings according to your needs
+        });
+        // you can create caches with custom settings manually, e.g.:
+        cacheManager.registerCache("my-custom-cache", spec -> {
+            spec.maxSize(5000L);
+        });
+        return cacheManager;
+    }
+}
+```
+
+#### Manually create a Cache
+
+The following snippet shows how to manually create a cache with custom settings:
+
+```java
+@Autowired
+private XanthicSpringCacheManager cacheManager;
+
+public void myFunction() {
+    cacheManager.registerCache("small-cache", spec -> {
+        spec.maxSize(10L);
+        spec.expiryType(ExpiryType.POST_ACCESS);
+        spec.expiryTime(Duration.ofSeconds(10));
+    });
+}
+```
+
+#### Dynamic Creation
+
+If you refer to a non-existing cache name from the Spring Cache Abstraction, for example the `@Cacheable` annotation, the [`XanthicSpringCacheManager`](https://javadoc.io/doc/io.github.xanthic.cache/cache-spring-java17/latest/io/github/xanthic/cache/springjdk17/XanthicSpringCacheManager.html) will create a new cache with the default settings provided in the spec.
+
+```java
+@Cacheable("customer-cache")
+public Customer getCustomerById(Long id) {
+    // ...
+}
+```
+
+For more information about the Spring Cache Abstraction, please refer to the following resources:
+
+- [Spring's documentation](https://docs.spring.io/spring-framework/reference/integration/cache.html)
+- [Baeldung's "A Guide To Caching in Spring"](https://www.baeldung.com/spring-cache-tutorial)
+
+### Static {#cachemanager-static}
+
+#### Configure the [`XanthicSpringCacheManager`](https://javadoc.io/doc/io.github.xanthic.cache/cache-spring-java17/latest/io/github/xanthic/cache/springjdk17/XanthicSpringCacheManager.html) with explicit cache names
+
+```java
+@Configuration
+@EnableCaching
+public class CachingConfig {
+
+    @Bean
+    public CacheManager cacheManager() {
+        XanthicSpringCacheManager cacheManager = new XanthicSpringCacheManager(spec -> {
+            spec.expiryType(ExpiryType.POST_ACCESS);
+            spec.expiryTime(Duration.ofSeconds(15));
+            spec.maxSize(10L);
+        }, Set.of("my-cache-name"));
+        return cacheManager;
+    }
+}
+```
+
+The list of cache names provided in the constructor needs to be exhaustive within static mode, as no further caches can be registered at runtime.