From c0274c815a2bb61bd391f54864bdee811450d91e Mon Sep 17 00:00:00 2001 From: Mark Paluch Date: Wed, 31 Jul 2024 09:54:29 +0200 Subject: [PATCH] Bundle Javadoc with Antora documentation site. Closes #1507 --- .gitignore | 1 - spring-data-cassandra-distribution/package.json | 10 ++++++++++ spring-data-cassandra-distribution/pom.xml | 2 +- src/main/antora/antora-playbook.yml | 8 +++----- src/main/antora/antora.yml | 5 +++++ src/main/antora/modules/ROOT/nav.adoc | 3 ++- .../modules/ROOT/pages/cassandra/cql-template.adoc | 13 +++++++------ .../antora/modules/ROOT/pages/cassandra/events.adoc | 6 +++--- .../ROOT/pages/cassandra/getting-started.adoc | 4 ++-- 9 files changed, 33 insertions(+), 19 deletions(-) create mode 100644 spring-data-cassandra-distribution/package.json diff --git a/.gitignore b/.gitignore index 79ee178f5..2a81d4ed0 100644 --- a/.gitignore +++ b/.gitignore @@ -18,6 +18,5 @@ work build/ node_modules node -package.json package-lock.json .mvn/.gradle-enterprise diff --git a/spring-data-cassandra-distribution/package.json b/spring-data-cassandra-distribution/package.json new file mode 100644 index 000000000..4689506b3 --- /dev/null +++ b/spring-data-cassandra-distribution/package.json @@ -0,0 +1,10 @@ +{ + "dependencies": { + "antora": "3.2.0-alpha.6", + "@antora/atlas-extension": "1.0.0-alpha.2", + "@antora/collector-extension": "1.0.0-alpha.7", + "@asciidoctor/tabs": "1.0.0-beta.6", + "@springio/antora-extensions": "1.13.0", + "@springio/asciidoctor-extensions": "1.0.0-alpha.11" + } +} diff --git a/spring-data-cassandra-distribution/pom.xml b/spring-data-cassandra-distribution/pom.xml index 892037172..b64d822bc 100644 --- a/spring-data-cassandra-distribution/pom.xml +++ b/spring-data-cassandra-distribution/pom.xml @@ -47,7 +47,7 @@ - io.spring.maven.antora + org.antora antora-maven-plugin diff --git a/src/main/antora/antora-playbook.yml b/src/main/antora/antora-playbook.yml index f20a13582..95482a719 100644 --- a/src/main/antora/antora-playbook.yml +++ b/src/main/antora/antora-playbook.yml @@ -3,8 +3,7 @@ # The purpose of this Antora playbook is to build the docs in the current branch. antora: extensions: - - '@antora/collector-extension' - - require: '@springio/antora-extensions/root-component-extension' + - require: '@springio/antora-extensions' root_component_name: 'data-cassandra' site: title: Spring Data Cassandra @@ -22,13 +21,12 @@ content: start_path: src/main/antora asciidoc: attributes: - page-pagination: '' hide-uri-scheme: '@' tabs-sync-option: '@' - chomp: 'all' extensions: - '@asciidoctor/tabs' - '@springio/asciidoctor-extensions' + - '@springio/asciidoctor-extensions/javadoc-extension' sourcemap: true urls: latest_version_segment: '' @@ -38,5 +36,5 @@ runtime: format: pretty ui: bundle: - url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.3.5/ui-bundle.zip + url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.4.16/ui-bundle.zip snapshot: true diff --git a/src/main/antora/antora.yml b/src/main/antora/antora.yml index 3687456a7..2a9a2b2bb 100644 --- a/src/main/antora/antora.yml +++ b/src/main/antora/antora.yml @@ -10,3 +10,8 @@ ext: local: true scan: dir: spring-data-cassandra-distribution/target/classes/ + - run: + command: ./mvnw package -Pdistribute + local: true + scan: + dir: target/antora diff --git a/src/main/antora/modules/ROOT/nav.adoc b/src/main/antora/modules/ROOT/nav.adoc index e3cd86e93..58b46a896 100644 --- a/src/main/antora/modules/ROOT/nav.adoc +++ b/src/main/antora/modules/ROOT/nav.adoc @@ -43,4 +43,5 @@ ** xref:kotlin/extensions.adoc[] ** xref:kotlin/coroutines.adoc[] -* https://github.com/spring-projects/spring-data-commons/wiki[Wiki] +* xref:attachment$api/java/index.html[Javadoc,role=link-external,window=_blank] +* https://github.com/spring-projects/spring-data-commons/wiki[Wiki,role=link-external,window=_blank] diff --git a/src/main/antora/modules/ROOT/pages/cassandra/cql-template.adoc b/src/main/antora/modules/ROOT/pages/cassandra/cql-template.adoc index 587020dca..fa7071207 100644 --- a/src/main/antora/modules/ROOT/pages/cassandra/cql-template.adoc +++ b/src/main/antora/modules/ROOT/pages/cassandra/cql-template.adoc @@ -1,21 +1,22 @@ [[cassandra.cql-template]] = CQL Template API -The `CqlTemplate` class (and its reactive variant `ReactiveCqlTemplate`) is the central class in the core CQL package. +The javadoc:org.springframework.data.cassandra.core.cql.CqlTemplate[] class (and its reactive variant javadoc:org.springframework.data.cassandra.core.cql.ReactiveCqlTemplate[]) is the central class in the core CQL package. It handles the creation and release of resources. It performs the basic tasks of the core CQL workflow, such as statement creation and execution, and leaves application code to provide CQL and extract results. The `CqlTemplate` class executes CQL queries and update statements, performs iteration over `ResultSet` instances and extraction of returned parameter values. It also catches CQL exceptions and translates them to the generic, more informative, exception hierarchy defined in the `org.springframework.dao` package. When you use the `CqlTemplate` for your code, you need only implement callback interfaces, which have a clearly defined contract. -Given a `Connection`, the `PreparedStatementCreator` callback interface creates a xref:cassandra/prepared-statements.adoc#cassandra.template.prepared-statements.cql[prepared statement] with the provided CQL and any necessary parameter arguments. -The `RowCallbackHandler` interface extracts values from each row of a `ResultSet`. +Given a `CqlSession`, the javadoc:org.springframework.data.cassandra.core.cql.PreparedStatementCreator[] callback interface creates a xref:cassandra/prepared-statements.adoc#cassandra.template.prepared-statements.cql[prepared statement] with the provided CQL and any necessary parameter arguments. +The javadoc:org.springframework.data.cassandra.core.cql.RowCallbackHandler[] interface extracts values from each row of a `ResultSet`. -The `CqlTemplate` can be used within a DAO implementation through direct instantiation with a `SessionFactory` reference or be configured in the Spring container and given to DAOs as a bean reference. `CqlTemplate` is a foundational building block for xref:cassandra/template.adoc[`CassandraTemplate`]. +The javadoc:org.springframework.data.cassandra.core.cql.CqlTemplate[] can be used within a DAO implementation through direct instantiation with a javadoc:org.springframework.data.cassandra.SessionFactory[] reference or be configured in the Spring container and given to DAOs as a bean reference. `CqlTemplate` is a foundational building block for xref:cassandra/template.adoc[`CassandraTemplate`]. All CQL issued by this class is logged at the `DEBUG` level under the category corresponding to the fully-qualified class name of the template instance (typically `CqlTemplate`, but it may be different if you use a custom subclass of the `CqlTemplate` class). -You can control fetch size, consistency level, and retry policy defaults by configuring these parameters on the CQL API instances: `CqlTemplate`, `AsyncCqlTemplate`, and `ReactiveCqlTemplate`. +You can control fetch size, consistency level, and retry policy defaults by configuring these parameters on the CQL API instances: +javadoc:org.springframework.data.cassandra.core.cql.CqlTemplate[], javadoc:org.springframework.data.cassandra.core.cql.AsyncCqlTemplate[], and javadoc:org.springframework.data.cassandra.core.cql.ReactiveCqlTemplate[]. Defaults apply if the particular query option is not set. NOTE: `CqlTemplate` comes in different execution model flavors. @@ -28,7 +29,7 @@ You can use `AsyncCqlTemplate` for asynchronous execution and synchronization wi This section provides some examples of the `CqlTemplate` class in action. These examples are not an exhaustive list of all functionality exposed by the `CqlTemplate`. -See the https://docs.spring.io/spring-data/cassandra/docs/{version}/api/[Javadoc] for that. +See the javadoc:org.springframework.data.cassandra.core.cql.CqlTemplate[Javadoc] for that. [[cassandra.cql-template.examples.query]] === Querying (SELECT) with `CqlTemplate` diff --git a/src/main/antora/modules/ROOT/pages/cassandra/events.adoc b/src/main/antora/modules/ROOT/pages/cassandra/events.adoc index 2f55ea504..d524b14cd 100644 --- a/src/main/antora/modules/ROOT/pages/cassandra/events.adoc +++ b/src/main/antora/modules/ROOT/pages/cassandra/events.adoc @@ -4,10 +4,10 @@ The Cassandra mapping framework has several built-in `org.springframework.context.ApplicationEvent` events that your application can respond to by registering special beans in the `ApplicationContext`. Being based on Spring's application context event infrastructure lets other products, such as Spring Integration, easily receive these events as they are a well known eventing mechanism in Spring-based applications. -To intercept an object before it goes into the database, you can register a subclass of `org.springframework.data.cassandra.core.mapping.event.AbstractCassandraEventListener` that overrides the `onBeforeSave(…)` method. +To intercept an object before it goes into the database, you can register a subclass of javadoc:org.springframework.data.cassandra.core.mapping.event.AbstractCassandraEventListener[] that overrides the `onBeforeSave(…)` method. When the event is dispatched, your listener is called and passed the domain object (which is a Java entity). Entity lifecycle events can be costly and you may notice a change in the performance profile when loading large result sets. -You can disable lifecycle events on the link:https://docs.spring.io/spring-data/cassandra/docs/{version}/api/org/springframework/data/cassandra/core/CassandraTemplate.html#setEntityLifecycleEventsEnabled(boolean)[Template API]. +You can disable lifecycle events on the javadoc:org.springframework.data.cassandra.core.CassandraTemplate#setEntityLifecycleEventsEnabled(boolean)[Template API]. The following example uses the `onBeforeSave` method: ==== @@ -19,7 +19,7 @@ include::example$mapping/BeforeSaveListener.java[tags=class] Declaring these beans in your Spring `ApplicationContext` will cause them to be invoked whenever the event is dispatched. -The `AbstractCassandraEventListener` has the following callback methods: +The javadoc:org.springframework.data.cassandra.core.mapping.event.AbstractCassandraEventListener[] has the following callback methods: * `onBeforeSave`: Called in `CassandraTemplate.insert(…)` and `.update(…)` operations before inserting or updating a row in the database but after creating the `Statement`. * `onAfterSave`: Called in `CassandraTemplate…insert(…)` and `.update(…)` operations after inserting or updating a row in the database. diff --git a/src/main/antora/modules/ROOT/pages/cassandra/getting-started.adoc b/src/main/antora/modules/ROOT/pages/cassandra/getting-started.adoc index b67401b4a..769ac2c89 100644 --- a/src/main/antora/modules/ROOT/pages/cassandra/getting-started.adoc +++ b/src/main/antora/modules/ROOT/pages/cassandra/getting-started.adoc @@ -97,7 +97,7 @@ include::example$ReactiveCassandraApplication.java[tags=file] Even in this simple example, there are a few notable things to point out: -* You can create an instance of `CassandraTemplate` (or `ReactiveCassandraTemplate` for reactive usage) with a Cassandra `CqlSession`. +* You can create an instance of javadoc:org.springframework.data.cassandra.core.CassandraTemplate[] (or javadoc:org.springframework.data.cassandra.core.ReactiveCassandraTemplate[] for reactive usage) with a Cassandra `CqlSession`. * You must annotate your POJO as a Cassandra `@Table` entity and also annotate the `@PrimaryKey`. Optionally, you can override these mapping names to match your Cassandra database table and column names. -* You can either use raw CQL or the DataStax `QueryBuilder` API to construct your queries. +* You can either use raw CQL or the Driver `QueryBuilder` API to construct your queries.