Skip to content

Commit 8073ca4

Browse files
author
notefox
committed
updated Docuentation,
/maps download now only with .osm Files deleted /test
1 parent e161d83 commit 8073ca4

20 files changed

+1063
-110
lines changed

‎doc/Developer Starting Guide for the OHDM-Download-Service.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# Developer Starting Guide for the OHDM-Download-Service
2+
3+
### Introduction
4+
5+
Hi, my name is Note (Tino Geißler) and I'm one of the People who worked on this part of the OHDM Project for about one Semester now. I wasn't really the first one and I probably wont be the last (at least I hope so ^^).
6+
7+
(This Service was originally created [here](https://github.com/parafoxx/ohdm-maps) (in Python). My Job was, to rewrite it in Java and put it though further development)
8+
9+
I really had fun working on on this and I hope you will too. To make it easier getting into this Project, maybe answering some questions you maybe have and showing some tough processes I put into this, I wanted to write a **Starting Guide** for people which want to work further on this.
10+
11+
If you got any questions you want to have answered, as long as I'm still a Student at the HTW Berlin, my E-Mail is
12+
_[[email protected]](mailto:[email protected])_.
13+
14+
---
15+
16+
### What is this ?
17+
18+
To Start, let's answer the question : __What even is this?__
19+
20+
This Program is the "Server Part" of the Android App : [OHDM Offline Viewer](https://github.com/OpenHistoricalDataMap/OHDMOfflineViewer)
21+
22+
23+
24+
The 3 __Main__ Services are:
25+
26+
+ Receiving Requests from the App or a Website to "create" a Map of a specific size from a specific point in time
27+
+ Using the [OHDMConverter](https://github.com/OpenHistoricalDataMap/OSMImportUpdate) and [osmosis](https://wiki.openstreetmap.org/wiki/Osmosis) to "build" a map-File from the request, and...
28+
+ Distributing the map-File to the App or the Website
29+
30+
31+
32+
For these Services, I decided to use:
33+
34+
* [Spring Boot](https://spring.io/projects/spring-boot) (for "Request Handling" and "Status Distribution")
35+
* [Apache MINA](https://mina.apache.org/mina-project/) (SFTP for the Distribution of said map-files)
36+
* OHDMConverter and osmosis (for the "building" of the map file)
37+
* and Java as the Main Programming Language
38+
39+
40+
41+
The Program itself is "module based".
42+
*(Which means it's build out of specific Modules which where made to work independently from one another, so they can be restarted/changed/swapped/etc. without damaging the rest of the System)*
43+
44+
These Modules are:
45+
46+
+ [The Request Manager]()
47+
48+
+ Manager for the Query Requests, can start and stop ongoing "Requests".
49+
50+
+ manages the number of Requests, that are allowed to run at the same time and automatically starts new, if they are allowed
51+
52+
+ is it's own Thread
53+
54+
55+
56+
+ [The Web Service]() (Spring Boot)
57+
58+
+ just takes HTTP Requests and processes them
59+
60+
+ in the Main Class (Spring Class)
61+
62+
63+
64+
+ [The SFTP File Service]() (Apache MINA)
65+
66+
+ used to create an SFTP Server
67+
68+
+ is it's own Thread
69+
70+
71+
72+
+ [The ID Management "System"]()
73+
74+
+ Just saves/creates/deletes IDs
75+
76+
+ not a Thread
77+
78+
79+
80+
+ [The Query Requests]()
81+
82+
+ is an Object
83+
84+
+ specifically build for downloading, creating and converting map files from a Database
85+
86+
+ is it's own Thread
87+
88+
+ is/are managed by the Request Manager
89+
90+
91+
92+
+ [The "Static Variables Initializer"]()
93+
94+
+ Initializes Variables from a File
95+
96+
+ is used for initializing the entire System
97+
98+
+ not a Thread
99+
100+
101+
102+
+ [The Logger]()
103+
104+
+ A small Logger System with **re-usability** in mind
105+
106+
+ is it's own Thread
107+
108+
109+
110+
+ [The Controller Endpoint]()
111+
112+
+ Access-point for the Service Controller
113+
+ is it's own Thread
114+
115+
116+
117+
*__Authors Note__: I've tried to build every single Module with the Idea in mind, that you can just take one out and even run it Standalone. This didn't always work out, but with a little bit of tweaking, I bet these things can be reused anywhere. Feel free to try it out yourself.*
118+
119+

‎doc/IDSystemModule.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# ID System Module
2+
3+
Module that is a Management for IDs. It can create IDs and save them.
4+
The ID System is not a Thread.
5+
6+
## Variables
7+
8+
| Name | Type | Standard Value | Description | Authors Note |
9+
| --------------------------- | --------------------- | ---------------------------- | ---------------------------------- | -------------------------- |
10+
| TAG | String (static final) | "IDSystem" | Tag for the Logger | more on that in [Logger]() |
11+
| idCharacterAlphabet | String (static final) | "abcdefghijklmnopqrstuvwxyz" | Characters used in the IDs | |
12+
| idNumbersAlphabet | String (static final) | "1234567890" | Numbers used in the IDs | |
13+
| idSpecialCharactersAlphabet | String (static final) | "_-" | special Characters used in the IDs | |
14+
| idSize | int (static final) | 8 | allowed size of an ID | |
15+
| idSaveFile | File (static) | null | File where the IDs will be saved | |
16+
17+
---
18+
19+
## Constructor
20+
21+
No Constructor, since everything is static
22+
23+
---
24+
25+
## Public Methods
26+
27+
### Interface Methods :
28+
29+
| Name | Parameter list | return Value | Description | Authors Note |
30+
| ---------------------- | ----------------- | ------------ | ------------------------------------------------------------ | ------------ |
31+
| (static) setIDSaveFile | idSaveFile (File) | void | setting the ID Save File to read from or write to | |
32+
| (static) createNewID | empty | String | creates a new ID , saves it in the idSaveFile and returns it | |
33+
| (static) writeEntry | id (String) | boolean | appending a new id to the save file, if it doesn't already exist | |
34+
35+
### Getter and Setter
36+
37+
| Name | Parameter List | return Value | Description | Authors Note |
38+
| ------------------ | -------------- | ------------ | ----------------------------------------- | ------------ |
39+
| (static) getAllIDs | empty | String | returns all saved ids from the idSaveFile | |
40+
41+
---
42+
43+
## Private Methods
44+
45+
| Name | Parameter List | return Value | Description | Authors Note |
46+
| ------------------------ | ---------------------------------------------- | ------------ | ------------------------------------------------------------ | ------------ |
47+
| (static) idAlreadyExists | id (String) | boolean | checks the file if the ID already exists | |
48+
| (static) generateID | rng (Random), characters(String), length (int) | String | Generates a new ID with the given Randomizer, allowed Characters and length | |
49+
| (static) getAllIDs | empty | String | returns all saved ids from the idSaveFile | |
50+

‎doc/ModuleTemplate.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Name <interface>
2+
3+
Short Description
4+
5+
## Variables
6+
7+
| Name | Type | Standard Value | Description | Authors Note |
8+
| ---- | ---- | -------------- | ----------- | ------------ |
9+
| | | | | |
10+
11+
---
12+
13+
## Constructor
14+
15+
| Parameter List | Type | used for... | Authors Note |
16+
| -------------- | ---- | ----------- | ------------ |
17+
| | | | |
18+
19+
---
20+
21+
## The "run" Method
22+
23+
24+
25+
---
26+
27+
## Public Methods
28+
29+
### Interface Methods :
30+
31+
| Name | Parameter list | return Value | Description | Authors Note |
32+
| ---- | -------------- | ------------ | ----------- | ------------ |
33+
| | | | | |
34+
35+
### Getter and Setter
36+
37+
| Name | Parameter List | return Value | Description | Authors Note |
38+
| ---- | -------------- | ------------ | ----------- | ------------ |
39+
| | | | | |
40+
41+
---
42+
43+
## Private Methods
44+
45+
| Name | Parameter List | return Value | Description | Authors Note |
46+
| ---- | -------------- | ------------ | ----------- | ------------ |
47+
| | | | | |
48+

‎doc/SFTPFileService.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# SFTP File Service
2+
3+
The SFTP File server is used to provide the Android App a Way to download map files and gives the Controller access to the Service.
4+
The Service is not used for the Download over the official OHDM-Website.
5+
6+
Used Dependencies:
7+
8+
+ [Apache MINA](https://mina.apache.org/mina-project/) (SFTP for the Distribution of said map-files)
9+
10+
## Variables
11+
12+
| Name | Type | Standard Value | Description | Authors Note |
13+
| ------------------ | ---------------------------- | ----------------------------- | ------------------------------------------------------------ | ------------ |
14+
| sshServer | SshServer | null | since sftp is based on ssh , we're using an base ssh server | |
15+
| port | int | null (defined in Constructor) | the port, that will be used to access | |
16+
| standardUser | [SftpUser]() | null (defined in Constructor) | standard user for the access from the app (name and password defined in the init file) | |
17+
| controller | [SftpUser]() | null (defined in Constructor) | controller access for the controller (name and password constant) | |
18+
| sharePath | String | null (defined in Constructor) | path for the app access | |
19+
| msgPath | String | null (defined in Constructor) | path for the controller msg | |
20+
| isRunning | boolean | false | shows, if the SFTP Server Thread is running | |
21+
| keySaveFilePath | String (static) | null (defined in Constructor) | the path for the saveFile for the keyFile ( for more information, look up on how sftp works) | |
22+
| sftpCommandFactory | List<NamedFactory<Command>> | null (defined in set-up) | command factory for the sftp server | |
23+
| userAuthFactories | List<NamedFactory<UserAuth>> | null (defined in set-up) | User Authentication Factory for the ssh server | |
24+
| vfsf | VirtualFileSystemFactory | null (defined in set-up) | VirtualFileSystemFactory for the current access | |
25+
| namedFactoryList | List<NamedFactory<Command>> | null (defined in set-up) | namedFactoryList for the sshServer | |
26+
| TAG | String (static, final) | "SFTP-Service" | Tag for the Logger | |
27+
28+
---
29+
30+
## Constructor
31+
32+
| Parameter List | Type | used for... | Authors Note |
33+
| --------------- | ------ | --------------- | ------------ |
34+
| port | int | port | |
35+
| strUsername | String | standardUser | |
36+
| stdPasswd | String | standardUser | |
37+
| keySaveFilePath | String | keySaveFilePath | |
38+
| sharePath | String | sharePath | |
39+
| msgPath | String | msgPath | |
40+
41+
```java
42+
public SftpService(int port, String stdUsername, String stdPasswd, String keySaveFilePath, String sharePath, String msgPath) {
43+
SftpService.keySaveFilePath = keySaveFilePath;
44+
this.port = port;
45+
this.sharePath = sharePath;
46+
this.msgPath = msgPath;
47+
48+
// setting up the standard user, these are the credentials used by the Android app
49+
standardUser = new SftpUser(stdUsername, stdPasswd);
50+
controller = new SftpUser("controller", "eqpS23PTagZgHmJcFQMBLgJv");
51+
52+
}
53+
```
54+
55+
---
56+
57+
## The "run" Method
58+
59+
```java
60+
@Override
61+
public synchronized void run() {
62+
try {
63+
// setup for the sftp Server
64+
setup();
65+
} catch (IOException e) {
66+
e.printStackTrace();
67+
}
68+
// setting the status to "running"
69+
isRunning = true;
70+
try {
71+
wait();
72+
} catch (InterruptedException e) {
73+
Logger.instance.addLogEntry(LogType.INFO, TAG, "SftpService was interrupted adn needs to be restarted");
74+
}
75+
}
76+
```
77+
78+
---
79+
80+
## Public Methods
81+
82+
### Interface Methods :
83+
84+
| Name | Parameter list | return Value | Description | Authors Note |
85+
| ---------- | -------------- | ------------ | -------------------------- | ------------ |
86+
| stopThread | empty | void | method to stop the Service | |
87+
88+
### Getter and Setter
89+
90+
no getter/setter
91+
92+
---
93+
94+
## Private Methods
95+
96+
| Name | Parameter List | return Value | Description | Authors Note |
97+
| ----- | -------------- | ------------ | --------------------------------------- | ------------ |
98+
| setup | empty | void | Setup method for the ssh -> sftp server | |
99+

0 commit comments

Comments
 (0)