Project

General

Profile

Wiki » History » Version 27

Tomek Dziemidowicz, 2019-07-04 08:53 PM

1 2 Tomek Dziemidowicz
h1. SQLite-sync documentation
2
3
*Owner* : AMPLIFIER sp. z o.o.
4
*Contact* : support (at) ampliapps.com
5
*website* : https://ampliapps.com
6
7 3 Tomek Dziemidowicz
{{>toc}}
8
9 9 Tomek Dziemidowicz
Welcome to the AMPLI-SYNC documentation!
10
We have language bindings in JavaScript, .NET C#, Java and Objective-C! 
11 1 Tomek Dziemidowicz
12 9 Tomek Dziemidowicz
h2. AMPLI-SYNC concept
13
14
h3. Solution diagram
15
16 8 Tomek Dziemidowicz
!{width:700px}SQLite-sync-structure.png!
17 1 Tomek Dziemidowicz
18 13 Tomek Dziemidowicz
* Devices communicate with server using HTTP/HTTPS protocol. 
19
* Proxy Load Balancer. If necessary, proxy can redirect request to another instance of SQLite-core.
20
* Authorization provider will generate token based on response from authorization provider.
21 9 Tomek Dziemidowicz
22
h3. Proxy Balancer flowchart
23
24
!{width:400px}SQLite-sync-proxy-balancer.png!
25
26
h3. Authorization Provider flowchart
27
28
!{width:350px}SQLite-sync-authentication-process.png!
29
30 2 Tomek Dziemidowicz
h2. REST API (server API)
31
32 10 Tomek Dziemidowicz
h3. Protocol version
33
34
This document describes integration with the REST API 3.x protocol.
35
36
h3. Service description
37
38
There are two stages to processing a request:
39
40 12 Tomek Dziemidowicz
* Device places an request.
41
* SQLite-sync server confirms the request has been processed successfully and sends confirmation with eventual conflict list that need to be resolved.
42 10 Tomek Dziemidowicz
43 11 Tomek Dziemidowicz
h3. Synchronization flowchart
44
45
!{width:200px;}Device-synchronization-diagram.png!
46 10 Tomek Dziemidowicz
47 23 Tomek Dziemidowicz
h3. Request URL format
48 22 Tomek Dziemidowicz
49
Sample REST API call:
50
<pre>
51
https://example.com/API3/__method___
52
</pre>
53
Explanation:
54
*https://example.com/* - adres of REST API service 
55
*API3* - version of synchronization
56
*__method___* - method/action
57
58 24 Tomek Dziemidowicz
h3. API methods
59
60 25 Tomek Dziemidowicz
h4. *Sync* - gets changes for table
61 26 Tomek Dziemidowicz
62 1 Tomek Dziemidowicz
*Method* : GET
63 26 Tomek Dziemidowicz
*Path* : /Sync/{subscriberUUID}/{tableName}
64 1 Tomek Dziemidowicz
*Produces* : TEXT_PLAIN
65 26 Tomek Dziemidowicz
*Description* : Get changed data. 
66
Params:
67 1 Tomek Dziemidowicz
*subscriberUUID* - identifier of subscriber. By default device unique ID is used. But we can place there any value (also #user.UUID)
68 26 Tomek Dziemidowicz
*tableName* - name of table from database (without schema)
69 1 Tomek Dziemidowicz
Response:
70 26 Tomek Dziemidowicz
<pre><code class="xml">
71
<?xml version="1.0" encoding="utf-8"?>
72
<records>
73
  <r a="1">
74
    <c>2</c>
75
    <c>Document</c>
76
    <c>75541</c>
77
    <c>2014-02-13 00:00:00</c>
78
    <c>665.000</c>
79
    <c>2c93d64e-cc72-11e3-87e0-f82fa8e587f9</c>
80
  </r>
81
  <r a="2">
82
    <c>4</c>
83
    <c>Document 4</c>
84
    <c>4879</c>
85
    <c>2014-04-23 13:44:48</c>
86
    <c>4875.000</c>
87
    <c>2c93d765-cc72-11e3-87e0-f82fa8e587f9</c>
88
  </r>
89
</records>
90
</code></pre>
91
<records> - section contains records 
92
<r a=”1”> - here starts record. 
93
</r> - here record ends
94
Attribute “a” (action type)
95
1 - new record
96
2 - update for record
97 1 Tomek Dziemidowicz
98 27 Tomek Dziemidowicz
Implementation examples: 
99 26 Tomek Dziemidowicz
* [[Objective-C]]
100
* [[.NET C#]]
101
* [[JAVA]]
102
* [[JavaScript]]
103 25 Tomek Dziemidowicz
104 2 Tomek Dziemidowicz
h2. Conflict Resolution
105
106
h2. Update procedure
107
108
h2. Data filtering
109
110 1 Tomek Dziemidowicz
h2. Installation
111 9 Tomek Dziemidowicz
112 18 Tomek Dziemidowicz
h3. Server Prerequisites
113
114
To make ampli-sync server work you need:
115
* Apache Tomcat 8.
116
* Java
117
* Linux/Windows environment. 
118
119 9 Tomek Dziemidowicz
h3. Manual
120
121 14 Tomek Dziemidowicz
Steps needed to install AMPLI-SYNC manually on Ubuntu.
122
123 15 Tomek Dziemidowicz
# Install Tomcat on Ubuntu:
124 14 Tomek Dziemidowicz
https://www.digitalocean.com/community/tutorials/how-to-install-apache-tomcat-8-on-ubuntu-16-04
125
# Create new user
126
<pre>
127
sudo adduser amplisync
128
</pre>
129
System will ask you for password for newly created user.
130
# Add user to group ‘tomcat’
131
<pre>
132
sudo usermod -a -G tomcat amplisync
133
</pre>
134
# Chang in web.xml path variable to 
135
<pre>
136
\home/sqlitesync/demo
137
</pre>
138
# Install new application in Tomcat. Start with switching to amplisync user.
139
<pre>
140
su amplisync
141
</pre>
142
# Create new folder /home/sqlitesync/demo
143 16 Tomek Dziemidowicz
# Upload new service amplisync-demo to Tomcat. You can do that using Tomcat application manager, or you can put WAR file in Tomcat webapps folder. Name of your WAR file is app name in Tomcat environment. Remember to not place spaces and special chars in name of your WAR file.
144 17 Tomek Dziemidowicz
# Restart Tomcat:
145 14 Tomek Dziemidowicz
<pre>
146
service tomcat restart
147
</pre>
148
Now you can access your installation using link:
149
<pre>
150
http://your_ip:8080/amplisync-app-name/API3
151
</pre>
152
# Setup permissions:
153
<pre>
154
chown -R sqlitesync:tomcat /home/amplisync/demo/
155
</pre>
156
157 9 Tomek Dziemidowicz
h3. Docker
158 2 Tomek Dziemidowicz
159 20 Tomek Dziemidowicz
h3. Configuring AMPLI-SYNC service
160 19 Tomek Dziemidowicz
161
First you need to adjust website configuration file (web.xml), then you need to change main configuration file (sync.properties).
162
*Service configuration (web.xml)*
163
Go to your_webapps_folder/SqliteSync/WEB-INF/web.xml and open for edit. Navigate to section:
164
<pre><code class="xml">
165
<env-entry>
166
<env-entry-name>working-dir</env-entry-name>
167
<env-entry-type>java.lang.String</env-entry-type>
168
<env-entry-value>/your/working/dir/sqlite-sync/</env-entry-value>
169
</env-entry>
170
</code></pre>
171
change env-entry-value key and point to working dir where SQLite-sync.com server will store log files, temporary files and configuration. Create manually a subfolder named config. Create a text file sync.properties in folder config. The path should look like this:
172
<pre>
173
\working_dir\config\sync.properties
174
</pre>
175
*IMPORTANT* Restart service after changing web.xml. Make sure that Tomcat has read/write access to working dir.
176
Sample configurations for MySQL server
177
<pre>
178
DB_ENGINE = mysql
179
DBURL = jdbc:mysql://server:3306/dbname?rewriteBatchedStatements=true
180
DBUSER = user
181
DBPASS = pass
182
DBDRIVER = com.mysql.cj.jdbc.Driver
183
DATE_FORMAT = yyyy-MM-dd HH:mm:ss
184
HISTORY_DAYS = 7
185
LOG_LEVEL = 4
186
</pre>
187
If you faced a timezone error after configuration in `sync.properties` add at the end of connection string:
188
<pre>
189
&useUnicode=true&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC
190
</pre>
191
*Keys explanation*
192 21 Tomek Dziemidowicz
*DB_ENGINE* - type of database engine. Available options:
193
* mysql
194
* mssql
195
* postgresql
196
* oracle
197
198 19 Tomek Dziemidowicz
*LOG_LEVEL* - defain details level for log
199
> 4: TRACE, DEBUG, INFO, WARN; (default)
200
> 3: DEBUG, INFO, WARN; 
201
> 2: INFO,WARN; 
202
> 1: WARN; 
203
> 0 - disable logs
204
*DATE_FORMAT* - set format of date 
205
default format: yyyy-MM-dd HH:mm:ss 
206
*HISTORY_DAYS* - How long files with sync data will be kept
207
default value: 7
208
When you use MySQL database DO NOT remove from the end of the connection string:
209
<pre>
210
?rewriteBatchedStatements=true
211 20 Tomek Dziemidowicz
</pre>
212 19 Tomek Dziemidowicz
213 2 Tomek Dziemidowicz
h2. Supported databases
214
215
h2. Samples