Developing lightweight computation at the DSG edge

README.md 4.5 KB
Newer Older
1
# AntidoteDB Java Tutorial
deepthidevaki's avatar
deepthidevaki committed
2

3
This is a sample application to demonstrate how to build applications that use [AntidoteDB][AntidoteDB-website] as backend database.
deepthidevaki's avatar
deepthidevaki committed
4

5
This tutorial is made for [Antidote Bookstore Tutorial](https://github.com/AntidoteDB/antidote-java-tutorial)
deepthidevaki's avatar
deepthidevaki committed
6

7
## What you need
deepthidevaki's avatar
deepthidevaki committed
8
9
* [Docker](https://docs.docker.com/engine/installation/)
* [docker-compose](https://docs.docker.com/compose/install/)
10
11
12
13
* An IDE for java development

## Clone source code
git clone https://github.com/AntidoteDB/antidote-java-tutorial
deepthidevaki's avatar
deepthidevaki committed
14

15
16
17
18
## Getting started
This repository is divided into two source directories:
* `setup`: scripts and docker files for running two instances of Antidote and two instances of the Java application
* `bookstore`: source of the tutorial application
deepthidevaki's avatar
deepthidevaki committed
19

20
21
| Note: make sure you have the software requirements listed above before following next steps. |
| --- |
deepthidevaki's avatar
deepthidevaki committed
22

23
24
25
26
27
28
29
30
### Step 1 : Starting antidote nodes
The following script starts two antidote docker containers and set up the inter-dc replication.
```bash
# in setup/
./start_antidote.sh
```

### Step 2 : Interactive Tutorial / Game
Dimitrios Vasilas's avatar
Dimitrios Vasilas committed
31
32
33
The interactive tutorial is an executable that presents a series of tasks/challenges. Each task has an outcome, SUCCESS or FAIL.
Solving a task allows you to try out the next task.
To try the interactive tutorial:
34
35

Open a new shell:
Dimitrios Vasilas's avatar
Dimitrios Vasilas committed
36
37
```bash
# in setup/
38
39
40
41
42
./tutorial_setup.sh
# build the tutorial
root@tutorial$ ./gradlew build
# run the tutorial executable
root@tutorial$ ./tutorial.sh
Dimitrios Vasilas's avatar
Dimitrios Vasilas committed
43
44
```

45
In case you want to reset your progress:
Dimitrios Vasilas's avatar
Dimitrios Vasilas committed
46
47
48
49
50
51
```bash
# in setup/
./stop_antidote.sh
./start_antidote.sh
```

52
53
| Note: Solving the interactive tutorial is equivalent to following steps 3, 4 and 5 bellow. Alternatively, you can skip this step and go directly to step 3.
| --- |
54
55
56
57
58
59
60


### Step 3 : Starting the application
Open two shells:
* In the first one, start the first app:
```bash
# in setup/
61
62
63
64
65
./app1_setup.sh
# build the app code
root@app1$ ./gradlew build
# and start the app
root@app1$ ./app1.sh
66
# then connect the app to Antidote instance 1:
67
bookstore@antidote1 > connect antidote1 8087
68
```
69

70
71
72
* We will do the same for the second app:
```bash
# in setup/
73
74
75
76
77
./app2_setup.sh
# build the app code
root@app2$ ./gradlew build
# and start the app
root@app2$ ./app2.sh
78
# then connect the app to Antidote instance 2:
79
bookstore@antidote2 > connect antidote2 8087
80
81
```

82
We have now deployed this configuration:
83
84
85
86
87
88

![Tutorial Figure](./doc/tutorial-figure.png "Tutorial figure")

### Step 4 : Try the following app commands
Some commands are already implemented in the app, lets try them:
~~~~
89
90
91
92
bookstore@antidote> inc testbucket mycounter
bookstore@antidote> getcounter testbucket mycounter
bookstore@antidote> additem testbucket myset newitem
bookstore@antidote> getset testbucket myset
93
94
95
96
~~~~

To stop the app:
~~~~
97
bookstore@antidote> quit
98
99
100
101
102
103
104
105
106
107
108
109
~~~~

You can also try to disconnect Antidote servers to simulate network partitions, commit some concurrent updates, then reconnect to merge CRDTs:
~~~~bash
# in setup/
./disconnect.sh #to disrupt communication between Antidote1 and Antidote2 nodes

#then update objects while disconnected

./connect.sh #connect Antidote nodes back
~~~~

110
To stop the two Antidote Nodes:
111
112
113
114
115
116
117
118
119
120
121
```bash
# in setup/
./stop_antidote.sh
```

### Step 5 : Hands On!!!
We now want to build our Bookstore app. The provided sources are divided into 3 files (located in bookstore/src/main/):
* `BookStore.java`: this file contains the command interface and the starting point of the app.
* `DemoCommandsExecutor.java`: this file contains the implementation of the demo commands we have seen in the previous Step. You can use them as examples to implement your own commands.
* `BookCommands.java`: Here is the file where you need to implement Bookstore commands, fill in the methods to add necessary.

122
123
124
125
126
127
128
129
130
131
132
The main method is located at bookstore/src/main/java/BookStore.java.

To re-build the app after modifying the source code:
```bash
some_docker_container$ ./gradlew build
```
where `some_docker_container` may be:
* `root@app1` or
* `root@app2` or
* `root@tutorial`

133
134
135
136
137
138
139
140
141
142
143
### Resources:
Some useful references:
* [Antidote API Javadoc](https://www.javadoc.io/doc/eu.antidotedb/antidote-java-client/0.3.1)
* [AntidoteDB source code](https://github.com/AntidoteDB/antidote)
* [AntidoteDB Documentation](https://antidotedb.gitbook.io/documentation/)
* [Antidote Docker reference](https://github.com/AntidoteDB/docker-antidote/blob/master/README.md)

## License
View [license information](https://github.com/AntidoteDB/antidote/blob/master/LICENSE) for the software contained in this image.

[AntidoteDB-website]: https://www.antidotedb.eu/