Skip to content

Commit 9d8ae35

Browse files
sfxcodesfxcode
committed
rewrite docs part 1
1 parent eded527 commit 9d8ae35

30 files changed

+326
-147
lines changed

‎build.sbt‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ scalacOptions += "-deprecation"
1313

1414
parallelExecution in Test := false
1515

16-
lazy val root = (project in file("."))
16+
lazy val simple_mongo = (project in file("."))
1717
.enablePlugins(BuildInfoPlugin)
1818
.settings(
1919
buildInfoKeys := BuildInfoKey.ofN(name, version, scalaVersion, sbtVersion),
@@ -26,6 +26,9 @@ lazy val docs = (project in file("docs"))
2626
.enablePlugins(GhpagesPlugin)
2727
.settings(
2828
name := "simple mongo docs",
29+
scalaVersion := "2.13.2",
30+
resolvers += "SFXCode" at "https://dl.bintray.com/sfxcode/maven/",
31+
libraryDependencies += "com.sfxcode.nosql" %% "simple-mongo" % "1.9.3",
2932
publish / skip := true,
3033
ghpagesNoJekyll := true,
3134
git.remoteRepo := "[email protected]:sfxcode/simple-mongo.git",
@@ -34,11 +37,11 @@ lazy val docs = (project in file("docs"))
3437

3538
}
3639
)
40+
.dependsOn(simple_mongo)
3741

3842
buildInfoOptions += BuildInfoOption.BuildTime
3943

40-
resolvers +=
41-
"Sonatype OSS Snapshots" at "https://oss.sonatype.org/content/repositories/snapshots"
44+
resolvers += "Sonatype OSS Snapshots" at "https://oss.sonatype.org/content/repositories/snapshots"
4245

4346
// Test
4447

‎docs/src/main/paradox/dao/base.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ Sometimes we need Raw Support (DAO maps to Document).
4242
This is automatically included in the MongoDAO class.
4343
Simply call Raw on your DAO Object.
4444

