Skip to content

Commit

Permalink
Merge pull request #119 from norbertpotocki/doc-fixes
Browse files Browse the repository at this point in the history 
Documentation improvements
  • Loading branch information
@abuijze
abuijze committed May 14, 2014
2 parents 1717b14 + d087dd9 commit 5af06b4
Showing 1 changed file with 23 additions and 23 deletions.
46 changes: 23 additions & 23 deletions documentation/src/main/docbook/en-US/reference-guide/5-repositories-and-event-stores.xml
View file
Expand Up @@ -697,16 +697,16 @@ public class AdministrativeDetailsUpdatedUpcaster implements Upcaster<Documen
</callout>
<callout arearefs="upcast-body">
<para> By copying the address and policy element from the
AdministrativeDetailsUpdatedEvent each into its own document, the
<code>AdministrativeDetailsUpdatedEvent</code> each into its own document, the
event is upcasted. Deserializing the result would get us an instance
of the InsurancePolicyUpdatedEvent and an instance of the
AddressUpdatedEvent.</para>
<code>AddressUpdatedEvent</code>.</para>
</callout>
<callout arearefs="upcast-type">
<para> Upcasting can be expensive, possibly involving type conversion,
deserialization and logic. Axon is smart enough to prevent this from
happening when it is not neccesary through the concept of
SerializedTypes. SerializedTypes provide Axon with the information
<code>SerializedType</code>s. <code>SerializedType</code>s provide Axon with the information
to delay event upcasting until the application requires it.</para>
</callout>
</calloutlist>
Expand All @@ -732,41 +732,41 @@ public class AdministrativeDetailsUpdatedUpcaster implements Upcaster&lt;Documen
<sect2>
<title>The Upcaster Chain</title>
<para>The Upcaster Chain is responsible for upcasting events by chaining the output of
one upcaster to the next. It comes in the following two flavours: </para>
one upcaster to the next. It comes in the following two flavours:</para>
<itemizedlist>
<listitem>
<para>The <code>SimpleUpcasterChain</code> immediately upcasts all events given
to it and returns them. </para>
to it and returns them.</para>
</listitem>
<listitem>
<para>The <code>LazyUpcasterChain</code> prepares the events to be upcasted but
only upcasts the events that are actually used. Whether or not your
application needs all events this can give you a significant performance
benefit. In the worst case it's as slow as the SimpleUpcasterChain. The
LazyUpcasterChain does not guarantee that all the events in an Event Stream
benefit. In the worst case it's as slow as the <code>SimpleUpcasterChain</code>. The
<code>LazyUpcasterChain</code> does not guarantee that all the events in an Event Stream
are in fact upcasted. When your upcasters rely on information from previous
events, this may be a problem. </para>
events, this may be a problem.</para>
</listitem>
</itemizedlist>
<para>The LazyUpcasterChain is a safe choice if your upcasters are stateless or do not
depend on other upcasters. Always consider using the LazyUpcasterChain since it can
provide a great performance benefit over the SimpleUpcasterChain. If you want
guaranteed upcasting in a strict order, use the SimpleUpcasterChain. </para>
<para>The <code>LazyUpcasterChain</code> is a safe choice if your upcasters are stateless or do not
depend on other upcasters. Always consider using the <code>LazyUpcasterChain</code> since it can
provide a great performance benefit over the <code>SimpleUpcasterChain</code>. If you want
guaranteed upcasting in a strict order, use the <code>SimpleUpcasterChain</code>.</para>
</sect2>
<sect2>
<title>Content type conversion</title>
<para>An upcaster works on a given content type (e.g. dom4j Document). To provide extra
flexibility between upcasters, content types between chained upcasters may vary.
Axon will try to convert between the content types automatically by using
ContentTypeConverters. It will search for the shortest path from type <code>x</code>
<code>ContentTypeConverter</code>s. It will search for the shortest path from type <code>x</code>
to type <code>y</code>, perform the conversion and pass the converted value into the
requested upcaster. For performance reasons, conversion will only be performed if
the <code>canUpcast</code> method on the receiving upcaster yields true. </para>
<para>The ContentTypeConverters may depend on the type of serializer used. Attempting to
convert a byte[] to a dom4j Document will not make any sence unless a Serializer was
used that writes an event as XML. To make sure the UpcasterChain has access to the
serializer-specific ContentTypeConverters, you can pass a reference to the
serializer to the constructor of the UpcasterChain.</para>
<para>The <code>ContentTypeConverter</code>s may depend on the type of serializer used. Attempting to
convert a <code>byte[]</code> to a dom4j <code>Document</code> will not make any sence unless a <code>Serializer</code> was
used that writes an event as XML. To make sure the <code>UpcasterChain</code> has access to the
serializer-specific <code>ContentTypeConverter</code>s, you can pass a reference to the
serializer to the constructor of the <code>UpcasterChain</code>.</para>
<tip>
<para>To achieve the best performance, ensure that all upcasters in the same chain
(where one's output is another's input) work on the same content type. </para>
Expand Down Expand Up @@ -869,7 +869,7 @@ public class AdministrativeDetailsUpdatedUpcaster implements Upcaster&lt;Documen
your aggregate must either have an accessible default constructor or implement
the <code>Serializable</code> interface. </para>
</note>
<para>The AbstractSnapshotter provides a basic set of properties that allow you to tweak
<para>The <code>AbstractSnapshotter</code> provides a basic set of properties that allow you to tweak
the way snapshots are created:
<itemizedlist>
<listitem>
Expand Down Expand Up @@ -905,7 +905,7 @@ public class AdministrativeDetailsUpdatedUpcaster implements Upcaster&lt;Documen
<code>SpringAggregateSnapshotter</code>, which allows you to configure a
<code>PlatformTransactionManager</code>. The
<code>SpringAggregateSnapshotter</code> will autowire all aggregate
factories (either directly, or via the Repository), if a list is not explicitly
factories (either directly, or via the <code>Repository</code>), if a list is not explicitly
configured. </para>
</note>
</sect2>
Expand Down Expand Up @@ -1018,8 +1018,8 @@ public class AdministrativeDetailsUpdatedUpcaster implements Upcaster&lt;Documen
user applied his command first, the second one will make the change to version 5,
instead of the version 4 that he expected. This second command will generate a
CustomerMovedEvent. This event is compared to all unseen events: AddressCorrectedEvent,
in this case. A ConflictResolver will compare these events, and decide that these
conflicts may be merged. If the other user had committed first, the ConflictResolver
in this case. A <code>ConflictResolver</code> will compare these events, and decide that these
conflicts may be merged. If the other user had committed first, the <code>ConflictResolver</code>
would have decided that a AddressCorrectedEvent on top of an unseen CustomerMovedEvent
is considered a conflicting change.
</para>
Expand All @@ -1034,7 +1034,7 @@ public class AdministrativeDetailsUpdatedUpcaster implements Upcaster&lt;Documen
the <code>EventSourcingRepository</code>. This <code>ConflictResolver</code> is
responsible for detecting conflicting modifications, based on the events representing
these changes. Detecting these conflicts is a matter of comparing the two lists of
DomainEvents provided in the <code>resolveConflicts</code> method declared on the
<code>DomainEvent</code>s provided in the <code>resolveConflicts</code> method declared on the
<code>ConflictResolver</code>. If such a conflict is found, a
<code>ConflictingModificationException</code> (or better, a more explicit and
explanatory subclass of it) must be thrown. If the <code>ConflictResolver</code> returns
Expand Down

0 comments on commit 5af06b4

Please sign in to comment.