diff --git a/docs/versioned_docs/version-0.x/integration/_category_.yml b/docs/versioned_docs/version-0.x/integration/_category_.yml new file mode 100644 index 0000000..dcc0aae --- /dev/null +++ b/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 diff --git a/docs/versioned_docs/version-0.x/integration/jackson.mdx b/docs/versioned_docs/version-0.x/integration/jackson.mdx new file mode 100644 index 0000000..512987a --- /dev/null +++ b/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 + + + +Versions are managed by the xanthic-bom! + +## 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(); +``` + +  + +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(); +``` +This example is simply included for illustration purposes (and may not be optimally parameterized for your use case). diff --git a/docs/versioned_docs/version-0.x/integration/spring.mdx b/docs/versioned_docs/version-0.x/integration/spring.mdx new file mode 100644 index 0000000..ab30818 --- /dev/null +++ b/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 + + + +
+ For SpringBoot 2.x / Spring 5.x, use this dependency instead + +
+ +Versions are managed by the xanthic-bom! + +## 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. + +Please ensure that you have a [backing cache implementation](/provider/) on your classpath for Xanthic to utilize. + +### 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.