45-
@@snip [RestaurantDatabase.scala](/src/test/scala/com/sfxcode/nosql/mongo/operation/AggregationSpec.scala) { #agg_execute }
45+
@@snip [Scala Sources](/src/test/scala/com/sfxcode/nosql/mongo/operation/AggregationSpec.scala) { #agg_execute }
4646

4747
## Base Functions
4848

‎docs/src/main/paradox/database_provider.md‎

Lines changed: 62 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -1,70 +1,40 @@
1-
# DatabaseProvider
1+
# Database
22

3-
DatabaseProvider is the central repository for MongoClient, databases, collections.
4-
It is referenced by the @ref:[MongoDAO](dao/index.md) Patttern.
3+
Database Connection can be done using MongConfig.
54

6-
## MongoConfig
5+
DatabaseProvider Instance contains setup for registries and databases.
76

8-
MongoConfig holds all the neded Data for creating a MongoClient.
9-
It is used for DatabaseProvider creation.
7+
Database provider will ues database by name from MongoConfig by default.
8+
Multiple databases access is supported on the same client is supported. For different MongoDBs you have to use different providers.
109

11-
| Key | Description | Default value |
12-
|:---------------------|:--------------------------|:-------------------|
13-
| database | default database to use | |
14-
| host | | 127.0.0.1 |
15-
| port | | 27017 |
16-
| applicationName | | simple-mongo-app |
17-
| userName | used for Authentification | |
18-
| password | used for Authentification | |
19-
| poolOptions | | MongoPoolOptions() |
20-
| compressors | List: zlib, snappy, zstd | List() |
21-
| customClientSettings | | None |
10+
## DatabaseProvider
11+
DatabaseProvider is the central repository for MongoClient, registries, databases and collections.
2212

13+
Every @ref:[MongoDAO](dao/index.md) / @ref:[GridFSDAO](gridfs/index.md) Instance needs this class.
2314

24-
## MongoPoolOptions
15+
@@snip [Mongo Conf](/docs/src/main/scala/DatabaseProviderDoc.scala) { #provider }
2516

26-
| Key | Default value |
27-
|:-------------------------------|:--------------|
28-
| maxConnectionIdleTime | 60 |
29-
| maxSize | 50 |
30-
| minSize | 0 |
31-
| DefaultMaintenanceInitialDelay | 0 |
3217

18+
## Create MongoConfig with application.conf
3319

34-
## Create MongoConfig with properties
20+
### With default path
3521

36-
Example:
22+
Default path in application.conf: mongo
3723

38-
```scala
39-
40-
val config = MongoConfig("my_database", host = "localhost",
41-
applicationName = "Awesome Application Name")
24+
@@snip [Mongo Conf](/docs/src/main/resources/docs.conf) { #sample_config }
4225

43-
```
26+
Scala Code Snippet
4427

45-
## Create MongoConfig with config
28+
@@snip [Mongo Conf](/docs/src/main/scala/DatabaseProviderDoc.scala) { #sample_config_from_path }
4629

47-
Create application.conf:
30+
### With custom path
4831

49-
```hocon
32+
@@snip [Mongo Conf](/docs/src/main/resources/docs.conf) { #sample_config_custom }
5033

51-
config.test.auth.mongo {
52-
database = "another_database"
53-
host = "localhost"
54-
port = 270007
55-
applicationName = "simple-mongo-config-test-with-auth"
56-
userName = "admin_user"
57-
password = "1234"
58-
pool {
59-
minSize = 5
60-
maxSize = 100
61-
}
34+
Scala Code Snippet
6235

63-
```
36+
@@snip [Mongo Conf](/docs/src/main/scala/DatabaseProviderDoc.scala) { #sample_config_from_custom_path }
6437

65-
```scala
66-
val config = MongoConfig.fromPath("config.test.auth.mongo")
67-
```
6838

6939
## Create MongoConfig with custom ClientSettings
7040

@@ -76,7 +46,50 @@ val config = MongoConfig("my_database", customClientSettings = Some(myClientSett
7646

7747
## Registries
7848

49+
@@@ note { title=ScalaDriverDocs }
50+
51+
Additional Info for [Registries](https://mongodb.github.io/mongo-java-driver/4.0/driver-scala/getting-started/quick-start-case-class/#configuring-case-classes)
52+
53+
@@@
54+
55+
### Create Case Classes
56+
57+
@@snip [Mongo Conf](/docs/src/main/scala/DatabaseProviderDoc.scala) { #provider_with_registry_classes }
58+
59+
### Create Registry
60+
61+
@@snip [Mongo Conf](/docs/src/main/scala/DatabaseProviderDoc.scala) { #provider_with_registry }
62+
63+
64+
## MongoConfig Options
65+
66+
MongoConfig holds all the neded Data for creating a MongoClient.
67+
68+
It is used for DatabaseProvider creation.
69+
70+
| Key | Description | Default value |
71+
|:---------------------|:--------------------------|:-------------------|
72+
| database | default database to use | |
73+
| host | | 127.0.0.1 |
74+
| port | | 27017 |
75+
| applicationName | | simple-mongo-app |
76+
| userName | used for Authentification | |
77+
| password | used for Authentification | |
78+
| poolOptions | | MongoPoolOptions() |
79+
| compressors | List: zlib, snappy, zstd | List() |
80+
| customClientSettings | | None |
81+
82+
83+
## MongoConfig Pool Options
84+
85+
| Key | Default value |
86+
|:-------------------------------|:--------------|
87+
| maxConnectionIdleTime | 60 |
88+
| maxSize | 50 |
89+
| minSize | 0 |
90+
| DefaultMaintenanceInitialDelay | 0 |
7991

92+
## Multiple databases access
8093

8194

8295

‎docs/src/main/paradox/features/aggregation.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,11 @@ MongoDB support an easy to use [Aggregation Handling](https://docs.mongodb.com/m
88

99
### Setup imports
1010

11-
@@snip [RestaurantDatabase.scala](/src/test/scala/com/sfxcode/nosql/mongo/operation/AggregationSpec.scala) { #agg_imports }
11+
@@snip [Scala Sources](/src/test/scala/com/sfxcode/nosql/mongo/operation/AggregationSpec.scala) { #agg_imports }
1212

1313
### Define stages
1414

15-
@@snip [RestaurantDatabase.scala](/src/test/scala/com/sfxcode/nosql/mongo/operation/AggregationSpec.scala) { #agg_stages }
15+
@@snip [Scala Sources](/src/test/scala/com/sfxcode/nosql/mongo/operation/AggregationSpec.scala) { #agg_stages }
1616

1717
### Execute Aggregation
1818

@@ -22,10 +22,10 @@ In most cases we have to use the RAW attribute, because the aggregation result n
2222

2323
@@@
2424

25-
@@snip [RestaurantDatabase.scala](/src/test/scala/com/sfxcode/nosql/mongo/operation/AggregationSpec.scala) { #agg_execute }
25+
@@snip [Scala Sources](/src/test/scala/com/sfxcode/nosql/mongo/operation/AggregationSpec.scala) { #agg_execute }
2626

2727
### Convert Result
2828

2929
For easy result handling, using the implicit Document to Map conversion can be useful.
3030

31-
@@snip [RestaurantDatabase.scala](/src/test/scala/com/sfxcode/nosql/mongo/operation/AggregationSpec.scala) { #agg_convert }
31+
@@snip [Scala Sources](/src/test/scala/com/sfxcode/nosql/mongo/operation/AggregationSpec.scala) { #agg_convert }

‎docs/src/main/paradox/features/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Features
1+
# Additional Features
22

33
* @ref:[Aggregation](aggregation.md)
44
* @ref:[Converter](converter.md)

‎docs/src/main/paradox/features/relationships.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,14 +37,14 @@ For relationship setup we create two Relationships in the UserDAO.
3737
* OneToOne loginRelation (LoginDAO, key is id in user collection)
3838
* OneToMany friendsRelation (FriendDAO, key is userId in friend collection)
3939

40-
@@snip [RestaurantDatabase.scala](/src/test/scala/com/sfxcode/nosql/mongo/relation/RelationDemoDatabase.scala) { #user_dao }
40+
@@snip [Scala Sources](/src/test/scala/com/sfxcode/nosql/mongo/relation/RelationDemoDatabase.scala) { #user_dao }
4141

4242

4343
We extend the User case class with the Relations trait and add relation specific functions.
4444

4545
* login (create an Option of Login)
4646
* friends (create a List of Friend)
4747

48-
@@snip [RestaurantDatabase.scala](/src/test/scala/com/sfxcode/nosql/mongo/relation/RelationDemoDatabase.scala) { #user_class }
48+
@@snip [Scala Sources](/src/test/scala/com/sfxcode/nosql/mongo/relation/RelationDemoDatabase.scala) { #user_class }
4949

5050

‎docs/src/main/paradox/index.md‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,38 +4,40 @@ A library for easy usage of the mongo-scala-driver.
44

55
Features:
66

7-
* Easy Config with @ref:[DatabaseProvider](database_provider.md)
8-
* Implement the [DAO](https://en.wikipedia.org/wiki/Data_access_object) Pattern for simple MongoDB database usage (@ref:[MongoDAO](dao/index.md))
9-
* Enhanced [BSON](http://mongodb.github.io/mongo-scala-driver/2.2/bson/) conversion support (@ref:[Converter](features/converter.md))
10-
11-
* [GridFS](https://docs.mongodb.com/manual/core/gridfs/) support (@ref:[GridFSDAO](gridfs/index.md))
7+
* Easy Database Config with @ref:[DatabaseProvider](database_provider.md) and MongoConfig
8+
* Implement the [DAO](https://en.wikipedia.org/wiki/Data_access_object) Pattern for simple MongoDB usage (@ref:[MongoDAO](dao/index.md))
9+
* [GridFS](https://mongodb.github.io/mongo-java-driver/4.0/driver-scala/tutorials/gridfs/) support (@ref:[GridFSDAO](gridfs/index.md))
10+
* [Reactive Streams](https://mongodb.github.io/mongo-java-driver/4.0/driver-scala/getting-started/quick-start-primer/) support (@ref:[Usage in simple-mongo](reactive_streams.md))
11+
* Enhanced [BSON](https://mongodb.github.io/mongo-java-driver/4.0/driver-scala/bson/) conversion support (@ref:[Bson Converter](features/converter.md))
1212
* @ref:[Relationships](features/relationships.md)
1313

1414
## Additional Documentation
1515

16-
* [mongo-scala-driver](http://mongodb.github.io/mongo-scala-driver/2.2/)
16+
* [mongo-scala-driver](https://mongodb.github.io/mongo-java-driver/4.0/driver-scala/)
1717
* [MongoDB](https://docs.mongodb.com/)
1818

19-
2019
## Dependency Setup
2120

2221
Support Scala 2.12 and Scala 2.13.
2322

2423
@@dependency[sbt,Maven,Gradle] {
2524
group="com.sfxcode.nosql"
26-
artifact="simple-mongo_2.12"
25+
artifact="simple-mongo_2.13"
2726
version="$project.version$"
2827
}
2928

3029
## Licence
3130

3231
[Apache 2](https://github.com/sfxcode/simple-mongo/blob/master/LICENSE)
3332

33+
34+
3435
@@@ index
3536

3637
- [Database Provider](database_provider.md)
3738
- [MongoDAO](dao/index.md)
3839
- [GridFSDAO](gridfs/index.md)
40+
- [reactive_streams](reactive_streams.md)
3941
- [Features](features/index.md)
4042
- [Changes ](changes.md)
4143

‎docs/src/main/paradox/reactive_streams.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Reactive Streams
2+
3+
* The MongoDB Scala driver is built upon [Reactive Streams](https://www.reactive-streams.org/)
4+
* simple-mongo wraps around the scala driver => Full support of Reactive Streams
5+
* For Blocking Results (implicit) conversion to Result Objects is provided
6+
* Conversion of Observable to Future is available
7+
8+
9+
@@@ note { title=ScalaDriverDocs }
10+
11+
Additional Info for [Reactive Streams JVM](https://github.com/reactive-streams/reactive-streams-jvm/)
12+
13+
Additional Info for [Mongo Scala Reactive Streams](https://mongodb.github.io/mongo-java-driver/4.0/driver-scala/getting-started/quick-start-primer/)
14+
15+
@@@
16+
17+
## Blocking Results
18+
19+
Conversion is provided in the DAO instances with four Helper function for Observable[C]:
20+
21+
| Funcion Name | Function Result | Sample | Sample Result |
22+
|:-------------|:----------------|:-----------------------------------------------|:---------------|
23+
| result | C | BookDAO.count().result() | Long |
24+
| results | Seq[C] | PersonDAO.findAggregated(aggregator).results() | Seq[Person] |
25+
| resultList | List[C] | UserDAO.find("name", "User").resultList() | List[User] |
26+
| resultOption | Option[C] | PersonDAO.find(Map("id" -> 42)).resultOption() | Option[Person] |
27+
28+
### Implicit Result Conversion (Blocking)
29+
30+
To use implicit result conversion, you have to import the simple mongo base package object.
31+
32+
```scala
33+
import com.sfxcode.nosql.mongo._
34+
```
35+
36+
After that, implicit conversion and other useful implicits (e.g. Map -> Bson) are available.
37+
38+
@@snip [Mongo Conf](/docs/src/main/scala/ReactiveStreamsDoc.scala) { #implicit_result_conversion }
39+
40+
## Future Results
41+
42+
DAO Instances support (implicit) conversion to Future,
43+
44+
@@snip [Mongo Conf](/docs/src/main/scala/ReactiveStreamsDoc.scala) { #as_future }

‎docs/src/main/resources/docs.conf‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
2+
// #sample_config
3+
mongo {
4+
database = "university"
5+
host = "localhost"
6+
port = 270007
7+
applicationName = "mongo.db.sample"
8+
userName = "standard_user"
9+
password = "change_me"
10+
pool {
11+
minSize = 5
12+
maxSize = 100
13+
}
14+
}
15+
// #sample_config
16+
17+
18+
// #sample_config_custom
19+
mongo.db.test {
20+
database = "unit_test"
21+
host = "localhost"
22+
port = 270007
23+
applicationName = "mongo.db.unit.test"
24+
userName = "unit_test"
25+
password = "change_me"
26+
}
27+
// #sample_config_custom
28+

0 commit comments

Comments
 (0)