From 512ade9a500b15cc5d9fcef7c42efa18d7cd2f45 Mon Sep 17 00:00:00 2001 From: Benjamin Graf Date: Mon, 23 Dec 2024 13:29:07 +0100 Subject: [PATCH] Enhance documentation and correct spelling --- README.md | 32 ++++++++++++++++++++++++-------- 1 file changed, 24 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index fbfa8953..764927ca 100644 --- a/README.md +++ b/README.md @@ -24,14 +24,14 @@ to customize the Narayana configuration. See the [NarayanaProperties](narayana-spring-boot-core/src/main/java/dev/snowdrop/boot/narayana/core/properties/NarayanaProperties.java) Javadoc for complete details. -> Only a limited number of Narayana configuration options are exposed via `application.properties`. For a more -more complex configuration you can provide a `jbossts-properties.xml` file. To get more details, please, consult +> Only a limited number of Narayana configuration options are exposed via `application.properties`. For a more complex +configuration you can provide a `jbossts-properties.xml` file. To get more details, please, consult Narayana project [documentation](http://narayana.io/docs/project/index.html). > To ensure that multiple transaction managers can safely coordinate the same resource managers, each Narayana instance must be configured with a unique ID. By default, this ID is set to 1. To ensure uniqueness in production, you should configure the `narayana.node-identifier` property with a different value for each instance of your application. This value -must not exceed a length of 28 bytes. To ensure that the value is shorten to a valid length by hashing with SHA-224 and encoding +must not exceed a length of 28 bytes. To ensure that the value is shortened to a valid length by hashing with SHA-224 and encoding with base64, configure `narayana.shorten-node-identifier-if-necessary` property to true. Be aware, this may result in duplicate strings which break the uniqueness that is mandatory for safe transaction usage! @@ -52,11 +52,17 @@ public class Application { # Using databases -By default Narayana Transactional driver is used to enlist a relational database to a JTA transaction which provides a basic XAResource enlistment and recovery. +By default, [Narayana Transactional driver](https://www.narayana.io/docs/api/com/arjuna/ats/jdbc/TransactionalDriver.html) +is used to enlist a relational database to a JTA transaction which provides a basic XAResource enlistment and recovery as +well as a simple pooling mechanism. + +> Be aware that Narayana Transactional driver automatically set transaction isolation level to `Connection.TRANSACTION_SERIALIZABLE`, +which might change default behaviour of the used database system! +For example, [Oracle Database](narayana-spring-boot-starter-it/src/test/resources/oracle-initscript.sql) ## Add pooling -If you need a more sophisticated connection management, we advice you to use [agroal-spring-boot-starter](https://agroal.github.io) +If you need a more sophisticated connection management, we advise you to use [agroal-spring-boot-starter](https://agroal.github.io) which provides connection pooling and many other features. To enable Agroal add the following dependency to your application configuration: ```xml @@ -73,16 +79,26 @@ All Agroal configuration properties described in its [documentation](https://agr This Narayana starter supports two ways to enlist a messaging broker to a JTA transaction: plain connection factory and MessagingHub pooled connection factory. -By default Narayana Connection Proxy around the JMS connection factory is used which provides a basic XAResource enlistment and recovery. +By default, [Narayana Connection Proxy](https://www.narayana.io/docs/api/org/jboss/narayana/jta/jms/ConnectionFactoryProxy.html) +around the JMS connection factory is used which provides a basic XAResource enlistment and recovery. ## Add pooling If you need a more sophisticated connection management, you can enable MessagingHub support which provides connection pooling -and many other features. To enable MessagingHub add the following property to you application configuration: +and many other features. To enable MessagingHub add the following dependency and property to you application configuration: +```xml + + org.messaginghub + pooled-jms + +``` ```properties narayana.messaginghub.enabled=true ``` -All MessagingHub configuration properties described in its [documentation](https://github.com/messaginghub/pooled-jms/blob/master/pooled-jms-docs/Configuration.md) are mapped with a prefix `narayana.messaginghub`. So for example if you'd like to set an max connections pool size to 10, you could do that by adding this entry to your application configuration: + +All MessagingHub configuration properties described in its [documentation](https://github.com/messaginghub/pooled-jms/blob/master/pooled-jms-docs/Configuration.md) +are mapped with a prefix `narayana.messaginghub`. So for example if you'd like to set a max connections pool size to 10, +you could do that by adding this entry to your application configuration: ```properties narayana.messaginghub.maxConnections=10 ```