Skip to content

Commit

Permalink
Improve Infinispan cache guide
Browse files Browse the repository at this point in the history
  • Loading branch information
karesti committed Jun 18, 2024
1 parent 713c9ba commit d147c0e
Show file tree
Hide file tree
Showing 2 changed files with 78 additions and 5 deletions.
80 changes: 76 additions & 4 deletions docs/src/main/asciidoc/cache-infinispan-reference.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -83,10 +83,82 @@ quarkus.cache.infinispan.client-name=another

== Marshalling

When interacting with Infinispan in Quarkus, you can easily marshal and unmarshal
Java simple types when writing to or reading from the cache. However, when dealing
with Plain Old Java Objects (POJOs), users of Infinispan need to provide the marshalling
schema.
When interacting with Infinispan in Quarkus, you can easily serialize and deserialize Java primitive types when storing or retrieving data from the cache. No additional marshalling configuration is required for Infinispan.

Check warning on line 86 in docs/src/main/asciidoc/cache-infinispan-reference.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.Spelling] Use correct American English spelling. Did you really mean 'deserialize'? Raw Output: {"message": "[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'deserialize'?", "location": {"path": "docs/src/main/asciidoc/cache-infinispan-reference.adoc", "range": {"start": {"line": 86, "column": 75}}}, "severity": "WARNING"}

[source, java]
----
@CacheResult(cacheName = "weather-cache") //<1>
public String getDailyForecast(String dayOfWeek, int dayOfMonth, String city) { //<2>
return dayOfWeek + " will be " + getDailyResult(dayOfMonth % 4) + " in " + city;
}
----
<1> Ask this method execution to be cached in the 'weather-cache'
<2> The key combines `String` dayOfWeek, `int` dayOfMonth and `String` city. The associated value is of type `String`.

However, when using Plain Old Java Objects (POJOs), users of Infinispan must provide the marshalling schema.

Check warning on line 98 in docs/src/main/asciidoc/cache-infinispan-reference.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'. Raw Output: {"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.", "location": {"path": "docs/src/main/asciidoc/cache-infinispan-reference.adoc", "range": {"start": {"line": 98, "column": 14}}}, "severity": "INFO"}

Check warning on line 98 in docs/src/main/asciidoc/cache-infinispan-reference.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.Spelling] Use correct American English spelling. Did you really mean 'POJOs'? Raw Output: {"message": "[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'POJOs'?", "location": {"path": "docs/src/main/asciidoc/cache-infinispan-reference.adoc", "range": {"start": {"line": 98, "column": 45}}}, "severity": "WARNING"}

=== Marshalling Java types

Let's say we want a composite Key using `java.time.LocalDate`.

Check warning on line 102 in docs/src/main/asciidoc/cache-infinispan-reference.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'. Raw Output: {"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.", "location": {"path": "docs/src/main/asciidoc/cache-infinispan-reference.adoc", "range": {"start": {"line": 102, "column": 34}}}, "severity": "INFO"}

[source, java]
----
@CacheResult(cacheName = "weather-cache") //<1>
public String getDailyForecast(LocalDate date, String city) { //<2>
return date.getDayOfWeek() + " will be " + getDailyResult(date.getDayOfMonth() % 4) + " in " + city;
}
----
<1> Request that the response of this method execution be cached in 'weather-cache'
<2> The key combines a `java.util.LocalDate` date and a `String` city. The associated value is of type 'String'.

Since Infinispan serializes data by default using Protobuf in Quarkus, executing the code will result in the following error:

Check warning on line 114 in docs/src/main/asciidoc/cache-infinispan-reference.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'. Raw Output: {"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.", "location": {"path": "docs/src/main/asciidoc/cache-infinispan-reference.adoc", "range": {"start": {"line": 114, "column": 44}}}, "severity": "INFO"}

