Make several additions to the reference guide

- Replace issue tracker reference for github/axonframework/issues
reference
- Add a note to point out it's by design that you cannot associate
domain concepts with Objects as the identifier
- Add additional constructor parameters for SpringCloudCommandRouter
- Add a note that it's required to enabled heartbeat events within your
spring application when using the SpringCloudCommandRouter
- Add a section to describe how to order Event Handlers within an Event
Processor

Author: smcvb

part1/introduction.md

@@ -90,7 +90,7 @@ When you're stuck
 
 While implementing your application, you might run into problems, wonder about why certain things are the way they are, or have some questions that need an answer. The Axon Users mailing list is there to help. Just send an email to [[email protected]](mailto:[email protected]). Other users as well as contributors to the Axon Framework are there to help with your issues.
 
-If you find a bug, you can report them at [issues.axonframework.org](http://issues.axonframework.org). When reporting an issue, please make sure you clearly describe the problem. Explain what you did, what the result was and what you expected to happen instead. If possible, please provide a very simple Unit Test (JUnit) that shows the problem. That makes fixing it a lot simpler.
+If you find a bug, you can report them at [github.com/AxonFramework/issues](https://github.com/AxonFramework/AxonFramework/issues). When reporting an issue, please make sure you clearly describe the problem. Explain what you did, what the result was and what you expected to happen instead. If possible, please provide a very simple Unit Test (JUnit) that shows the problem. That makes fixing it a lot simpler.
 
 Contributing to Axon Framework
 ==============================
@@ -99,7 +99,7 @@ Development on the Axon Framework is never finished. There will always be more f
 
 There are a number of ways in which you can contribute to the Axon Framework:
 
--   You can report any bugs, feature requests or ideas for improvements on our issue page: [issues.axonframework.org](http://issues.axonframework.org). All ideas are welcome. Please be as exact as possible when reporting bugs. This will help us reproduce and thus solve the problem faster.
+-   You can report any bugs, feature requests or ideas for improvements on our issue page: [github.com/AxonFramework/issues](https://github.com/AxonFramework/AxonFramework/issues). All ideas are welcome. Please be as exact as possible when reporting bugs. This will help us reproduce and thus solve the problem faster.
 
 -   If you have created a component for your own application that you think might be useful to include in the framework, send us a patch or a zip containing the source code. We will evaluate it and try to fit it in the framework. Please make sure code is properly documented using javadoc. This helps us to understand what is going on.
 

part2/event-handling.md

@@ -78,4 +78,4 @@ Configurer axonConfigurer = DefaultConfigurer.defaultConfiguration()
     .registerModule(ehConfiguration);
 ```
 
-See [Event Handling Configuration](../part3/spring-boot-autoconfig.md#event-handling-configuration) for details on registering event handlers using Spring AutoConfiguration.
+See [Event Handling Configuration](../part3/spring-boot-autoconfig.md#event-handling-configuration) for details on registering event handlers using Spring AutoConfiguration.

part2/sagas.md

@@ -47,6 +47,10 @@ When a Saga manages a transaction across multiple domain concepts, such as Order
 
 Associating a Saga with a concept is done in several ways. First of all, when a Saga is newly created when invoking a `@StartSaga` annotated Event Handler, it is automatically associated with the property identified in the `@SagaEventHandler` method. Any other association can be created using the `SagaLifecycle.associateWith(String key, String/Number value)` method. Use the `SagaLifecycle.removeAssociationWith(String key, String/Number value)` method to remove a specific association.
 
+> Note
+>
+> The API to associate domain concepts within a Saga intentionally only allows a `String` or a `Number` as the identifying value, since a `String` representation of the identifier is required for the association value entry which is stored. Using simple identifier values in the API with a straightforward `String` representation is by design, as a `String` column entry in the database makes the comparison between database engines simpler. It is thus intentionally that there is no `associateWith(String, Object)` for example, as the result of an `Object#toString()` call might provide unwieldy identifiers.
+
 Imagine a Saga that has been created for a transaction around an Order. The Saga is automatically associated with the Order, as the method is annotated with `@StartSaga`. The Saga is responsible for creating an Invoice for that Order, and tell Shipping to create a Shipment for it. Once both the Shipment have arrived and the Invoice has been paid, the transaction is completed and the Saga is closed.
 
 Here is the code for such a Saga:

part3/command-dispatching.md

@@ -310,16 +310,22 @@ The Spring Cloud Connector setup uses the service registration and discovery mec
 Giving a description of every Spring Cloud implementation would push this reference guide to far. Hence we refer to their respective documentations for further information.
 
 The Spring Cloud Connector setup is a combination of the `SpringCloudCommandRouter` and a `SpringHttpCommandBusConnector`, which respectively fill the place of the `CommandRouter` and the `CommandBusConnector` for the `DistributedCommandBus`.
-  
+
 > **Note**
 >
-> The Spring Cloud Connector specific components for the `DistributedCommandBus` can be found in the `axon-distributed-commandbus-springcloud` module.
+> When using the `SpringCloudCommandRouter`, make sure that your Spring application is has heartbeat events enabled. The implementation leverages the heartbeat events published by a Spring Cloud application to check whether its knowledge of all the others nodes is up to date. Hence if heartbeat events are disabled the majority of the Axon applications within your cluster will not be aware of the entire set up, thus posing issues for correct command routing.
 
 The `SpringCloudCommandRouter` has to be created by providing the following:
 
 - A "discovery client" of type `DiscoveryClient`. This can be provided by annotating your Spring Boot application with `@EnableDiscoveryClient`, which will look for a Spring Cloud implementation on your classpath.
 
-- A "routing strategy" of type `RoutingStrategy`. The `axon-core` module currently provides several implementations, but a function call can suffice as well. If you want to route the Commands based on the 'aggregate identifier' for example, you would use the `AnnotationRoutingStrategy` and annotate the field on the payload that identifies the aggregate with `@TargetAggregateIdentifier`. 
+- A "routing strategy" of type `RoutingStrategy`. The `axon-core` module currently provides several implementations, but a function call can suffice as well. If you want to route the Commands based on the 'aggregate identifier' for example, you would use the `AnnotationRoutingStrategy` and annotate the field on the payload that identifies the aggregate with `@TargetAggregateIdentifier`.
+
+Other optional parameters for the `SpringCloudCommandRouter`  are:
+
+- A "service instance filter" of type `Predicate<ServiceInstance>`. This predicate is used to filter out `ServiceInstances` which the `DiscoveryClient` might encounter which by forehand you know will not handle any command messages. This might be useful if you've got several services within the Spring Cloud Discovery Service set up which you do not want to take into account for command handling, ever.  
+
+- A "consistent hash change listener" of type `ConsistentHashChangeListener`. Adding a consistent hash change listener provides you the opportunity to perform a specific task if  new members have been added to the known command handlers set.
 
 The `SpringHttpCommandBusConnector` requires three parameters for creation:
 
@@ -329,6 +335,10 @@ The `SpringHttpCommandBusConnector` requires three parameters for creation:
 
 - Lastly a "serializer" of type `Serializer`. The serializer is used to serialize the command messages before they are sent over the wire.
 
+> **Note**
+>
+> The Spring Cloud Connector specific components for the `DistributedCommandBus` can be found in the `axon-distributed-commandbus-springcloud` module.
+
 The `SpringCloudCommandRouter` and `SpringHttpCommandBusConnector` should then both be used for creating the `DistributedCommandsBus`. In Spring Java config, that would look as follows:
 
 ```java

part3/event-processing.md

@@ -44,6 +44,14 @@ will trigger the creation of two Processors:
 
 The Configuration API allows you to configure other strategies for assigning classes to processors, or even assign specific instances to specific processors.
 
+### Ordering Event Handlers within a single Event Processor
+
+To order Event Handlers within an Event Processor, the ordering in which Event Handlers are registered (as described in the [Registering Event Handlers](../part2/event-handling.md#registering-event-handlers) section) is guiding. Thus, the ordering in which Event Handlers will be called by an Event Processor for Event Handling is their insertion ordering in the configuration API. 
+
+If Spring is selected as the mechanism to wire everything, the ordering of the Event Handlers can be specified by adding the `@Order` annotation. This annotation should be placed on class level of your Event Handler class, adding a `integer` value to specify the ordering.
+
+Do note that it is not possible to order Event Handlers which are not a part of the same Event Processor.
+
 ### Configuring processors
 
 Processors take care of the technical aspects of handling an event, regardless of the business logic triggered by each event. However, the way "regular" (singleton, stateless) event handlers are Configured is slightly different from Sagas, as different aspects are important for both types of handlers.