Skip to content

Commit 7870ca6

Browse files
sttksttk
authored
doc: modified the sample code in the Usage section of README.md (#57)
1 parent b2497e6 commit 7870ca6

1 file changed

Lines changed: 82 additions & 67 deletions

File tree

‎README.md‎

Lines changed: 82 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ The examples of declaring that repository and the dependency on this package in
5151

5252
### For Maven
5353

54-
```
54+
```xml
5555
<dependencies>
5656
<dependency>
5757
<groupId>io.github.sttk</groupId>
@@ -63,7 +63,7 @@ The examples of declaring that repository and the dependency on this package in
6363

6464
### For Gradle
6565

66-
```
66+
```groovy
6767
repositories {
6868
mavenCentral()
6969
}
@@ -74,103 +74,107 @@ dependencies {
7474

7575
## Usage
7676

77-
### 1. Implementing DataSrc and DataConn
78-
79-
First, you'll define `DataSrc` which manages connections to external data services and creates `DataConn`. Then, you'll define `DataConn` which represents a session-specific connection and implements transactional operations.
80-
81-
```java
82-
import com.github.sttk.errs.Err;
83-
import com.github.sttk.sabi.DataSrc;
84-
import com.github.sttk.sabi.DataConn;
85-
import com.github.sttk.sabi.AsyncGroup;
86-
87-
class FooDataSrc implements DataSrc {
88-
@Override public void setup(AsyncGroup ag) throws Err {}
89-
@Override public void close() {}
90-
@Override public DataConn createDataConn() throws Err { return new FooDataConn(); }
91-
}
92-
93-
class FooDataConn implements DataConn {
94-
@Override public void commit(AsyncGroup ag) throws Err {}
95-
@Override public void rollback(AsyncGroup ag) {}
96-
@Override public void close(AsyncGroup ag) {}
97-
}
98-
99-
class BarDataSrc implements DataSrc {
100-
@Override public void setup(AsyncGroup ag) throws Err {}
101-
@Override public void close() {}
102-
@Override public DataConn createDataConn() throws Err { return new BarDataConn(); }
103-
}
104-
105-
class BarDataConn implements DataConn {
106-
@Override public void commit(AsyncGroup ag) throws Err {}
107-
@Override public void rollback(AsyncGroup ag) {}
108-
@Override public void close(AsyncGroup ag) {}
109-
}
110-
```
111-
112-
### 2. Implementing logic functions and data interfaces
77+
### 1. Implementing a logic function and a data access interface
11378

114-
Define interfaces and functions that express your application logic. These interfaces are independent of specific data source implementations, improving testability.
79+
First, define a functional interface that represents your application logic, along with its dedicated data access interface. This interface is independent of specific data source implementations, improving testability.
11580

11681
```java
11782
import com.github.sttk.errs.Err;
118-
import com.github.sttk.sabi.Logic;
11983

12084
interface MyData {
12185
String getText() throws Err;
12286
void setText(String text) throws Err;
12387
}
88+
```
89+
```java
90+
import com.github.sttk.errs.Err;
12491

12592
class MyLogic implements Logic<MyData> {
126-
@Override public void run(MyData data) throws Err {
93+
@Override
94+
public void run(MyData data) throws Err {
12795
String text = data.getText();
12896
data.setText(text);
12997
}
13098
}
13199
```
132100

133-
### 3. Implementing DataAcc derived classes
101+
### 2. Implementing DataAcc derived interfaces
134102

135-
The `DataAcc` interface abstracts access to data connections. The methods defined here will be used to obtain data connections via `DataHub` and perform actual data operations.
103+
The `DataAcc` interface provides a simple mechanism to retrieve `DataConn` objects. However, it's the derived interfaces (like `GettingDataAcc` and `SettingDataAcc` in this example) that define the application-specific methods for accessing data. These methods then use `DataHub#getDataConn` to obtain the appropriate `DataConn` and perform the actual data operations.
104+
105+
```java
106+
interface AllLogicData extends MyData {}
107+
```
136108

137109
```java
138110
import com.github.sttk.errs.Err;
139111
import com.github.sttk.sabi.DataAcc;
140112

141-
interface GettingDataAcc extends DataAcc, MyData {
142-
@Override default String getText() throws Err {
143-
var conn = getDataConn("foo", FooDataConn.class);
144-
// ...
113+
interface GettingDataAcc extends DataAcc, AllLogicData {
114+
default String getText() throws Err {
145115
return "output text";
146116
}
147117
}
118+
```
119+
120+
```java
121+
import com.github.sttk.errs.Err;
122+
import com.github.sttk.sabi.DataAcc;
123+
import com.github.sttk.sabi_redis.RedisDataConn;
124+
import com.github.sttk.sabi_stdio.StdioDataConn; // This is a conceptual, non-existent DataConn.
125+
import java.io.InputStream;
126+
import java.io.PrintStream;
127+
128+
interface SettingDataAcc extends DataAcc, AllLogicData {
129+
default void setText(String text) throws Err {
130+
var redisDc = getDataConn("redis", RedisDataConn.class);
131+
var redisConn = redisDc.getConnection();
132+
var commands = redisConn.sync();
133+
try {
134+
commands.set("sample", text);
135+
} catch (Exception e) {
136+
throw new Err("fail to set value", e);
137+
}
148138

149-
interface SettingDataAcc extends DataAcc, MyData {
150-
@Override default void setText(String text) throws Err {
151-
var conn = getDataConn("bar", BarDataConn.class);
152-
// ...
139+
redisDc.addRollback(rConn -> {
140+
var cmd = rConn.sync();
141+
try {
142+
cmd.del("sample");
143+
} catch (Exception e) {
144+
throw new Err("fail to roll back", e);
145+
}
146+
});
147+
148+
var stdioDc = getDataConn("stdio", StdioDataConn.class);
149+
stdioDc.addPostCommit((InputStream in, PrintStream out, PrintStream err) -> {
150+
out.printf("%s", text);
151+
});
153152
}
154153
}
155154
```
156155

157-
### 4. Integrating data interfaces and DataAcc derived classes into `DataHub`
156+
### 3. Integrating data interfaces and DataAcc derived interfaces into DataHub
158157

159-
The `DataHub` is the central component that manages all `DataSrc` and `DataConn`, providing access to them for your application logic. By implementing the data interface (`MyData`) from step 2 and the `DataAcc` class from step 3 on `DataHub`, you integrate them.
158+
The `DataHub` is the central component that manages all `DataSrc` and `DataConn`,
159+
providing access to them for your application logic.
160+
By implementing the data interface (`MyData`) from step 1. and the `DataAcc` classes
161+
from step 2. on `DataHub`, you integrate them.
160162

161163
```java
162-
import com.github.sttk.errs.Err;
163164
import com.github.sttk.sabi.DataHub;
164165

165-
class MyDataHub extends DataHub implements GettingDataAcc, SettingDataAcc {}
166+
class MyDataHub extends DataHub implements GettingDataAcc, SettingDataAcc {
167+
public MyDataHub() {}
168+
}
166169
```
167170

168-
### 5. Using logic functions and `DataHub`
171+
### 4. Using logic functions and DataHub
169172

170-
Inside your init function, register your global `DataSrc`. Next, main function calls run function, and inside run function, setup the sabi framework. Then, create an instance of `DataHub` and register the necessary local `DataSrc` using the Uses method. Finally, use the txn method of `DataHub` to execute your defined application logic function (`MyLogic`) within a transaction. This automatically handles transaction commits and rollbacks.
173+
Inside your `static` block, register your global `DataSrc`. Next, `main` function calls `run` function, and inside `run` function, set up the sabi framework. Then, create an instance of `DataHub` and register the necessary local `DataSrc` using the `Sabi.uses` method. Finally, use the `DataHub#run` method or `DataHub#txn` method to execute your defined application logic function (`MyLogic`) without or within a transaction.
171174

172175
```java
173176
import com.github.sttk.errs.Err;
177+
import com.github.sttk.sabi.DataHub;
174178
import com.github.sttk.sabi.Sabi;
175179

176180
public class Main {
@@ -179,22 +183,33 @@ public class Main {
179183
Sabi.uses("foo", new FooDataSrc());
180184
}
181185

186+
static MyLogic myLogic = new MyLogic();
187+
182188
public static void main(String[] args) {
183-
// Set up the sabi framework.
184-
try (var ac = Sabi.setup()) {
189+
try {
190+
run();
191+
} catch (Exception e) {
192+
System.err.println(e.toString());
193+
System.exit(1);
194+
}
195+
}
185196

197+
static void run() throws Err {
198+
// Set up the sabi framework
199+
try (var ac = Sabi.setup()) {
200+
186201
// Creates a new instance of DataHub.
187-
var hub = new MyDataHub();
202+
try (var data = new MyDataHub()) {
188203

189-
// Register session-local DataSrc to DataHub.
190-
hub.uses("bar", new BarDataSrc());
204+
// Register session-local DataSrc with DataHub
205+
data.uses("bar", new BarDataSrc());
191206

192-
// Execute application logic within a transaction.
193-
// MyLogic performs data operations via DataHub.
194-
hub.txn(new MyLogic());
207+
// Execute application logic without a transaction control.
208+
data.run(myLogic);
195209

196-
} catch (Exception e) {
197-
System.exit(1);
210+
// If you need to execute logic within a transaction, use the `txn` method instead of `run`
211+
// data.txn(myLogic);
212+
}
198213
}
199214
}
200215
}

0 commit comments

Comments
 (0)