You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@polygene.apache.org by pa...@apache.org on 2015/07/19 18:40:30 UTC
[4/6] zest-qi4j git commit: eventsourcing docs
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 <ti...@adleritech.com>
Authored: Sun Jul 19 08:31:47 2015 +0200
Committer: tbml <ti...@adleritech.com>
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
+----
+
+