From 19efb1a258b59ef2b5293639ae737bb536193d1e Mon Sep 17 00:00:00 2001 From: Niels Meijer Date: Fri, 8 May 2026 14:34:24 +0200 Subject: [PATCH] Revise configuration documentation for clarity Updated configuration documentation to reflect changes in parameters and transaction handling. --- docs/manual/configuration/basics.md | 47 ++++++++++++++++------------- 1 file changed, 26 insertions(+), 21 deletions(-) diff --git a/docs/manual/configuration/basics.md b/docs/manual/configuration/basics.md index b7236b1..981b1fb 100644 --- a/docs/manual/configuration/basics.md +++ b/docs/manual/configuration/basics.md @@ -47,7 +47,7 @@ Listeners define how an adapter receives input. They are placed inside a ` ``` @@ -55,8 +55,8 @@ Listeners define how an adapter receives input. They are placed inside a `` block and one or more pipes. The `firstPipe` attribute specifies the entry point. Without `firstPipe`, pipes execute sequentially. @@ -75,7 +75,7 @@ Each exit has a `name`, a `state` (SUCCESS or ERROR), and an HTTP response `code ## Pipes -Pipes are the processing units inside a pipeline. Each pipe has a `name` attribute and one or more `` elements controlling flow. For a complete and up-to-date list of all available pipes and their attributes, see the [FF! Reference](https://reference.frankframework.org/#/components). +Pipes are the processing units inside a pipeline and have control over the processing flow. As such each pipe must have an unique name using the `name` attribute and one or more `` elements. For a complete and up-to-date list of all available pipes, possible sub-elements and their attributes, see the [FF! Reference](https://reference.frankframework.org/#/components). ### EchoPipe @@ -109,7 +109,7 @@ Validates the incoming XML message against an XSD schema. See the [XmlValidatorP ### SenderPipe -Wraps a sender to communicate with external systems (databases, services, etc.). See the [SenderPipe reference](https://reference.frankframework.org/#/Components/Pipes/SenderPipe) for all available attributes. +Wraps a sender to communicate with external systems (databases, services, etc.). Unlike a `Pipe` senders do not control the flow of execution and may not be placed directly inside a `Pipeline` but must be wrapped by either a `SenderPipe` any type of `IteratingPipe`. See the [SenderPipe reference](https://reference.frankframework.org/#/Components/Pipes/SenderPipe) for all available attributes. ```xml @@ -122,7 +122,7 @@ Wraps a sender to communicate with external systems (databases, services, etc.). - + ``` @@ -202,19 +202,17 @@ Executes SQL queries against a JDBC datasource. ``` - `query` — SQL statement with `?` positional parameters -- `datasourceName` — JNDI datasource name; `${instance.name.lc}` resolves to the lowercase instance name +- `datasourceName` — DataSource name; defaults to `${instance.name.lc}` which resolves to the lowercase instance name - `` — binds values via XPath expressions; `/element` selects elements, `/@attr` selects attributes #### Named Parameters -An alternative syntax uses named parameters with `useNamedParams="true"`: +An alternative syntax uses named parameters: ```xml + query="INSERT INTO booking VALUES(?{id}, ?{travelerId}, ?{price}, ?{fee})"> @@ -222,9 +220,13 @@ An alternative syntax uses named parameters with `useNamedParams="true"`: ``` +- The query-parameters in the SQL query may reference a specific parameter using `?{name}` +- You do not need to specify the `datasourceName` attribute if you wish to use the default. + ## Database Initialization with Liquibase Frank!Framework uses Liquibase for database schema management. Enable it by setting `jdbc.migrator.active=true`. +Each configuration may use their own changelog file. It is possible to change the name of the file and also to change the datasource it needs to apply the changelog to. ### DatabaseChangelog.xml @@ -259,8 +261,8 @@ Place this file in the configuration directory. It defines schema changes as ord Important rules: - Never modify existing changesets after they have been applied. Always add new changesets. -- The default datasource when using Frank!Runner is `jdbc/${instance.name.lc}` (e.g., `jdbc/frank2manual`). -- Use `DROP ALL OBJECTS` via JDBC Execute Query to reset an H2 database during development. +- The default datasource when using the Frank!Framework is `jdbc/${instance.name.lc}` (e.g., `jdbc/frank2manual`). +- Use `DROP ALL OBJECTS` via JDBC Execute Query to reset an H2 database during development, this however does not reapply the migration changelog! ## XML Validation with XSD @@ -319,8 +321,7 @@ Use `` with an XSLT stylesheet to transform XML messages: ``` ## Transactions - -Add `transactionAttribute` to the `` element to wrap all operations in a database transaction. +Transactions are configured in a `` or in a ``. You can control the use of transactions via the `transactionAttribute` on either of the elements to wrap all operations in a database transaction. If configured on the `Receiver` and not the `Pipeline`, the `Pipeline` will inherit the given transaction controlled by the `Receiver`. ```xml @@ -328,11 +329,15 @@ Add `transactionAttribute` to the `` element to wrap all operations in | Value | Behavior | |-------|----------| -| `RequiresNew` | Starts a new transaction for this pipeline | -| `Required` | Joins an existing transaction or creates a new one | -| `Mandatory` | Requires an existing transaction; fails if none exists | +| `Required` | Ensures there is a transaction; inherits or create a new one if none exists. | +| `Supports` | Support a current transaction; execute non-transactionally if none exists. | +| `Mandatory` | Requires a transaction is present; throws an exception if no current transaction exists. | +| `RequiresNew` | Always create a new transaction, suspending the current transaction if one exists. | +| `NotSupported` | Do not support a transaction; remove it when present and always execute non-transactional. | +| `Never` | Do not support a transaction; throw an exception if a current transaction exists. | -With transactions enabled, all database operations within the pipeline either succeed or roll back together (ACID semantics). +- With transactions enabled, all database operations within the pipeline either succeed or roll back together (ACID semantics). +- It is possible to have different transactions for data transport and data processing. ## File Layout @@ -344,8 +349,8 @@ configurations/ Configuration.xml DatabaseChangelog.xml StageSpecifics_LOC.properties - booking.xsd - booking2destinations.xsl + xml/xsd/booking.xsd + xml/xsl/booking2destinations.xsl webcontent/ index.html ```