Check warning on line 114 in docs/src/main/asciidoc/cache-infinispan-reference.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.Spelling] Use correct American English spelling. Did you really mean 'Protobuf'? Raw Output: {"message": "[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'Protobuf'?", "location": {"path": "docs/src/main/asciidoc/cache-infinispan-reference.adoc", "range": {"start": {"line": 114, "column": 51}}}, "severity": "WARNING"}

[source, bash]
----
java.lang.IllegalArgumentException:
No marshaller registered for object of Java type java.time.LocalDate
----

Protobuf does not inherently know how to marshal `java.time.LocalDate`. Fortunately, Protostream provides a straightforward solution to this problem using `@ProtoAdapter` and `@ProtoSchema`.

Check warning on line 122 in docs/src/main/asciidoc/cache-infinispan-reference.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.Spelling] Use correct American English spelling. Did you really mean 'Protobuf'? Raw Output: {"message": "[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'Protobuf'?", "location": {"path": "docs/src/main/asciidoc/cache-infinispan-reference.adoc", "range": {"start": {"line": 122, "column": 1}}}, "severity": "WARNING"}

Check warning on line 122 in docs/src/main/asciidoc/cache-infinispan-reference.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.Spelling] Use correct American English spelling. Did you really mean 'Protostream'? Raw Output: {"message": "[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'Protostream'?", "location": {"path": "docs/src/main/asciidoc/cache-infinispan-reference.adoc", "range": {"start": {"line": 122, "column": 75}}}, "severity": "WARNING"}

[source, java]
----
@ProtoAdapter(LocalDate.class)
public class LocalDateAdapter {
@ProtoFactory
LocalDate create(String localDate) {
return LocalDate.parse(localDate);
}
@ProtoField(1)
String getLocalDate(LocalDate localDate) {
return localDate.toString();
}
}
@ProtoSchema(includeClasses = LocalDateAdapter.class, schemaPackageName = "quarkus")
public interface Schema extends GeneratedSchema {
}
----


=== Marshalling your POJOs

Check warning on line 145 in docs/src/main/asciidoc/cache-infinispan-reference.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.Headings] Use sentence-style capitalization in 'Marshalling your POJOs'. Raw Output: {"message": "[Quarkus.Headings] Use sentence-style capitalization in 'Marshalling your POJOs'.", "location": {"path": "docs/src/main/asciidoc/cache-infinispan-reference.adoc", "range": {"start": {"line": 145, "column": 5}}}, "severity": "INFO"}

Check warning on line 145 in docs/src/main/asciidoc/cache-infinispan-reference.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale

[vale] reported by reviewdog 🐶 [Quarkus.Spelling] Use correct American English spelling. Did you really mean 'POJOs'? Raw Output: {"message": "[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'POJOs'?", "location": {"path": "docs/src/main/asciidoc/cache-infinispan-reference.adoc", "range": {"start": {"line": 145, "column": 22}}}, "severity": "WARNING"}

Just like with Java types, when using your POJOs as keys or values, you can follow this approach:

[source, java]
----
@CacheResult(cacheName = "my-cache") //<1>
public ExpensiveResponse requestApi(String id) { //<2>
// very expensive call
return new ExpensiveResponse(...);
}
----
<1> Request that the response of this method execution be cached in 'my-cache'
<2> The key is a `String`. The associated value is of type `org.acme.ExpensiveResponse`.

In this case, you'll need to define the schema for your Java type using `@Proto` and `@ProtoSchema`. This schema can encompass all types and adapters used in your Quarkus application.

[source, java]
----
Expand Down
3 changes: 2 additions & 1 deletion docs/src/main/asciidoc/cache.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,8 @@ We'll do that using a single Quarkus annotation.
[NOTE]
====
In this guide, we use the default Quarkus Cache backend (Caffeine).
You can use Redis instead.
You can use Infinispan or Redis instead.
Refer to the xref:cache-infinispan-reference.adoc[Infinispan cache backend reference] to configure the Infinispan backend.
Refer to the xref:cache-redis-reference.adoc[Redis cache backend reference] to configure the Redis backend.
====

Expand Down

0 comments on commit d147c0e

Please sign in to comment.