Skip to content

Commit a922018

Browse files
Jack12816Jack12816
committed
[Documentation] Updated examples and reworked some parts. General formating cleanup.
1 parent 152e34c commit a922018

File tree

4 files changed

+84
-53
lines changed

4 files changed

+84
-53
lines changed

‎docs/guide/00_intro.md

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,10 @@
11
# Greppy Framework - Documentation
22

3-
The Greppy Framework's documentation explains how to use and maintain the cluster and the application itself.
3+
The Greppy Framework's documentation explains how to use and
4+
maintain the cluster and the application itself.
45

5-
The lead developer and maintainer of this project is Hermann Mayer (<hermann.mayer92@gmail.com>).
6-
For feedback or suggestions compose an issue on [Github](https://github.com/Jack12816/greppy).
6+
The lead developer and maintainer of this project is Hermann
7+
Mayer (<hermann.mayer92@gmail.com>).
8+
For feedback or suggestions compose an issue on
9+
[Github](https://github.com/Jack12816/greppy).
710

‎docs/guide/10_structure.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
11
# Structure
22

3-
The structure results from an application's logical encapsulation of namespaces and responsibilities.
4-
A brief overview can be described as the following:
3+
The structure results from an application's logical encapsulation of
4+
namespaces and responsibilities. A brief overview can be described
5+
as the following:
6+
57
.
68
├── app
79
│ ├── config

‎docs/guide/11_cluster.md

Lines changed: 28 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -11,13 +11,17 @@
1111

1212
### Description
1313

14-
The server is the starting point of the whole application. Deriving from other languages and systems, such as Ruby or Java, it represents the application server.
15-
16-
The server implementation also represents the cluster master. It manages the whole IPC pool and starts and restarts the workers in case they crash. A crashing worker is called a worker crash.
17-
18-
The master takes care of an application's high availability to keep it operable even if the worker crash. To ensure that goal, the master's implementation is as easy and definitive as possible.
19-
20-
If the master crashes, the application's availability cannot be ensured anymore. This case is called a master crash.
14+
The server is the starting point of the whole application. Deriving
15+
from other languages and systems, such as Ruby or Java, it represents
16+
the application server. The server implementation also represents the
17+
cluster master. It manages the whole IPC pool and starts and restarts
18+
the workers in case they crash. A crashing worker is called a worker
19+
crash. The master takes care of an application's high availability
20+
to keep it operable even if the worker crash. To ensure that goal,
21+
the master's implementation is as easy and definitive as possible.
22+
23+
If the master crashes, the application's availability cannot be
24+
ensured anymore. This case is called a master crash.
2125

2226
## Worker
2327

@@ -33,14 +37,17 @@ If the master crashes, the application's availability cannot be ensured anymore.
3337

3438
The worker is started and managed by the cluster master.
3539

36-
After forking the worker process, the backend configuration is loaded and all connections for the specific modules are established.
37-
38-
Once completed, the Express application is initialized and middleware is loaded into the application's request stack. Subsequently, the specific modules are searched for controllers and integrated into the application.
39-
40-
Furthermore, the ``configure`` method is called to load worker specific middleware or to start other bootstrapping processes.
41-
42-
Finally, the HTTP server is provided with the configured Express application and starts listening to the configured TCP port.
43-
40+
After forking the worker process, the backend configuration is loaded
41+
and all connections for the specific modules are established.
42+
Once completed, the Express application is initialized and middleware
43+
is loaded into the application's request stack. Subsequently, the
44+
specific modules are searched for controllers and integrated into
45+
the application. Furthermore, the ``configure`` method is called
46+
to load worker specific middleware or to start other bootstrapping
47+
processes.
48+
49+
Finally, the HTTP server is provided with the configured Express
50+
application and starts listening to the configured TCP port.
4451
The application is ready by this point.
4552

4653
## Worker Context
@@ -52,7 +59,11 @@ The application is ready by this point.
5259

5360
### Description
5461

55-
The worker context is different from the generic worker as it provides the worker with additional information. Theoretically, the generic worker would suffice to run an application, it wouldn't describe an application specific profile, though.
62+
The worker context is different from the generic worker as it provides
63+
the worker with additional information. Theoretically, the generic worker
64+
would suffice to run an application, it wouldn't describe an application
65+
specific profile, though.
5666

57-
To add another worker to the project, only a new context is needed, even if it isn't specialised in anything.
67+
To add another worker to the project, only a new context is needed,
68+
even if it isn't specialised in anything.
5869

‎docs/guide/20_backend.md

Lines changed: 46 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -2,29 +2,40 @@
22

33
## Managing the backend with db-Store
44

5-
To manage the framework's backend connections, a special backend layer was implemented.
6-
7-
The db-Store now acts as the layer's head. It processes the backend configuration and intializes all backends with their corresponding connections. Furthermore, it provides the possibility to integrate different a different ORM for each backend.
8-
9-
db-Store works absolutely asynchronous, which results in the layer's high performance.
10-
11-
Additionally, db-Store includes and defines a set of methods for every backend interface. A purposeful and easy workflow is etablished using these methods. The current backend adapters are currently limited to MySQL, MongoDB, and Memcached.
12-
13-
Every adapter provides the possibility to use the backend's native implementation, making specialised accesses easy.
5+
To manage the framework's backend connections, a special backend
6+
layer was implemented. The db-Store now acts as the layer's head.
7+
It processes the backend configuration and intializes all backends
8+
with their corresponding connections. Furthermore, it provides the
9+
possibility to integrate different a different ORM for each backend.
10+
db-Store works absolutely asynchronous, which results in the layer's
11+
high performance. Additionally, db-Store includes and defines a set
12+
of methods for every backend interface. A purposeful and easy workflow
13+
is etablished using these methods. The current backend adapters are
14+
currently limited to MySQL, MongoDB, and Memcached.
15+
Every adapter provides the possibility to use the backend's
16+
native implementation, making specialised accesses easy.
1417

1518
## db-Store's methods
1619

17-
db-Store should be the first big initialisation as it is of vital importance for persisting data.
20+
db-Store should be the first big initialisation as it
21+
is of vital importance for persisting data.
22+
If the adapter's configuration fails, the worker has to
23+
be shut down by normal means. After shutting down the worker,
24+
the master tries to spawn a new worker to take the previous
25+
one's place which enables the worker to start a fresh
26+
backend connection.
1827

19-
If the adapter's configuration fails, the worker has to be shut down by normal means. After shutting down the worker, the master tries to spawn a new worker to take the previous one's place which enables the worker to start a fresh backend connection.
20-
21-
Unless interrupted manually, the server tries to spawn workers indefinitely until the designated amount of workers is reached. Database failures and other external failures can be bypassed by this measurement, without requiring manual interference.
28+
Unless interrupted manually, the server tries to spawn workers
29+
indefinitely until the designated amount of workers is reached.
30+
Database failures and other external failures can be bypassed by
31+
this measurement, without requiring manual interference.
2232

2333
## db-Store in action
2434

2535
### Configuration
2636

27-
db-Store can handle multiple backend connections by using a structure like these:
37+
db-Store can handle multiple backend connections by
38+
using a structure like these:
2839

2940
/**
3041
* Current Environment specific Database connections
@@ -49,30 +60,34 @@ db-Store can handle multiple backend connections by using a structure like these
4960

5061
### Initialisation
5162

52-
Inside the generic worker, you can use db-Store like this:
63+
The generic worker implementation will setup the db-Store automatically
64+
by your given configuration. So after booting the worker you can use all
65+
configured backend connections.
66+
67+
### Accessing a backend connection
5368

54-
// @TODO: Update example
55-
dbReg = require('../modules/default/worker/db/registry.js');
69+
The db-Store provides the method ``get()`` to get the backend connection.
70+
This is just a wrapper class around the real backend adapter.
5671

57-
dbReg.configure(/* { specific backends/connections config to load } */, function(err)
58-
{
59-
// Your further application here
60-
});
72+
var connection = greppy.db.get('mysql.demo');
6173

62-
### Accessing a backend connection
74+
#### Methods of a backend connection
6375

64-
The backend instance provides the method ``getConnection`` to get the instance's connection.
76+
Methods wrapped by the backend adapters are:
6577

66-
greppy.db.get('mysql.demo').instance.getConnection(function(err, con) {
67-
console.log(con);
68-
});
78+
constructor(name, backend, config)
79+
configure(callback)
80+
getORM(callback)
81+
close(callback)
6982

70-
### Methods
83+
#### Properties of a backend connection
7184

72-
Methods used by the backend are:
85+
A backend connection also ships with some public
86+
accessable properties:
7387

74-
configure();
75-
getORM();
76-
close();
88+
errors // All errors which came from the backend adapter
89+
instance // The plain backend connection instance
90+
name // Name of the connection
91+
config // Configuration of the connection
7792

7893
## Working with backends

0 commit comments

Comments
 (0)