eventsourcing docs
Project: http://git-wip-us.apache.org/repos/asf/zest-qi4j/repo Commit: http://git-wip-us.apache.org/repos/asf/zest-qi4j/commit/6c0e59f3 Tree: http://git-wip-us.apache.org/repos/asf/zest-qi4j/tree/6c0e59f3 Diff: http://git-wip-us.apache.org/repos/asf/zest-qi4j/diff/6c0e59f3 Branch: refs/heads/develop Commit: 6c0e59f368c1cf1186dca76ee50272dae718b024 Parents: 96c58b6 Author: tbml <[email protected]> Authored: Sun Jul 19 08:31:47 2015 +0200 Committer: tbml <[email protected]> Committed: Sun Jul 19 08:31:47 2015 +0200 ---------------------------------------------------------------------- .../src/docs/eventsourcing-jdbm.txt | 31 ------ .../src/docs/eventsourcing-rest.txt | 32 ------ .../eventsourcing/src/docs/eventsourcing.txt | 104 ++++++++++++++++++- 3 files changed, 102 insertions(+), 65 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/6c0e59f3/libraries/eventsourcing-jdbm/src/docs/eventsourcing-jdbm.txt ---------------------------------------------------------------------- diff --git a/libraries/eventsourcing-jdbm/src/docs/eventsourcing-jdbm.txt b/libraries/eventsourcing-jdbm/src/docs/eventsourcing-jdbm.txt deleted file mode 100644 index a2ead6e..0000000 --- a/libraries/eventsourcing-jdbm/src/docs/eventsourcing-jdbm.txt +++ /dev/null @@ -1,31 +0,0 @@ -/////////////////////////////////////////////////////////////// - * Licensed to the Apache Software Foundation (ASF) under one - * or more contributor license agreements. See the NOTICE file - * distributed with this work for additional information - * regarding copyright ownership. The ASF licenses this file - * to you under the Apache License, Version 2.0 (the - * "License"); you may not use this file except in compliance - * with the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, - * software distributed under the License is distributed on an - * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - * KIND, either express or implied. See the License for the - * specific language governing permissions and limitations - * under the License. -/////////////////////////////////////////////////////////////// - -[[library-eventsourcing-jdbm, Event Sourcing JDBM Library]] -= Event Sourcing - JDBM = - -[devstatus] --------------- -source=libraries/eventsourcing-jdbm/dev-status.xml --------------- - - -NOTE: This Library has no documentation yet. Learn how to contribute in <<community-docs>>. - -include::../../build/docs/buildinfo/artifact.txt[] http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/6c0e59f3/libraries/eventsourcing-rest/src/docs/eventsourcing-rest.txt ---------------------------------------------------------------------- diff --git a/libraries/eventsourcing-rest/src/docs/eventsourcing-rest.txt b/libraries/eventsourcing-rest/src/docs/eventsourcing-rest.txt deleted file mode 100644 index c748cbc..0000000 --- a/libraries/eventsourcing-rest/src/docs/eventsourcing-rest.txt +++ /dev/null @@ -1,32 +0,0 @@ -/////////////////////////////////////////////////////////////// - * Licensed to the Apache Software Foundation (ASF) under one - * or more contributor license agreements. See the NOTICE file - * distributed with this work for additional information - * regarding copyright ownership. The ASF licenses this file - * to you under the Apache License, Version 2.0 (the - * "License"); you may not use this file except in compliance - * with the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, - * software distributed under the License is distributed on an - * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - * KIND, either express or implied. See the License for the - * specific language governing permissions and limitations - * under the License. -/////////////////////////////////////////////////////////////// - -[[library-eventsourcing-rest, Event Sourcing ReST Library]] -= Event Sourcing - ReST = - -[devstatus] --------------- -source=libraries/eventsourcing-rest/dev-status.xml --------------- - -Event Sourcing - ReST Library - -NOTE: This Library has no documentation yet. Learn how to contribute in <<community-docs>>. - -include::../../build/docs/buildinfo/artifact.txt[] http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/6c0e59f3/libraries/eventsourcing/src/docs/eventsourcing.txt ---------------------------------------------------------------------- diff --git a/libraries/eventsourcing/src/docs/eventsourcing.txt b/libraries/eventsourcing/src/docs/eventsourcing.txt index 0aedb66..d6a6263 100644 --- a/libraries/eventsourcing/src/docs/eventsourcing.txt +++ b/libraries/eventsourcing/src/docs/eventsourcing.txt @@ -25,8 +25,108 @@ source=libraries/eventsourcing/dev-status.xml -------------- -Event Sourcing Library +The Event Sourcing Library supports generating, storing and replying two types of events: application-events and domain-events. -NOTE: This Library has no documentation yet. Learn how to contribute in <<community-docs>>. +Application events are bound to usecase and are produced by execution of specific methods (ones with ApplicationEvent as their first parameter). +Each application event holds information about usecase, method name and json serialized values of method parameters. + +Domain events are bound to entity instances and are produced by execution of annotated (see @DomainEvent) method that belongs to EntityComposite. +Each domain event (see DomainEventValue) holds information about entity type, identity, method name and json serialized values of method parameters. + +Both application and domain events are captured during UnitOfWork lifetime and are stored in event store after successfully completed UnitOfWork as collection together (see UnitOfWorkDomainEventsValue and TransactionApplicationEvents). + +There is support for replying events. When events are replied the same code is executed but no new events are generated. + +There are helper classes that enables a service to easily track event feed, and +for domain events there is event router that allow specify specification->receiver routes. include::../../build/docs/buildinfo/artifact.txt[] + +*JDBM backed store* + +Event store supports indexed and streamed access to events feed. There is in-memory and JDBM backed implementation. + +[devstatus] +-------------- +source=libraries/eventsourcing-jdbm/dev-status.xml +-------------- + +include::../../../eventsourcing-jdbm/build/docs/buildinfo/artifact.txt[] + +*REST access* + +For remote access to feed there is eventsourcing-rest library that exposes events as Atom feeds. + +[devstatus] +-------------- +source=libraries/eventsourcing-rest/dev-status.xml +-------------- + +include::../../../eventsourcing-rest/build/docs/buildinfo/artifact.txt[] + + +== Application Events == + +Assembly is done as follows: + +[snippet,java] +---- +source=libraries/eventsourcing/src/test/java/org/qi4j/library/eventsourcing/application/ApplicationEventTest.java +tag=assemblyAE +---- + +configure application events store: +[snippet,java] +---- +source=libraries/eventsourcing/src/test/java/org/qi4j/library/eventsourcing/application/ApplicationEventTest.java +tag=storeAE +---- + +Actual method on composite which execution emits application event. First parameter is null on "normal" execution. If it is not null, then the method call is a replay of previously created events. +[snippet,java] +---- +source=libraries/eventsourcing/src/test/java/org/qi4j/library/eventsourcing/application/ApplicationEventTest.java +tag=methodAE +---- + +to enable execution capturing, you have to configure composite with concern: +[snippet,java] +---- +source=libraries/eventsourcing/src/test/java/org/qi4j/library/eventsourcing/application/ApplicationEventTest.java +tag=concernAE +---- + +== Domain Events == + +Assembly: + +[snippet,java] +---- +source=libraries/eventsourcing/src/test/java/org/qi4j/library/eventsourcing/domain/DomainEventTest.java +tag=assemblyDE +---- + +configure domain events store: + +[snippet,java] +---- +source=libraries/eventsourcing/src/test/java/org/qi4j/library/eventsourcing/domain/DomainEventTest.java +tag=storeDE +---- + +annotate your entity state changing methods. Event methods may only change state. They may not fail or thrown exceptions: +[snippet,java] +---- +source=libraries/eventsourcing/src/test/java/org/qi4j/library/eventsourcing/domain/DomainEventTest.java +tag=methodDE +---- + +to enable method execution capturing, you have to configure entity with concern: + +[snippet,java] +---- +source=libraries/eventsourcing/src/test/java/org/qi4j/library/eventsourcing/domain/DomainEventTest.java +tag=concernDE +---- + +
