spring-projects · fmbenhassine · Oct 28, 2024 · Oct 15, 2024
diff --git a/.github/workflows/spring-batch-notion.yml b/.github/workflows/spring-batch-notion.yml
@@ -0,0 +1,34 @@
+name: Spring Batch Notion
+
+on:
+  pull_request:
+    paths:
+      - 'spring-batch-notion/**'
+  push:
+    paths:
+      - 'spring-batch-notion/**'
+
+defaults:
+  run:
+    working-directory: spring-batch-notion
+
+env:
+  MAVEN_ARGS: -B -V -ntp -e -Djansi.passthrough=true -Dstyle.color=always
+
+jobs:
+
+  build:
+
+    name: Build
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Java
+        uses: actions/setup-java@v4
+        with:
+          java-version: '21'
+          distribution: 'temurin'
+          cache: maven
+      - name: Build with Maven
+        run: ./mvnw $MAVEN_ARGS verify javadoc:javadoc
diff --git a/README.md b/README.md
@@ -6,13 +6,14 @@ This project is part of the [Spring organization][] on GitHub.
 
 ## Available Modules
 
-| Module                     | Description                   | Lead                                                 | Version | CI build                                                                                                                                                                                                                                                            |
-|----------------------------|-------------------------------|------------------------------------------------------| ------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| spring-batch-excel         | Support for [Microsoft Excel] | [@mdeinum](https://github.com/mdeinum)               | 0.1.1 | [![Spring Batch Excel](https://github.com/spring-projects/spring-batch-extensions/actions/workflows/spring-batch-excel.yml/badge.svg)](https://github.com/spring-projects/spring-batch-extensions/actions/workflows/spring-batch-excel.yml)                         |
-| spring-batch-elasticsearch | Support for [Elasticsearch]   | [@parikshitdutta](https://github.com/parikshitdutta) | 0.1.0-SNAPSHOT | [![Spring Batch Elasticsearch](https://github.com/spring-projects/spring-batch-extensions/actions/workflows/spring-batch-elasticsearch.yml/badge.svg)](https://github.com/spring-projects/spring-batch-extensions/actions/workflows/spring-batch-elasticsearch.yml) |
-| spring-batch-bigquery      | Support for [Google BigQuery] | [@dgray16](https://github.com/dgray16)               | 0.1.0 | [![Spring Batch BigQuery](https://github.com/spring-projects/spring-batch-extensions/actions/workflows/spring-batch-bigquery.yml/badge.svg)](https://github.com/spring-projects/spring-batch-extensions/actions/workflows/spring-batch-bigquery.yml)                |
-| spring-batch-neo4j         | Support for [Neo4j]           | [@michael-simons](https://github.com/michael-simons) | 0.1.0 | [![Spring Batch Neo4j](https://github.com/spring-projects/spring-batch-extensions/actions/workflows/spring-batch-neo4j.yml/badge.svg)](https://github.com/spring-projects/spring-batch-extensions/actions/workflows/spring-batch-neo4j.yml)                         |
-| spring-batch-geode         | Support for [Apache Geode]    | TBA                                                  | 0.1.0-SNAPSHOT | [![Spring Batch Geode](https://github.com/spring-projects/spring-batch-extensions/actions/workflows/spring-batch-geode.yml/badge.svg)](https://github.com/spring-projects/spring-batch-extensions/actions/workflows/spring-batch-geode.yml)                         |
+| Module                                                             | Description                   | Lead                                                 | Version        | CI build                                                                                                                                                                                                                                                                       |
+|--------------------------------------------------------------------|-------------------------------|------------------------------------------------------|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [spring-batch-bigquery](spring-batch-bigquery/README.adoc)         | Support for [Google BigQuery] | [@dgray16](https://github.com/dgray16)               | 0.1.0          | [![Spring Batch BigQuery](https://github.com/spring-projects/spring-batch-extensions/actions/workflows/spring-batch-bigquery.yml/badge.svg)](https://github.com/spring-projects/spring-batch-extensions/actions/workflows/spring-batch-bigquery.yml)                           |
+| [spring-batch-elasticsearch](spring-batch-elasticsearch/README.md) | Support for [Elasticsearch]   | [@parikshitdutta](https://github.com/parikshitdutta) | 0.1.0-SNAPSHOT | [![Spring Batch Elasticsearch](https://github.com/spring-projects/spring-batch-extensions/actions/workflows/spring-batch-elasticsearch.yml/badge.svg)](https://github.com/spring-projects/spring-batch-extensions/actions/workflows/spring-batch-elasticsearch.yml)            |
+| [spring-batch-excel](spring-batch-excel/README.adoc)               | Support for [Microsoft Excel] | [@mdeinum](https://github.com/mdeinum)               | 0.1.1          | [![Spring Batch Excel](https://github.com/spring-projects/spring-batch-extensions/actions/workflows/spring-batch-excel.yml/badge.svg)](https://github.com/spring-projects/spring-batch-extensions/actions/workflows/spring-batch-excel.yml)                                    |
+| [spring-batch-geode](spring-batch-geode/README.adoc)               | Support for [Apache Geode]    | TBA                                                  | 0.1.0-SNAPSHOT | [![Spring Batch Geode](https://github.com/spring-projects/spring-batch-extensions/actions/workflows/spring-batch-geode.yml/badge.svg)](https://github.com/spring-projects/spring-batch-extensions/actions/workflows/spring-batch-geode.yml)                                    |
+| [spring-batch-neo4j](spring-batch-neo4j/README.md)                 | Support for [Neo4j]           | [@michael-simons](https://github.com/michael-simons) | 0.1.0          | [![Spring Batch Neo4j](https://github.com/spring-projects/spring-batch-extensions/actions/workflows/spring-batch-neo4j.yml/badge.svg)](https://github.com/spring-projects/spring-batch-extensions/actions/workflows/spring-batch-neo4j.yml)                                    |
+| [spring-batch-notion](spring-batch-notion/README.md)               | Support for [Notion]          | [@scordio](https://github.com/scordio)               | 0.1.0-SNAPSHOT | [![Spring Batch Notion](https://github.com/spring-projects/spring-batch-extensions/actions/workflows/spring-batch-notion.yml/badge.svg?branch=main)](https://github.com/spring-projects/spring-batch-extensions/actions/workflows/spring-batch-notion.yml?query=branch%3Amain) |
 
 ## Getting support
 
@@ -92,6 +93,7 @@ Follow the Spring Batch team members and contributors on Twitter:
 * [@rotnroll666](https://twitter.com/rotnroll666) - Michael Simons
 * [@meistermeier](https://twitter.com/meistermeier) - Gerrit Meier
 * [@truecoder](https://twitter.com/truecoder) - Parikshit Dutta
+* [@stefanocodes](https://twitter.com/stefanocodes) - Stefano Cordio
 
 ## License
 
@@ -100,23 +102,24 @@ noted differently for individual extension Modules, but this should be the rare
 
 **We look forward to your contributions!!**
 
-[Spring Batch Project]: https://projects.spring.io/spring-batch/
-[Spring organization]: https://github.com/spring-projects
-[Microsoft Excel]: https://www.microsoft.com/en-us/microsoft-365/excel
+[Apache Geode]: https://geode.apache.org
+[Apache License]: https://www.apache.org/licenses/LICENSE-2.0
+[Contributor Guidelines]: CONTRIBUTING.md
 [Elasticsearch]: https://www.elastic.co
+[Git]: https://help.github.com/set-up-git-redirect
+[GitHub Issue Tracker]: https://github.com/spring-projects/spring-batch-extensions/issues
 [Google BigQuery]: https://cloud.google.com/bigquery
+[Intellij IDEA]: https://www.jetbrains.com/idea/
+[Maven]: https://maven.apache.org
+[Microsoft Excel]: https://www.microsoft.com/en-us/microsoft-365/excel
 [Neo4j]: https://neo4j.com
-[Apache Geode]: https://geode.apache.org
-[spring-batch tag]: https://stackoverflow.com/questions/tagged/spring-batch
+[Notion]: https://notion.so/
+[Pull requests]: https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests
 [Spring Batch]: https://github.com/spring-projects/spring-batch
+[Spring Batch Project]: https://projects.spring.io/spring-batch/
 [Spring Boot]: https://github.com/spring-projects/spring-boot
-[Spring Cloud Task]: https://github.com/spring-cloud/spring-cloud-task
 [Spring Cloud Data Flow]: https://github.com/spring-cloud/spring-cloud-dataflow
-[GitHub Issue Tracker]: https://github.com/spring-projects/spring-batch-extensions/issues
-[Maven]: https://maven.apache.org
-[Git]: https://help.github.com/set-up-git-redirect
+[Spring Cloud Task]: https://github.com/spring-cloud/spring-cloud-task
+[Spring organization]: https://github.com/spring-projects
 [Spring Tool Suite]: https://spring.io/tools
-[Intellij IDEA]: https://www.jetbrains.com/idea/
-[Pull requests]: https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests
-[Contributor Guidelines]: CONTRIBUTING.md
-[Apache License]: https://www.apache.org/licenses/LICENSE-2.0
+[spring-batch tag]: https://stackoverflow.com/questions/tagged/spring-batch
@@ -0,0 +1,13 @@
+root = true
+
+# Unix-style newlines with a newline ending every file
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+
+# Maven POM code convention
+[pom.xml]
+indent_size = 2
+indent_style = space
+max_line_length = 205
@@ -0,0 +1,32 @@
+### Maven ###
+target/
+.mvn/wrapper/maven-wrapper.jar
+.flattened-pom.xml
+
+### STS ###
+.apt_generated
+.classpath
+.factorypath
+.project
+.settings
+.springBeans
+.sts4-cache
+
+### IntelliJ IDEA ###
+.idea
+*.iws
+*.iml
+*.ipr
+
+### NetBeans ###
+/nbproject/private/
+/nbbuild/
+/dist/
+/nbdist/
+/.nb-gradle/
+build/
+!**/src/main/**/build/
+!**/src/test/**/build/
+
+### VS Code ###
+.vscode/
@@ -0,0 +1,19 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+wrapperVersion=3.3.2
+distributionType=only-script
+distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.9/apache-maven-3.9.9-bin.zip
@@ -0,0 +1,97 @@
+# Spring Batch Notion [![Maven Central](https://img.shields.io/maven-central/v/org.springframework.batch.extensions/spring-batch-notion?label=Maven%20Central)](https://mvnrepository.com/artifact/org.springframework.batch.extensions/spring-batch-notion) [![javadoc](https://javadoc.io/badge2/org.springframework.batch.extensions/spring-batch-notion/javadoc.svg)](https://javadoc.io/doc/org.springframework.batch.extensions/spring-batch-notion)
+
+[![Spring Batch Notion](https://github.com/spring-projects/spring-batch-extensions/actions/workflows/spring-batch-notion.yml/badge.svg?branch=main)](https://github.com/spring-projects/spring-batch-extensions/actions/workflows/spring-batch-notion.yml?query=branch%3Amain)
+
+This project provides a [Spring Batch][] extension module that adds support for [Notion][].
+
+## Compatibility
+
+Spring Batch Notion is based on Spring Batch 5 and tested on Spring Boot 3, thus requiring at least Java 17.
+
+Compatibility is guaranteed only with the Spring Boot versions under [OSS support](https://spring.io/projects/spring-boot/#support). 
+
+## Getting Started
+
+### Maven
+
+```xml
+<dependency>
+  <groupId>org.springframework.batch.extensions</groupId>
+  <artifactId>spring-batch-notion</artifactId>
+  <version>${spring-batch-notion.version}</version>
+</dependency>
+```
+
+### Gradle
+
+```kotlin
+implementation("org.springframework.batch.extensions:spring-batch-notion:${springBatchNotionVersion}")
+```
+
+## NotionDatabaseItemReader
+
+The `NotionDatabaseItemReader` is a restartable `ItemReader` that reads entries from a [Notion Database] via a paging technique.
+
+A minimal configuration of the item reader is as follows:
+
+```java
+NotionDatabaseItemReader<Item> itemReader() {
+    NotionDatabaseItemReader<Item> reader = new NotionDatabaseItemReader<>();
+    reader.setToken(System.getenv("NOTION_TOKEN"));
+    reader.setDatabaseId("XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"); // UUID
+    reader.setPropertiesMapper(new CustomPropertyMapper());
+    return reader;
+}
+```
+
+The following configuration options are available:
+
+| Property         | Required | Default                     | Description                                                                                                               |
+|------------------|----------|-----------------------------|---------------------------------------------------------------------------------------------------------------------------|
+| `baseUrl`        | no       | `https://api.notion.com/v1` | Base URL of the Notion API. A custom value can be provided for testing purposes (e.g., the URL of a [WireMock][] server). |
+| `databaseId`     | yes      | -                           | UUID of the database to read from.                                                                                        |
+| `filter`         | no       | `null`                      | `Filter` condition to limit the returned items.                                                                           |
+| `pageSize`       | no       | `100`                       | Number of items to be read with each page. Must be greater than zero and less than or equal to 100.                       |
+| `propertyMapper` | yes      | -                           | The `PropertyMapper` responsible for mapping properties of a Notion item into a Java object.                              |
+| `sorts`          | no       | `null`                      | `Sort` conditions to order the returned items. Each condition is applied following the declaration order.                 |
+| `token`          | yes      | -                           | The Notion integration token.                                                                                             |
+
+In addition to the Notion-specific configuration, all the configuration options of the Spring Batch
+[`AbstractPaginatedDataItemReader`](https://docs.spring.io/spring-batch/docs/current/api/org/springframework/batch/item/data/AbstractPaginatedDataItemReader.html)
+are supported.
+
+### PropertyMapper
+
+The `NotionDatabaseItemReader` requires a `PropertyMapper` to map the properties of a Notion item into an object.
+
+Currently, only properties of type [Title](https://developers.notion.com/reference/property-object#title)
+and [Rich Text](https://developers.notion.com/reference/property-object#rich-text) are supported,
+and both are converted to strings.
+
+The following `PropertyMapper` implementations are provided out of the box.
+
+| Name                        | Description                                                                                                                                                                |
+|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `BeanWrapperPropertyMapper` | Supports JavaBeans. Requires a default constructor and expects the setter names to match the Notion item property names (case-insensitive).                                |
+| `ConstructorPropertyMapper` | Supports types with a constructor with arguments. Requires the constructor to be unique and its argument names to match the Notion item property names (case-insensitive). |
+| `RecordPropertyMapper`      | Supports Java records. It uses the canonical constructor and requires the component names to match the Notion item property names (case-insensitive).                      |
+
+All implementations above offer two constructors:
+* One accepting the `Class` instance of the type to be mapped
+* One without parameters, for cases where the type to be mapped can be inferred by the generic type of the variable or method enclosing the constructor declaration
+
+In case none of the provided implementations is suitable, a custom one can be provided.
+
+## NotionDatabaseItemWriter
+
+Currently not provided but will be added in the future.
+
+## License
+
+The Spring Batch Notion is released under version 2.0 of the [Apache License][].
+
+[Apache License]: https://www.apache.org/licenses/LICENSE-2.0
+[Notion]: https://notion.so/
+[Notion Database]: https://www.notion.so/help/category/databases
+[Spring Batch]: https://github.com/spring-projects/spring-batch
+[WireMock]: https://wiremock.org/