refs #230: Clean up example projects and documentation (#233)

Author: JaidenAshmore

README.md

@@ -150,8 +150,7 @@ subprojects {
         violationRules {
             rule {
                 excludes = listOf(
-                        "com.jashmore.sqs.examples*",
-                        "com.jashmore.sqs.extensions.xray.client"
+                        "com.jashmore.sqs.examples*"
                 )
                 element = "PACKAGE"
                 limit {

build.gradle.kts

@@ -1,15 +1,15 @@
 # Java Dynamic SQS Listener Core
 
-This is the core implementation of the Dynamic SQS Listener API. This contains basic implementations that should cover a
-significant amount of use cases but if it doesn't the consumer can easily implement their own.
+This is the core implementation of the Dynamic SQS Listener API. This contains basic implementations that should cover a significant amount of use cases
+but if it doesn't, the consumer can easily implement their own.
 
 ## Usage
 
-See [java-dynamic-sqs-listener-core-examples](../examples/core-examples) for examples of
-using this core code to listen to a queue.
+See the [core-example](../examples/core-example) for examples of using this core code to listen to a queue in a Java application. If it is a Kotlin application,
+the [core-kotlin-example](../examples/core-kotlin-example) uses a [Core Kotlin DSL](../extensions/core-kotlin-dsl) for constructing a core message listener.
 
 ## More Information
 
-For more information you can look at the root project [README.md](../README.md) which provides more information about
-the architecture of the application. The [API](../api) is also a good location to find more
-information about what each part of the framework is how they interact with each other.
+For more information you can look at the root project [README.md](../README.md) which provides more information about the architecture
+of the application. The [API](../api) is also a good location to find more information about what each part of the framework is how
+they interact with each other.

core/README.md

@@ -12,20 +12,20 @@ The following is the diagram for how a single message would be processed through
 ### Message Retriever
 
 The [MessageRetriever](../api/src/main/java/com/jashmore/sqs/retriever) has a simple API in that it only exposes methods to obtain
-a message from the queue and it makes no requirements on how it should get these messages from the SQS queue. This allows for ability to optimise the
+a message from the queue, and it makes no requirements on how it should get these messages from the SQS queue. This allows for ability to optimise the
 retrieval of messages such as batching requests for retrieving messages or pre-fetching messages.
 
 Core implementations include:
 
 - [PrefetchingMessageRetriever](../core/src/main/java/com/jashmore/sqs/retriever/prefetch/PrefetchingMessageRetriever.java):
-this will prefetch messages from the queue so that new messages can be processed as soon as possible. This implementation is not appropriate if the
-prefetched message's visibility timeout expires before it can be picked up for process due to the message processing of previous messages taking too long.
-The result is that if the message has a re-drive policy it will be placed back into the queue and processed multiple times. This implementation is appropriate
+this will prefetch messages from the queue so that new messages can be processed as soon as possible. This implementation is not appropriate if the time
+to process messages is long enough for the prefetched message's visibility timeout to expire before it can be processed. In this scenario, the message's
+re-drive policy may place the message back into the queue resulting in it being processed multiple times. This implementation is appropriate
 for high volumes of messages that take little time to process.
 - [BatchingMessageRetriever](../core/src/main/java/com/jashmore/sqs/retriever/batching/BatchingMessageRetriever.java):
-This will batch requests for messages from the consumer into a single call out to the SQS queue once a certain threshold of messages were requested or at
-a given period if this threshold is not reached. This reduces the number of calls out to the SQS queue but reduces the performance
-as messages are not being requested while the batch is waiting to be built.
+This will batch requests for messages from the consumer into a single call out to the SQS queue once reaching the threshold of messages, or the batching
+timeout expires. This reduces the number of calls out to the SQS queue but can reduce the performance as no messages processing will occur while waiting
+for the batch size to be reached.
 
 ### Message Processor
 
@@ -39,12 +39,15 @@ Core implementations include:
 
 - [CoreMessageProcessor](../core/src/main/java/com/jashmore/sqs/processor/CoreMessageProcessor.java):
 default implementation that calls out to a `ArgumentResolverService` to resolve the arguments and calls the method.
+- [DecoratingMessageProcessor](../core/src/main/java/com/jashmore/sqs/processor/DecoratingMessageProcessor.java): implementation that allows for the
+message processing to be decorated with [MessageProcessingDecorator](../api/src/main/java/com/jashmore/sqs/decorator/MessageProcessingDecorator.java) logic.
+This can be useful for adding tracing, metrics or other extra functionality in the message processing.
 
 ### ArgumentResolverService
 
 The [ArgumentResolverService](../api/src/main/java/com/jashmore/sqs/argument/ArgumentResolverService.java) is used to obtain the
 [ArgumentResolver](../api/src/main/java/com/jashmore/sqs/argument/ArgumentResolver.java) that can be used to populate an argument
-in a method when a message is being processed. For example, a parameter with the
+in a method when processing a message. For example, a parameter with the
 [@Payload](../core/src/main/java/com/jashmore/sqs/argument/payload/Payload.java) annotation will be resolved with the body
 of the message cast to that type.
 
@@ -55,7 +58,7 @@ this implementation delegates to specific [ArgumentResolver](../api/src/main/jav
 that have been passed in. See below for the core
 [ArgumentResolver](../api/src/main/java/com/jashmore/sqs/argument/ArgumentResolver.java)s that are available.
 - [CoreArgumentResolverService](../core/src/main/java/com/jashmore/sqs/argument/CoreArgumentResolverService.java): this is
-a helper implementation that uses the DelegatingArgumentResolverService under the hood with all of the core
+a helper implementation that uses the DelegatingArgumentResolverService under the hood with the core
 [ArgumentResolver](../api/src/main/java/com/jashmore/sqs/argument/ArgumentResolver.java)s.
 
 The core arguments that be resolved include:
@@ -64,56 +67,58 @@ The core arguments that be resolved include:
 this argument. This is useful if you need to forward this message to other services or want to manually extract information from the service. This is
 provided by the [MessageArgumentResolver](../core/src/main/java/com/jashmore/sqs/argument/message/MessageArgumentResolver.java).
 - [@Payload](../core/src/main/java/com/jashmore/sqs/argument/payload/Payload.java): arguments annotated with this will parse the
-message body into that object. If this is a String a direct transfer of the message contents is passed in, otherwise if it is a Java Bean, an attempt to
+message body into that object. If this is a String, the raw message body will be provided, otherwise if it is a Java Bean, an attempt to
 cast the message body to that bean will be used. This is provided by the
-[PayloadArgumentResolver](../core/src/main/java/com/jashmore/sqs/argument/payload/PayloadArgumentResolver.java), which uses
+[PayloadArgumentResolver](../core/src/main/java/com/jashmore/sqs/argument/payload/PayloadArgumentResolver.java) which uses
 a [PayloadMapper](../core/src/main/java/com/jashmore/sqs/argument/payload/mapper/PayloadMapper.java), such as
-the [JacksonPayloadMapper](../core/src/main/java/com/jashmore/sqs/argument/payload/mapper/JacksonPayloadMapper.java)
-that uses a Jackson `ObjectMapper` to parse the message body.
+the [JacksonPayloadMapper](../core/src/main/java/com/jashmore/sqs/argument/payload/mapper/JacksonPayloadMapper.java), to parse the message body.
 - [@MessageId](../core/src/main/java/com/jashmore/sqs/argument/messageid/MessageId.java): string arguments annotated with this will
 place the message ID of the message into this argument. This is provided by the
 [MessageIdArgumentResolver](../core/src/main/java/com/jashmore/sqs/argument/messageid/MessageIdArgumentResolver.java).
 - [Acknowledge](../api/src/main/java/com/jashmore/sqs/processor/argument/Acknowledge.java): arguments of this type will be injected
-with an implementation that allows for a message to be manually acknowledged when it is successfully processed. Note that if this is included in the messages
-signature, the [MessageProcessor](../api/src/main/java/com/jashmore/sqs/processor/MessageProcessor.java) is not required to
-acknowledge the message after a successful execution. These implementations should be provided by the
-[MessageProcessor](../api/src/main/java/com/jashmore/sqs/processor/MessageProcessor.java) being used.
-- [MessageAttribute](../core/src/main/java/com/jashmore/sqs/argument/attribute/MessageAttribute.java): arguments annotated with this
+with an implementation that allows for a message to be manually acknowledged when it is successfully processed. Note that if this is included,
+the [MessageProcessor](../api/src/main/java/com/jashmore/sqs/processor/MessageProcessor.java) is not required to
+acknowledge the message after a successful execution and the consumer must acknowledge the message them self. The implementation of the
+[Acknowledge](../api/src/main/java/com/jashmore/sqs/processor/argument/Acknowledge.java) should be provided by the
+[MessageProcessor](../api/src/main/java/com/jashmore/sqs/processor/MessageProcessor.java) instead of
+an [ArgumentResolver](../api/src/main/java/com/jashmore/sqs/argument/ArgumentResolver.java).
+- [@MessageAttribute](../core/src/main/java/com/jashmore/sqs/argument/attribute/MessageAttribute.java): arguments annotated with this
 will attempt to parse the contents of the message attribute into this field. For example, if the argument is a String then the attribute will be cast to a
 string where as if the argument is an integer it will try and parse the string into the number.  This also works with POJOs in that the resolver will
  attempt to deserialised the message attribute into this POJO shape, e.g. via the Jackson Object Mapper.  This is provided by the
 [MessageAttributeArgumentResolver](../core/src/main/java/com/jashmore/sqs/argument/attribute/MessageAttributeArgumentResolver.java).
-- [MessageSystemAttribute](../core/src/main/java/com/jashmore/sqs/argument/attribute/MessageAttribute.java); arguments annotated
+- [@MessageSystemAttribute](../core/src/main/java/com/jashmore/sqs/argument/attribute/MessageAttribute.java): arguments annotated
 with this will attempt to parse the contents of a system message attribute into this field. For example, the `SENT_TIMESTAMP` of the message can be obtained
 by this annotation.  This is provided by the
 [MessageSystemAttributeArgumentResolver](../core/src/main/java/com/jashmore/sqs/argument/attribute/MessageSystemAttributeArgumentResolver.java).
 - [VisibilityExtender](../api/src/main/java/com/jashmore/sqs/processor/argument/VisibilityExtender.java): arguments of this type
 will be injected with an implementation that extends the message visibility of the current message.  These implementations should be provided by the
-[MessageProcessor](../api/src/main/java/com/jashmore/sqs/processor/MessageProcessor.java) being used.
+[MessageProcessor](../api/src/main/java/com/jashmore/sqs/processor/MessageProcessor.java) instead of
+an [ArgumentResolver](../api/src/main/java/com/jashmore/sqs/argument/ArgumentResolver.java).
 
 ### Message Broker
 
 The [MessageBroker](../api/src/main/java/com/jashmore/sqs/broker/MessageBroker.java) is the main container that controls the
 whole flow of messages from the [MessageRetriever](../api/src/main/java/com/jashmore/sqs/retriever) to the
 [MessageProcessor](../api/src/main/java/com/jashmore/sqs/processor/MessageProcessor.java). It can provide logic like the rate
-of concurrency of the messages being processed or when messages should be processed.
+of concurrency of messages processing or when messages should be processed.
 
 Core implementation include:
 
 - [ConcurrentMessageBroker](../core/src/main/java/com/jashmore/sqs/broker/concurrent/ConcurrentMessageBroker.java): this
-implementation will run on multiple threads each processing messages. It has dynamic configuration and this allows the rate of concurrency to change
-dynamically while the application is running.
+implementation will run on multiple threads each processing messages. It allows the configuration to be changed dynamically, such as changing the rate of
+concurrency to change while the application is running.
 
 ### Message Resolver
 
 The [MessageResolver](../api/src/main/java/com/jashmore/sqs/resolver/MessageResolver.java) is used when the message has been
-successfully processed and it is needed to be removed from the SQS queue so it isn't processed again.
+successfully processed, and it needs to be removed from the SQS queue.
 
 Core implementation include:
 
 - [BatchingMessageResolver](../core/src/main/java/com/jashmore/sqs/resolver/batching/BatchingMessageResolver.java): this
 implementation will batch calls to delete messages from the SQS queue into a batch that will go out together once asynchronously. This is useful if you
-are processing many messages at the same time and it is desirable to reduce the number of calls out to SQS. A disadvantage is that the message may
-sit in the batch for enough time that the visibility expires and it is placed onto the queue. To mitigate this, smaller batch
-timeout should be used or by increasing the visibility timeout. Note you can configure this to always delete a message as soon as it is finished by
+are processing many messages at the same time, and it is desirable to reduce the number of calls out to SQS. A disadvantage is that the message may
+sit in the batch for enough time for the visibility timeout to expire, and it is placed onto the queue again. To mitigate this, a smaller batch
+timeout should be used or by increasing the visibility timeout. Note that you can configure this to always delete a message as soon as it is finished by
 setting the batch size of 1.

doc/core-implementations-overview.md

@@ -26,7 +26,7 @@ the [DecoratingMessageProcessor](../../../core/src/main/java/com/jashmore/sqs/pr
 
 ## Example
 
-See the [core-examples](../../../examples/core-examples) for a basic application that is running with tracing enabled automatically.
+See the [core-example](../../../examples/core-example) for a basic application that is running with tracing enabled automatically.
 
 ## Including Brave information in your SQS messages
 

doc/how-to-guides/core/core-how-to-add-brave-tracing.md

@@ -12,7 +12,7 @@ is written in a non-blocking programming style.  The current core implementation
 [retriever package](../../../core/src/main/java/com/jashmore/sqs/retriever).
 
 Once you have built your own retriever you can see how this can be integrated into the framework by looking in the [examples](../../../examples) directory
-and more specifically in the [core-examples module](../../../examples/core-examples).
+and more specifically in the [core-example](../../../examples/core-example) module.
 
 ### Integrating the new message retriever into the spring app
 

doc/how-to-guides/core/core-how-to-implement-a-custom-message-retrieval.md

@@ -10,26 +10,6 @@ In this example we are defining the SQS Properties needed via Environment variab
 documentation about different ways to define these properties. The [Spring AWS Example](../../examples/spring-aws-example) will be
 used for this guide.
 
-## Steps
+## Usage
 
-1. Create a new AWS account. You can Google for links on where to do this.
-1. Create a new SQS Queue in a region near you, e.g. us-east-2 (Ohio). You will need the region and Queue URL.
-1. Create a new IAM user that has full permission (for simplicity, otherwise you can put a more restricted permissions) to this SQS queue. You will
-need the Access Key ID and Secret Access Key.
-1. Change directory to the AWS Spring example.
-
-    ```bash
-    cd examples/java-dynamic-sqs-listener-spring-aws-example
-    ```
-
-1. Run the Spring Boot application with the AWS details recorded above. For example:
-
-    ```bash
-    AWS_ACCESS_KEY_ID={KEY_RECORDED_ABOVE} \
-    AWS_REGION={REGION_QUEUE_CREATED_IN_ABOVE} \
-    AWS_SECRET_ACCESS_KEY={SECRET_KEY_RECORDED_ABOVE} \
-    SQS_QUEUE_URL={FULL_URL_OF_SQS_QUEUE} \
-    gradle bootRun
-    ```
-
-1. Send a message to the Queue by right clicking the queue in the AWS Console and selecting Send Message
+See the [Spring AWS Example README.md](../../examples/spring-aws-example/README.md) for steps to use this yourself.