|
| 1 | +# Apache Kafka Connect source and sink connectors for Azure Cosmos DB Java SDK for Java |
| 2 | +The Azure Cosmos DB connectors allow moving data between Azure Cosmos DB and Kafka. The Cosmos DB Sink connector writes data from a Kafka topic to a Cosmos DB container. The Cosmos DB Source connector writes changes from a Cosmos DB container to a Kafka topic. |
| 3 | + |
| 4 | +[Source code][kafka_source_code] | [Package (Maven)][cosmos_kafka_maven] | [Product documentation][cosmos_docs] |
| 5 | + |
| 6 | +## Getting started |
| 7 | +### Include the package |
| 8 | + |
| 9 | +[//]: # ({x-version-update-start;com.azure.kafka-connect:azure-cosmos-kafka-connect;current}) |
| 10 | +```xml |
| 11 | +<dependency> |
| 12 | + <groupId>com.azure.kafka.connect</groupId> |
| 13 | + <artifactId>azure-cosmos-kafka-connect</artifactId> |
| 14 | + <version>2.0.0-beta.1</version> |
| 15 | +</dependency> |
| 16 | +``` |
| 17 | +[//]: # ({x-version-update-end}) |
| 18 | + |
| 19 | +Refer to maven central for previous [releases][cosmos_kafka_maven] |
| 20 | + |
| 21 | +### Prerequisites |
| 22 | + |
| 23 | +- [Java Development Kit (JDK) with version 8 or above][jdk] |
| 24 | +- An active Azure account. If you don't have one, you can sign up for a [free account][azure_subscription]. Alternatively, you can use the [Azure Cosmos DB Emulator](https://docs.microsoft.com/azure/cosmos-db/local-emulator) for development and testing. As emulator HTTPS certificate is self-signed, you need to import its certificate to java trusted cert store as [explained here](https://docs.microsoft.com/azure/cosmos-db/local-emulator-export-ssl-certificates) |
| 25 | +- (Optional) SLF4J is a logging facade. |
| 26 | +- (Optional) [SLF4J binding](https://www.slf4j.org/manual.html) is used to associate a specific logging framework with SLF4J. |
| 27 | +- (Optional) [Maven][maven] |
| 28 | + |
| 29 | +SLF4J is only needed if you plan to use logging, please also download an SLF4J binding which will link the SLF4J API with the logging implementation of your choice. See the [SLF4J user manual](https://www.slf4j.org/manual.html) for more information. |
| 30 | + |
| 31 | +The SDK provides Reactor Core-based async APIs. You can read more about Reactor Core and [Flux/Mono types here](https://projectreactor.io/docs/core/release/api/) |
| 32 | + |
| 33 | +## Key concepts |
| 34 | + |
| 35 | +TBD |
| 36 | + |
| 37 | +## Examples |
| 38 | +TBD |
| 39 | + |
| 40 | +## Troubleshooting |
| 41 | + |
| 42 | +### General |
| 43 | + |
| 44 | +Azure Cosmos DB is a fast and flexible distributed database that scales seamlessly with guaranteed latency and throughput. |
| 45 | +You do not have to make major architecture changes or write complex code to scale your database with Azure Cosmos DB. |
| 46 | +Scaling up and down is as easy as making a single API call or SDK method call. |
| 47 | +However, because Azure Cosmos DB is accessed via network calls there are client-side optimizations you can make to achieve peak performance when using Azure Cosmos DB Java SDK v4. |
| 48 | + |
| 49 | +- [Performance][perf_guide] guide covers these client-side optimizations. |
| 50 | + |
| 51 | +- [Troubleshooting Guide][troubleshooting] covers common issues, workarounds, diagnostic steps, and tools when you use Azure Cosmos DB Java SDK v4 with Azure Cosmos DB SQL API accounts. |
| 52 | + |
| 53 | +## Next steps |
| 54 | + |
| 55 | +- Quick start of Cosmos DB core java sdk [quickstart][quickstart] - Building a java app to manage Cosmos DB SQL API data |
| 56 | +- [Read more about Azure Cosmos DB Service][cosmos_docs] |
| 57 | + |
| 58 | +## Contributing |
| 59 | + |
| 60 | +This project welcomes contributions and suggestions. Most contributions require you to agree to a |
| 61 | +[Contributor License Agreement (CLA)][cla] declaring that you have the right to, and actually do, grant us the rights |
| 62 | +to use your contribution. |
| 63 | + |
| 64 | +When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate |
| 65 | +the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to |
| 66 | +do this once across all repos using our CLA. |
| 67 | + |
| 68 | +This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For more information see the [Code of Conduct FAQ][coc_faq] |
| 69 | +or contact [[email protected]][coc_contact] with any additional questions or comments. |
| 70 | + |
| 71 | +<!-- LINKS --> |
| 72 | +[kafka_source_code]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/cosmos/azure-cosmos-kafka-connect/src |
| 73 | +[cosmos_introduction]: https://docs.microsoft.com/azure/cosmos-db/ |
| 74 | +[cosmos_docs]: https://docs.microsoft.com/azure/cosmos-db/introduction |
| 75 | +[jdk]: https://docs.microsoft.com/java/azure/jdk/ |
| 76 | +[maven]: https://maven.apache.org/ |
| 77 | +[cosmos_kafka_maven]: https://central.sonatype.com/artifact/com.azure.kafka.connect/azure-cosmos-kafka-connect |
| 78 | +[cla]: https://cla.microsoft.com |
| 79 | +[coc]: https://opensource.microsoft.com/codeofconduct/ |
| 80 | +[coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/ |
| 81 | +[coc_contact]: mailto:[email protected] |
| 82 | +[azure_subscription]: https://azure.microsoft.com/free/ |
| 83 | +[troubleshooting]: https://docs.microsoft.com/azure/cosmos-db/troubleshoot-java-sdk-v4-sql |
| 84 | +[perf_guide]: https://docs.microsoft.com/azure/cosmos-db/performance-tips-java-sdk-v4-sql?tabs=api-async |
| 85 | +[sql_api_query]: https://docs.microsoft.com/azure/cosmos-db/sql-api-sql-query |
| 86 | +[quickstart]: https://docs.microsoft.com/azure/cosmos-db/create-sql-api-java?tabs=sync |
| 87 | + |
| 88 | + |
0 commit comments