Add spring-batch-notion
This commit is contained in:
Stefano Cordio
97
spring-batch-notion/README.md
Normal file
97
spring-batch-notion/README.md
Normal file
@@ -0,0 +1,97 @@
|
||||
# Spring Batch Notion [](https://mvnrepository.com/artifact/org.springframework.batch.extensions/spring-batch-notion) [](https://javadoc.io/doc/org.springframework.batch.extensions/spring-batch-notion)
|
||||
|
||||
[](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/
|
||||
Reference in New Issue
Block a user