Skip to content

Commit e9318c5

Browse files
kevinten10kevinten10
committed
docs: refresh Java SDK guidance
1 parent 764d923 commit e9318c5

2 files changed

Lines changed: 196 additions & 389 deletions

File tree

‎README.md‎

Lines changed: 98 additions & 211 deletions
Original file line numberDiff line numberDiff line change
@@ -1,251 +1,138 @@
1-
![logo](./docs/logo.png)
1+
<p align="center">
2+
<img src="./docs/logo.png" alt="Capa" width="160">
3+
</p>
24

3-
# Capa(cloud application api): To be the high-level api layer for all application runtime.
5+
# Capa Java SDK
46

5-
Let the code achieve "write once, run anywhere".
7+
Capa is a rich-SDK implementation of Cloud Application APIs for Java. Applications program against vendor-neutral runtime interfaces while pluggable SPI modules connect those interfaces to concrete middleware or cloud services.
68

7-
With the help of the Capa project, your Java applications have the ability to run across clouds and hybrid clouds with small changes.
9+
[简体中文](README_ZH.md) · [Documentation](https://capa.rxcloud.group/) · [Issues](https://github.com/capa-cloud/capa-java/issues)
810

9-
[中文文档](./README_ZH.md)
11+
> **Project boundary:** this repository contains the Java SDK. The experimental Go sidecar runtime is maintained separately in [capa](https://github.com/capa-cloud/capa), and API contracts are defined in [cloud-runtimes-jvm](https://github.com/capa-cloud/cloud-runtimes-jvm).
1012
11-
[介绍文章](https://capa.rxcloud.group/blog/2022/01/18/capa-mecha-sdk-of-cloud-application-api/)
13+
## Requirements
1214

13-
## Motivation
15+
- Java 8 or 11
16+
- Maven 3.8.1 or later
17+
- A Capa SPI implementation for every capability used by the application
1418

15-
### Mecha architecture
19+
## Add the SDK
1620

17-
The Capa project is based on the design concept of the Mecha architecture and uses **rich SDK mode** to provide Multi-Runtime standard API.
18-
19-
You can simply understand the Capa project as the SDK implementation of [Dapr](https://github.com/dapr/dapr) / [Layotto](https://github.com/mosn/layotto) Sidecar mode projects.
20-
21-
To understand the design ideas of Mecha architecture, please read the following articles:
22-
23-
[死生之地不可不察：论API标准化对Dapr的重要性](https://www.infoq.cn/article/wjkNGoGaaHyKs7xIyTSB)
24-
25-
[MOSN子项目Layotto：开启服务网格+应用运行时新篇章](http://mosn.io/layotto/#/zh/blog/mosn-subproject-layotto-opening-a-new-chapter-in-service-grid-application-runtime/index)
26-
27-
### Sidecar or SDK
28-
29-
Based on the Mecha architecture concept, Multi-Runtime provides standard API functions in a Sidecar manner, which seems to be the most reasonable choice.
30-
31-
So why not use Dapr/Layotto and other projects directly, but choose to develop the Capa project of **Rich SDK Mode** instead.
32-
33-
Summary: _The Sidecar architecture represented by Dapr is the future, but it is difficult for many existing enterprises and systems to upgrade to the Sidecar architecture in one step. The rich SDK architecture will exist for a long time._
34-
35-
Extension: _Faced with the huge Java systems, the Capa project will use the rich SDK model to support the transition from the Java system to the Mecha architecture. After Dapr and other projects mature, they can also be seamlessly connected to the Sidecar architecture._
36-
37-
For specific discussions on this issue, please refer to:
38-
39-
[SDK模型的Dapr API](https://github.com/dapr/dapr/issues/3261)
40-
41-
[Dapr API的未来计划](https://github.com/dapr/dapr/issues/2817)
42-
43-
[Java SDK的设计讨论](https://github.com/mosn/layotto/issues/188)
44-
45-
## Feature
46-
47-
### API definition
48-
49-
Capa API design follow community standards, please refer to the API definitions of open source projects such as Dapr / Layotto.
50-
51-
The API definition is placed in the following independent warehouse, unbound from the Capa project, and hopes to develop into the community's API standard definition:
52-
53-
+ java: [cloud-runtimes-jvm](https://github.com/capa-cloud/cloud-runtimes-jvm)
54-
+ python(alpha): [cloud-runtimes-python](https://github.com/capa-cloud/cloud-runtimes-python)
55-
+ golang(alpha): [cloud-runtimes-golang](https://github.com/capa-cloud/cloud-runtimes-golang)
56-
57-
#### Why not use Dapr API directly?
58-
59-
Due to the current strong binding between Dapr API and Dapr project, we hope that this set of API can become the standard of the entire community, so Capa puts the API definition in an independent warehouse and keeps it synchronized with upstream community standards at all times.
60-
61-
We hope that Dapr can deploy its API independently, decouple it from the Dapr project, and become a standard for the entire community.
62-
63-
For the discussion of this item, please see:
64-
65-
[Future plans for dapr api](https://github.com/dapr/dapr/issues/2817)
66-
67-
### Capa features
68-
69-
Capa (Java SDK) is an SDK solution that implements Mecha architecture for Java applications. It currently supports features in the following areas:
70-
71-
+ Service Invocation (RPC)
72-
+ Configuration Centor (Configuration)
73-
+ Publish/Subscribe (Pub/Sub)
74-
+ State Management (State)
75-
+ Application Log/Metrics/Traces (Telemetry)
76-
+ Database (SQL) -alpha
77-
+ Schedule (Schedule) -alpha
78-
+ ...
79-
80-
## Design
81-
82-
### Capa design
83-
84-
Design idea: **Standard API + pluggable and replaceable SDK components** mode
85-
86-
In different distributed middleware fields, Capa provides a unified standard programming API without relying on specific middleware APIs. Therefore, the application does not need to rely on any specific middleware API when programming with Capa, but only needs to rely on Capa's standard programming API.
87-
88-
When deployed to different target environments, Capa will load different implementation classes of the standard API into the application. When calling a unified programming API, the underlying runtime will be adapted to different specific middleware SDK implementations.
89-
90-
The middleware team needs to develop the implementation classes of the standard API in the target environment for different target environments; and the application code can have a "write once, run anywhere" development experience.
91-
92-
### Architecture Overview
93-
94-
![Capa Architecture](./docs/capa-architecture.png)
95-
96-
Capa adopts a layered architecture design:
97-
- **Application Layer**: Uses unified Capa API for programming
98-
- **Capa SDK Layer**: Contains core SDK, components, SPI interface definitions
99-
- **SPI Implementation Layer**: Provides AWS, Alibaba Cloud, Dapr and other implementations
100-
- **Runtime Layer**: Connects to specific middleware services
101-
102-
### Write Once, Run Anywhere
103-
104-
![Write Once Run Anywhere](./docs/capa-write-once-run-anywhere.png)
105-
106-
With Capa's unified standard programming API, applications can run on different platforms (AWS, Alibaba Cloud, Kubernetes, Dapr, etc.) without modifying business code.
107-
108-
### Supported Features
109-
110-
![Capa Features](./docs/capa-features.png)
111-
112-
| Feature | Description | Status |
113-
|---------|-------------|--------|
114-
| RPC | Service Invocation | Stable |
115-
| Configuration | Dynamic Configuration | Stable |
116-
| Pub/Sub | Publish/Subscribe Messaging | Stable |
117-
| State | State Management | Stable |
118-
| Telemetry | Logs/Metrics/Traces | Stable |
119-
| Database | SQL Database | Alpha |
120-
| Schedule | Scheduled Tasks | Alpha |
121-
122-
### SDK design
123-
124-
The Capa module is divided into the following parts:
125-
126-
* sdk
127-
* sdk-component
128-
* sdk-spi
129-
* sdk-spi-demo/...
130-
131-
![capa-design](./docs/capa-design/capa-layer.PNG)
132-
133-
Application programming only needs to rely on the SDK, and use the unified programming API defined in the SDK module.
134-
135-
Before running, the specific SPI implementation package will be introduced as a specific implementation of the unified programming API.
136-
137-
## Usage
138-
139-
### Getting Started
140-
141-
#### Importing Capa's Java SDK
142-
143-
For a Maven project, add the following to your pom.xml file:
21+
Current repository version: `1.11.13.2.RELEASE`.
14422

14523
```xml
146-
147-
<project>
148-
...
149-
<dependencies>
150-
...
151-
<!-- Capa's core SDK with all features. -->
152-
<dependency>
153-
<groupId>group.rxcloud</groupId>
154-
<artifactId>capa-sdk</artifactId>
155-
<version>1.0.7.RELEASE</version>
156-
</dependency>
157-
...
158-
</dependencies>
159-
...
160-
</project>
24+
<dependency>
25+
<groupId>group.rxcloud</groupId>
26+
<artifactId>capa-sdk</artifactId>
27+
<version>1.11.13.2.RELEASE</version>
28+
</dependency>
16129
```
16230

163-
Sample implementation library:
31+
`capa-sdk` exposes the programming surface but does not select production infrastructure on its own. Add a compatible SPI implementation, such as an organization-specific adapter or one of the cloud integration repositories.
16432

165-
```xml
33+
For local exploration only, the repository publishes a demo SPI:
16634

167-
<project>
168-
...
169-
<dependencies>
170-
...
171-
<!-- Capa's core SDK with all features. -->
172-
<dependency>
173-
<groupId>group.rxcloud</groupId>
174-
<artifactId>capa-sdk-spi-demo</artifactId>
175-
<version>1.0.7.RELEASE</version>
176-
</dependency>
177-
...
178-
</dependencies>
179-
...
180-
</project>
35+
```xml
36+
<dependency>
37+
<groupId>group.rxcloud</groupId>
38+
<artifactId>capa-sdk-spi-demo</artifactId>
39+
<version>1.11.13.2.RELEASE</version>
40+
<scope>runtime</scope>
41+
</dependency>
18142
```
18243

183-
### Logging compatibility
184-
185-
The Spring Boot integration does not transitively select a logging implementation. Applications should provide the
186-
SLF4J provider they use, such as Logback or Log4j 2. Capa's Java 8 Logback adapters compile against SLF4J 2.0.17 and
187-
Logback 1.3.16; their logging dependencies remain optional so Spring Boot applications can keep their own managed
188-
logging stack.
189-
190-
### Running the examples
44+
The demo SPI is an example implementation, not a production runtime.
19145

192-
Try the following examples to learn more about Capa's Java SDK:
46+
## Capabilities
19347

194-
* [capa-demo](https://github.com/capa-cloud/capa-java/tree/master/sdk-spi-demo)
195-
* [capa-aws](https://github.com/capa-cloud/capa-java-aws)
196-
* [capa-alibaba](https://github.com/capa-cloud/capa-java-alibaba)
48+
The SDK and API modules cover these runtime domains:
19749

198-
### Low retrofit cost migration
50+
| Domain | Purpose | Maturity note |
51+
| --- | --- | --- |
52+
| RPC | Service invocation | API and component/SPI layers are present |
53+
| Configuration | Dynamic configuration stores | API and component/SPI layers are present |
54+
| Pub/Sub | Message publication and subscription | API and component/SPI layers are present |
55+
| State | Key-value state operations | API contracts are present; adapter support varies |
56+
| Telemetry | Logs, metrics, and trace context | Component/SPI support is present |
57+
| Database and schedule | Extended runtime APIs | Treat as alpha and verify the selected adapter |
19958

200-
If you want to use the native Capa API, your legacy system needs to face a large refactoring workload.
59+
An API contract being present does not guarantee that every SPI adapter implements every operation. Check the adapter repository and run integration tests against the target infrastructure before production use.
20160

202-
In order to make the migration low-cost, we can reuse the middleware API currently used.
61+
## Repository layout
20362

204-
By developing an adaptation layer project (providing the same annotation/interface call method), the implementation of the original middleware API is changed to Capa API.
205-
206-
In this way, the application only needs to change a few code (such as changing the path name of the annotation/interface) to migrate to the Capa architecture.
207-
208-
For discussion of this issue, please see:
63+
```text
64+
.
65+
├── sdk/ # Public Capa SDK
66+
├── sdk-component/ # Component discovery and shared implementations
67+
├── sdk-spi/ # SPI extension points
68+
├── sdk-spi-demo/ # Demo SPI implementation
69+
├── sdk-infrastructure/ # Runtime infrastructure and hooks
70+
├── sdk-springboot/ # Spring Boot integration
71+
├── examples/ # Example applications
72+
└── spec/ # Protocol definitions
73+
```
20974

210-
[Java sdk design 调研：能否复用业界已有的事实标准](https://github.com/mosn/layotto/issues/206)
75+
The design follows **standard APIs plus replaceable SDK components**:
21176

212-
[Capa API adapted to spring annotation.](https://github.com/reactivegroup/sigs/issues/16)
77+
<p align="center">
78+
<img src="./docs/capa-design/capa-layer.PNG" alt="Capa SDK layers" width="720">
79+
</p>
21380

214-
[遗留中间件SDK无感迁移到Capa.](https://github.com/reactivegroup/sigs/issues/18)
81+
## Build and verify
21582

216-
## Develop
83+
```bash
84+
git clone https://github.com/capa-cloud/capa-java.git
85+
cd capa-java
86+
mvn --batch-mode --no-transfer-progress --fail-fast clean verify \
87+
-Pjacoco,rat,checkstyle \
88+
-DskipTests=false \
89+
-Dcheckstyle.skip=false \
90+
-Drat.skip=false \
91+
-Dmaven.javadoc.skip=true \
92+
-Dgpg.skip=true
93+
```
21794

218-
#### Reactor API
95+
This is the same verification profile used by CI on Java 8 and Java 11.
21996

220-
Taking into account the asynchronous call mode and the use of non-blocking IO, we provide the Reactor programming model natively. You can also use the synchronous call function through its `block()` method.
97+
Runnable and configuration examples are available in [`examples/`](examples/) and [`sdk-spi-demo/`](sdk-spi-demo/). Sample component mappings live under each module's `src/main/resources/sample/` directory.
22198

222-
The Java SDK for Capa is built using [Project Reactor](https://projectreactor.io/). It provides an asynchronous API for
223-
Java. When consuming a result is consumed synchronously, as in the examples referenced above, the `block()` method is
224-
used.
99+
## Reactive API model
225100

226-
The code below does not make any API call, it simply returns
227-
the [Mono](https://projectreactor.io/docs/core/release/api/reactor/core/publisher/Mono.html) publisher object. Nothing
228-
happens until the application subscribes or blocks on the result:
101+
Capa uses [Project Reactor](https://github.com/reactor/reactor-core) for asynchronous operations. A returned [`Mono`](https://github.com/reactor/reactor-core/blob/main/docs/modules/ROOT/pages/coreFeatures/mono.adoc) remains lazy until it is subscribed to or blocked:
229102

230103
```java
231-
Mono<String> result=capaRpcClient.invokeMethod(SERVICE_APP_ID,"say","hello",HttpExtension.POST,null,TypeRef.STRING);
104+
Mono<String> result = capaRpcClient.invokeMethod(
105+
SERVICE_APP_ID,
106+
"say",
107+
"hello",
108+
HttpExtension.POST,
109+
null,
110+
TypeRef.STRING
111+
);
112+
113+
String response = result.block();
232114
```
233115

234-
To start execution and receive the result object synchronously, use `block()`. The code below shows how to execute the
235-
call and consume an empty response:
116+
Use non-blocking composition in reactive applications. Call `block()` only at an intentional synchronous boundary.
236117

237-
```java
238-
Mono<String> result=capaRpcClient.invokeMethod(SERVICE_APP_ID,"say","hello",HttpExtension.POST,null,TypeRef.STRING);
239-
String response=result.block();
240-
```
118+
## Design background
119+
120+
- [Dapr API future plans](https://github.com/dapr/dapr/issues/2817)
121+
- [Layotto Java SDK design discussion](https://github.com/mosn/layotto/issues/188)
122+
- [Adapting Capa APIs to Spring annotations](https://github.com/reactivegroup/sigs/issues/16)
123+
- [Migrating legacy middleware SDKs to Capa](https://github.com/reactivegroup/sigs/issues/18)
124+
- [Multi-Runtime 2022: open questions](https://zhuanlan.zhihu.com/p/435012312)
241125

242-
#### Exception handling
126+
## Contributing
243127

244-
Most exceptions thrown from the SDK are instances of `CapaException`. `CapaException` extends from `RuntimeException`,
245-
making it compatible with Project Reactor.
128+
1. Create a branch from `master`.
129+
2. Keep public API changes compatible or document the compatibility impact.
130+
3. Update examples whenever an SDK or SPI contract changes.
131+
4. Run the full verification command above.
132+
5. Open a pull request with the affected capability and adapter scope.
246133

247-
## Future
134+
Do not commit cloud credentials, private endpoints, or customer configuration in examples or test resources.
248135

249-
### Multi-Runtime
136+
## License
250137

251-
[Multi-Runtime 2022：待解决的问题](https://zhuanlan.zhihu.com/p/435012312?utm_source=wechat_session&utm_medium=social&utm_oi=618742049890111488&utm_content=group2_article&utm_campaign=shareopn)
138+
Apache License 2.0. See [LICENSE](LICENSE).

0 commit comments

Comments
 (0)