davsclaus commented on code in PR #27314:
URL: https://github.com/apache/camel/pull/27314#discussion_r4216654520
##########
components/camel-hibernate/src/main/docs/hibernate-component.adoc:
##########
@@ -0,0 +1,764 @@
+= Hibernate Component
+:doctitle: Hibernate
+:shortname: hibernate
+:artifactid: camel-hibernate
+:description: Camel Hibernate Component
+:since: 4.24
+:supportlevel: Preview
+:tabs-sync-option:
+:component-header: Both producer and consumer are supported
+
+*Since Camel {since}*
+
+*{component-header}*
+
+The Hibernate component provides integration with relational databases using
**Hibernate ORM 8**.
+
+The component uses Hibernate's native `SessionFactory`, `Session`,
`StatelessSession`, `SelectionQuery`, and `MutationQuery` APIs.
+
+It supports HQL selection and mutation queries, natural-id lookups, Hibernate
filters, read-only queries, streaming query results, stateless insert and
upsert operations, multi-tenancy, and competing consumers using `SKIP_LOCKED`.
+
+The component can either reuse an existing Hibernate `SessionFactory` or
bootstrap one using a configured `DataSource` and explicit entity classes.
+
+The component does not use Jakarta Persistence (JPA), `camel-jpa`, or Spring
`PlatformTransactionManager`.
+
+Maven users will need to add the following dependency to their `pom.xml`
+for this component:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.camel</groupId>
+ <artifactId>camel-hibernate</artifactId>
+ <version>x.x.x</version>
+ <!-- use the same version as your Camel core version -->
+</dependency>
+----
+
+== URI format
+
+=== hibernate:entityClassName
+
+Where `entityClassName` is the target entity class name or entity type name.
+
+// component options: START
+include::partial$component-configure-options.adoc[]
+include::partial$component-endpoint-options.adoc[]
+include::partial$component-endpoint-headers.adoc[]
+// component options: END
+
+== Usage
+
+=== SessionFactory configuration
+
+The component can use an existing Hibernate `SessionFactory` or create one
during startup.
+
+==== Using an existing SessionFactory
+
+An existing `SessionFactory` can be configured directly on the component:
+
+[source,java]
+----
+HibernateComponent component = new HibernateComponent();
+component.setSessionFactory(sessionFactory);
+
+context.addComponent("hibernate", component);
+----
+
+The component does not own an externally supplied `SessionFactory` and
therefore does not close it when the component stops.
+
+If no `SessionFactory` is explicitly configured, the component attempts to
reuse a `SessionFactory` available in the Camel registry.
+
+==== Bootstrapping a SessionFactory
+
+The component can bootstrap a `SessionFactory` using a `DataSource` and
explicit entity classes:
+
+[source,java]
+----
+HibernateComponent component = new HibernateComponent();
+component.setDataSource(dataSource);
+component.setEntityClasses(new Class[] {
+ MyEntity.class
+});
+component.setSchemaAction("update");
+
+context.addComponent("hibernate", component);
+----
+
+The `DataSource` can be supplied directly or as a Camel registry name.
+
+Supported values for `schemaAction` are:
+
+* `none`
+* `validate`
+* `update`
+* `create`
+
+When the component creates the `SessionFactory`, it owns the resulting
`SessionFactory` and closes it when the component stops.
+
+Hibernate determines the database dialect automatically; the component does
not require an explicit dialect configuration.
+
+[NOTE]
+====
+Entity package scanning is not currently provided. Use `entityClasses` to
explicitly register the entity classes used by the `SessionFactory`.
+====
+
+==== Hibernate properties
+
+Additional Hibernate configuration properties can be supplied through
`hibernateProperties`.
+
+[source,java]
+----
+component.setHibernateProperties(Map.of(
+ "hibernate.show_sql", true,
+ "hibernate.format_sql", true
+));
+----
+
+The supplied properties are passed directly to Hibernate during
`SessionFactory` bootstrap.
+
+=== Producer operations
+
+When acting as a producer, the endpoint performs exactly one configured
operation.
+
+The supported operations are:
+
+* `selectionQuery`
+* `mutationQuery`
+* `naturalIdParameters`
+* `statelessOperation`
+
+The endpoint validates this configuration during startup.
+
+==== Selection query
+
+Use `selectionQuery` to execute an HQL selection query using Hibernate's
`SelectionQuery` API.
+
+[source,java]
+----
+from("direct:findEntities")
+ .to("hibernate:com.example.MyEntity?selectionQuery=from MyEntity where
status = :status");
+----
+
+Query parameters are supplied through the `CamelHibernateParameters` message
header:
+
+[source,java]
+----
+exchange.getMessage().setHeader(
+ HibernateConstants.HIBERNATE_PARAMETERS,
+ Map.of("status", "ACTIVE"));
+----
+
+The query result is placed in the message body.
+
+==== Mutation query
+
+Use `mutationQuery` to execute an HQL mutation query using Hibernate's
`MutationQuery` API.
+
+[source,java]
+----
+from("direct:updateEntities")
+ .to("hibernate:com.example.MyEntity?mutationQuery=update MyEntity set
status = :status where status = :oldStatus");
+----
+
+Parameters are supplied through the `CamelHibernateParameters` header:
+
+[source,java]
+----
+exchange.getMessage().setHeader(
+ HibernateConstants.HIBERNATE_PARAMETERS,
+ Map.of(
+ "status", "INACTIVE",
+ "oldStatus", "EXPIRED"));
+----
+
+The mutation update count is placed in the message body.
+
+==== Natural-id lookup
+
+Hibernate entities that define a natural identifier can be looked up using
`naturalId.` URI parameters
+(`naturalIdParameters` in Java, including `#bean`).
+
+String values are evaluated with Simple, so the natural-id can come from the
message. Values can also be
+passed or overridden with the `CamelHibernateParameters` header.
+
+[NOTE]
+====
+Values configured through the `naturalId.` URI prefix are Strings. For
non-String natural-id types, such as `Long`, configure the values using Java or
`#bean` configuration so the appropriate Java type is preserved.
Review Comment:
The `#bean` advice does not work for `naturalId.` values:
`HibernateEndpoint.resolveFilterValue` resolves `#` references for `filter.`
values only, so `naturalId.code=#myCode` stays the String `#myCode` and is then
evaluated by Simple as that literal. Either resolve references for natural-id
values the same way as filters, or limit this note to Java configuration
(`setNaturalIdParameters(...)`).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
