raboof/pekko
1
0
Fork 0
Code Issues Pull requests Projects Releases 6 Packages Wiki Activity Actions 11

Merge paradox/scala/persistence-query-leveldb.md and java/persistence-query-leveldb.md (#23188)

Browse source
This commit is contained in:
Richard Imaoka 2017-06-19 19:50:44 +09:00 • committed by Arnout Engelen
parent 85e55f289b
commit b29753eb84
2 changed files with 44 additions and 148 deletions
Download patch file Download diff file Expand all files Collapse all files

137
akka-docs/src/main/paradox/java/persistence-query-leveldb.md
View file

@ -1,137 +0,0 @@
# Persistence Query for LevelDB
This is documentation for the LevelDB implementation of the @ref:[Persistence Query](persistence-query.md) API.
Note that implementations for other journals may have different semantics.
## Dependencies
Akka persistence LevelDB query implementation is bundled in the `akka-persistence-query` artifact.
Make sure that you have the following dependency in your project:
@@@vars
```
<dependency>
<groupId>com.typesafe.akka</groupId>
<artifactId>akka-persistence-query_$scala.binary_version$</artifactId>
<version>$akka.version$</version>
</dependency>
```
@@@
## How to get the ReadJournal
The `ReadJournal` is retrieved via the `akka.persistence.query.PersistenceQuery`
extension:
@@snip [LeveldbPersistenceQueryDocTest.java]($code$/java/jdocs/persistence/query/LeveldbPersistenceQueryDocTest.java) { #get-read-journal }
## Supported Queries
### EventsByPersistenceIdQuery and CurrentEventsByPersistenceIdQuery
`eventsByPersistenceId` is used for retrieving events for a specific `PersistentActor`
identified by `persistenceId`.
@@snip [LeveldbPersistenceQueryDocTest.java]($code$/java/jdocs/persistence/query/LeveldbPersistenceQueryDocTest.java) { #EventsByPersistenceId }
You can retrieve a subset of all events by specifying `fromSequenceNr` and `toSequenceNr`
or use `0L` and `Long.MAX_VALUE` respectively to retrieve all events. Note that
the corresponding sequence number of each event is provided in the `EventEnvelope`,
which makes it possible to resume the stream at a later point from a given sequence number.
The returned event stream is ordered by sequence number, i.e. the same order as the
`PersistentActor` persisted the events. The same prefix of stream elements (in same order)
are returned for multiple executions of the query, except for when events have been deleted.
The stream is not completed when it reaches the end of the currently stored events,
but it continues to push new events when new events are persisted.
Corresponding query that is completed when it reaches the end of the currently
stored events is provided by `currentEventsByPersistenceId`.
The LevelDB write journal is notifying the query side as soon as events are persisted, but for
efficiency reasons the query side retrieves the events in batches that sometimes can
be delayed up to the configured `refresh-interval` or given `RefreshInterval`
hint.
The stream is completed with failure if there is a failure in executing the query in the
backend journal.
### AllPersistenceIdsQuery and CurrentPersistenceIdsQuery
`allPersistenceIds` is used for retrieving all `persistenceIds` of all persistent actors.
@@snip [LeveldbPersistenceQueryDocTest.java]($code$/java/jdocs/persistence/query/LeveldbPersistenceQueryDocTest.java) { #AllPersistenceIds }
The returned event stream is unordered and you can expect different order for multiple
executions of the query.
The stream is not completed when it reaches the end of the currently used *persistenceIds*,
but it continues to push new *persistenceIds* when new persistent actors are created.
Corresponding query that is completed when it reaches the end of the
currently used *persistenceIds* is provided by `currentPersistenceIds`.
The LevelDB write journal is notifying the query side as soon as new `persistenceIds` are
created and there is no periodic polling or batching involved in this query.
The stream is completed with failure if there is a failure in executing the query in the
backend journal.
### EventsByTag and CurrentEventsByTag
`eventsByTag` is used for retrieving events that were marked with a given tag, e.g.
all domain events of an Aggregate Root type.
@@snip [LeveldbPersistenceQueryDocTest.java]($code$/java/jdocs/persistence/query/LeveldbPersistenceQueryDocTest.java) { #EventsByTag }
To tag events you create an @ref:[Event Adapters](persistence.md#event-adapters) that wraps the events in a `akka.persistence.journal.Tagged`
with the given `tags`.
@@snip [LeveldbPersistenceQueryDocTest.java]($code$/java/jdocs/persistence/query/LeveldbPersistenceQueryDocTest.java) { #tagger }
You can use `NoOffset` to retrieve all events with a given tag or retrieve a subset of all
events by specifying a `Sequence` `offset`. The `offset` corresponds to an ordered sequence number for
the specific tag. Note that the corresponding offset of each event is provided in the
`EventEnvelope`, which makes it possible to resume the stream at a later point from a given offset.
The `offset` is exclusive, i.e. the event with the exact same sequence number will not be included
in the returned stream. This means that you can use the offset that is returned in `EventEnvelope`
as the `offset` parameter in a subsequent query.
In addition to the `offset` the `EventEnvelope` also provides `persistenceId` and `sequenceNr`
for each event. The `sequenceNr` is the sequence number for the persistent actor with the
`persistenceId` that persisted the event. The `persistenceId` + `sequenceNr` is an unique
identifier for the event.
The returned event stream is ordered by the offset (tag sequence number), which corresponds
to the same order as the write journal stored the events. The same stream elements (in same order)
are returned for multiple executions of the query. Deleted events are not deleted from the
tagged event stream.
@@@ note
Events deleted using `deleteMessages(toSequenceNr)` are not deleted from the "tagged stream".
@@@
The stream is not completed when it reaches the end of the currently stored events,
but it continues to push new events when new events are persisted.
Corresponding query that is completed when it reaches the end of the currently
stored events is provided by `currentEventsByTag`.
The LevelDB write journal is notifying the query side as soon as tagged events are persisted, but for
efficiency reasons the query side retrieves the events in batches that sometimes can
be delayed up to the configured `refresh-interval` or given `RefreshInterval`
hint.
The stream is completed with failure if there is a failure in executing the query in the
backend journal.
## Configuration
Configuration settings can be defined in the configuration section with the
absolute path corresponding to the identifier, which is `"akka.persistence.query.journal.leveldb"`
for the default `LeveldbReadJournal.Identifier`.
It can be configured with the following properties:
@@snip [reference.conf]($akka$/akka-persistence-query/src/main/resources/reference.conf) { #query-leveldb }

1
akka-docs/src/main/paradox/java/persistence-query-leveldb.md Symbolic link
View file

@ -0,0 +1 @@
../scala/persistence-query-leveldb.md

46
akka-docs/src/main/paradox/scala/persistence-query-leveldb.md
View file

@ -8,18 +8,34 @@ Note that implementations for other journals may have different semantics.
Akka persistence LevelDB query implementation is bundled in the `akka-persistence-query` artifact. Akka persistence LevelDB query implementation is bundled in the `akka-persistence-query` artifact.
Make sure that you have the following dependency in your project: Make sure that you have the following dependency in your project:
@@@vars Scala
: @@@vars
``` ```
"com.typesafe.akka" %% "akka-persistence-query" % "$akka.version$" "com.typesafe.akka" %% "akka-persistence-query" % "$akka.version$"
``` ```
@@@ @@@
Java
: @@@vars
```
<dependency>
<groupId>com.typesafe.akka</groupId>
<artifactId>akka-persistence-query_$scala.binary_version$</artifactId>
<version>$akka.version$</version>
</dependency>
```
@@@
## How to get the ReadJournal ## How to get the ReadJournal
The `ReadJournal` is retrieved via the `akka.persistence.query.PersistenceQuery` The `ReadJournal` is retrieved via the `akka.persistence.query.PersistenceQuery`
extension: extension:
@@snip [LeveldbPersistenceQueryDocSpec.scala]($code$/scala/docs/persistence/query/LeveldbPersistenceQueryDocSpec.scala) { #get-read-journal } Scala
: @@snip [LeveldbPersistenceQueryDocSpec.scala]($code$/scala/docs/persistence/query/LeveldbPersistenceQueryDocSpec.scala) { #get-read-journal }
Java
: @@snip [LeveldbPersistenceQueryDocTest.java]($code$/java/jdocs/persistence/query/LeveldbPersistenceQueryDocTest.java) { #get-read-journal }
## Supported Queries ## Supported Queries
@ -28,10 +44,14 @@ extension:
`eventsByPersistenceId` is used for retrieving events for a specific `PersistentActor` `eventsByPersistenceId` is used for retrieving events for a specific `PersistentActor`
identified by `persistenceId`. identified by `persistenceId`.
@@snip [LeveldbPersistenceQueryDocSpec.scala]($code$/scala/docs/persistence/query/LeveldbPersistenceQueryDocSpec.scala) { #EventsByPersistenceId } Scala
: @@snip [LeveldbPersistenceQueryDocSpec.scala]($code$/scala/docs/persistence/query/LeveldbPersistenceQueryDocSpec.scala) { #EventsByPersistenceId }
Java
: @@snip [LeveldbPersistenceQueryDocTest.java]($code$/java/jdocs/persistence/query/LeveldbPersistenceQueryDocTest.java) { #EventsByPersistenceId }
You can retrieve a subset of all events by specifying `fromSequenceNr` and `toSequenceNr` You can retrieve a subset of all events by specifying `fromSequenceNr` and `toSequenceNr`
or use `0L` and `Long.MaxValue` respectively to retrieve all events. Note that or use `0L` and @scala[`Long.MaxValue`]@java[`Long.MAX_VALUE`] respectively to retrieve all events. Note that
the corresponding sequence number of each event is provided in the `EventEnvelope`, the corresponding sequence number of each event is provided in the `EventEnvelope`,
which makes it possible to resume the stream at a later point from a given sequence number. which makes it possible to resume the stream at a later point from a given sequence number.
@ -56,7 +76,11 @@ backend journal.
`allPersistenceIds` is used for retrieving all `persistenceIds` of all persistent actors. `allPersistenceIds` is used for retrieving all `persistenceIds` of all persistent actors.
@@snip [LeveldbPersistenceQueryDocSpec.scala]($code$/scala/docs/persistence/query/LeveldbPersistenceQueryDocSpec.scala) { #AllPersistenceIds } Scala
: @@snip [LeveldbPersistenceQueryDocSpec.scala]($code$/scala/docs/persistence/query/LeveldbPersistenceQueryDocSpec.scala) { #AllPersistenceIds }
Java
: @@snip [LeveldbPersistenceQueryDocTest.java]($code$/java/jdocs/persistence/query/LeveldbPersistenceQueryDocTest.java) { #AllPersistenceIds }
The returned event stream is unordered and you can expect different order for multiple The returned event stream is unordered and you can expect different order for multiple
executions of the query. executions of the query.
@ -77,12 +101,20 @@ backend journal.
`eventsByTag` is used for retrieving events that were marked with a given tag, e.g. `eventsByTag` is used for retrieving events that were marked with a given tag, e.g.
all domain events of an Aggregate Root type. all domain events of an Aggregate Root type.
@@snip [LeveldbPersistenceQueryDocSpec.scala]($code$/scala/docs/persistence/query/LeveldbPersistenceQueryDocSpec.scala) { #EventsByTag } Scala
: @@snip [LeveldbPersistenceQueryDocSpec.scala]($code$/scala/docs/persistence/query/LeveldbPersistenceQueryDocSpec.scala) { #EventsByTag }
Java
: @@snip [LeveldbPersistenceQueryDocTest.java]($code$/java/jdocs/persistence/query/LeveldbPersistenceQueryDocTest.java) { #EventsByTag }
To tag events you create an @ref:[Event Adapters](persistence.md#event-adapters) that wraps the events in a `akka.persistence.journal.Tagged` To tag events you create an @ref:[Event Adapters](persistence.md#event-adapters) that wraps the events in a `akka.persistence.journal.Tagged`
with the given `tags`. with the given `tags`.
@@snip [LeveldbPersistenceQueryDocSpec.scala]($code$/scala/docs/persistence/query/LeveldbPersistenceQueryDocSpec.scala) { #tagger } Scala
: @@snip [LeveldbPersistenceQueryDocSpec.scala]($code$/scala/docs/persistence/query/LeveldbPersistenceQueryDocSpec.scala) { #tagger }
Java
: @@snip [LeveldbPersistenceQueryDocTest.java]($code$/java/jdocs/persistence/query/LeveldbPersistenceQueryDocTest.java) { #tagger }
You can use `NoOffset` to retrieve all events with a given tag or retrieve a subset of all You can use `NoOffset` to retrieve all events with a given tag or retrieve a subset of all
events by specifying a `Sequence` `offset`. The `offset` corresponds to an ordered sequence number for events by specifying a `Sequence` `offset`. The `offset` corresponds to an ordered sequence number for