-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: add pages for jackson and spring (#112)
Co-authored-by: Philipp Heuer <[email protected]>
- Loading branch information
1 parent
0c46ae5
commit 1ae3fc1
Showing
3 changed files
with
205 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
position: 4 | ||
label: 'Integrations' | ||
collapsible: true | ||
collapsed: true | ||
link: | ||
type: generated-index | ||
title: Integrations |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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(); | ||
``` | ||
|
||
| ||
|
||
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> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |