Skip to content

Commit

Permalink
docs: changes for new usage
Browse files Browse the repository at this point in the history
  • Loading branch information
QuadStingray committed Feb 3, 2025
1 parent 60e1350 commit 382eb35
Show file tree
Hide file tree
Showing 22 changed files with 130 additions and 145 deletions.
26 changes: 9 additions & 17 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,7 @@
A library for easy usage of the mongo-scala-driver (5.1.xa). Full MongoDB Functionality in Scala with a few lines of code.

## MongoDB Support

Support MongoDB 3.6 to 7.0.x.

We currently testing with '4.4', '5.0', '6.0', '7.0' and '8.0'.

## Features

Expand Down Expand Up @@ -46,7 +44,7 @@ Add following lines to your build.sbt (replace x.x with the actual Version)

```
libraryDependencies += "dev.mongocamp" %% "mongodb-driver" % "2.x.x"
libraryDependencies += "dev.mongocamp" %% "mongodb-driver" % "3.x.x"
```

Expand All @@ -61,6 +59,8 @@ import dev.mongocamp.driver.mongodb.database.DatabaseProvider
import org.bson.codecs.configuration.CodecRegistries._
import org.mongodb.scala.bson.ObjectId
import org.mongodb.scala.bson.codecs.Macros._
import dev.mongocamp.driver.mongodb.json._
import io.circe.generic.auto._

/**
* import mongodb restaurants sample data
Expand All @@ -71,12 +71,9 @@ object RestaurantDatabase {

case class Grade(date: Date, grade: String, score: Int)

case class Restaurant(restaurant_id: String, name: String, borough: String, cuisine: String,
grades: List[Grade], address: Address, _id: ObjectId = new ObjectId())

private val registry = fromProviders(classOf[Restaurant], classOf[Address], classOf[Grade])
case class Restaurant(restaurant_id: String, name: String, borough: String, cuisine: String, grades: List[Grade], address: Address, _id: ObjectId = new ObjectId())

val provider = DatabaseProvider("test", registry)
val provider = DatabaseProvider.fromPath("dev.mongocamp")

object RestaurantDAO extends MongoDAO[Restaurant](provider, "restaurants")

Expand All @@ -88,7 +85,6 @@ object RestaurantDatabase {
Import the database object and execute some find and CRUD functions on the DAO object ...

```scala

import dev.mongocamp.driver.mongodb.demo.restaurant.RestaurantDemoDatabase._
import dev.mongocamp.driver.mongodb._

Expand All @@ -97,17 +93,14 @@ trait RestaurantDemoDatabaseFunctions {
/**
* single result with implicit conversion to Entity Option
*/
def findRestaurantByName(name: String): Option[Restaurant] =
RestaurantDAO.find("name", name)
def findRestaurantByName(name: String): Option[Restaurant] = RestaurantDAO.find("name", name)

def restaurantsSize: Long = RestaurantDAO.count()

/**
* result with implicit conversion to List of Entities
*/
def findAllRestaurants(filterValues: Map[String, Any] = Map()): List[Restaurant] =
RestaurantDAO.find(filterValues)

def findAllRestaurants(filterValues: Map[String, Any] = Map()): List[Restaurant] = RestaurantDAO.find(filterValues)
```


Expand Down Expand Up @@ -137,7 +130,6 @@ Use the mongodb functions in your app ...
Write some spec tests ...

```scala

import dev.mongocamp.driver.mongodb.demo.restaurant.RestaurantDemoDatabase._
import org.specs2.mutable.Specification

Expand All @@ -160,7 +152,7 @@ class RestaurantDemoSpec extends Specification with RestaurantDemoDatabaseFuncti
## Run Tests
```shell
docker run -d --publish 27017:27017 --name mongodb mongocamp/mongodb:latest;
sbt test;
sbt +test;
docker rm -f mongodb;
```

Expand Down
8 changes: 4 additions & 4 deletions docs/documentation/collection/aggregation.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,10 @@ MongoDB support an easy to use [Aggregation Handling](https://docs.mongodb.com/m
## Demo

### Setup imports
<<< @/../src/test/scala/dev/mongocamp/driver/mongodb/operation/AggregationSpec.scala#agg_imports
<<< @/../src/test/scala/dev/mongocamp/driver/mongodb/operation/AggregationSuite.scala#agg_imports

### Define stages
<<< @/../src/test/scala/dev/mongocamp/driver/mongodb/operation/AggregationSpec.scala#agg_stages
<<< @/../src/test/scala/dev/mongocamp/driver/mongodb/operation/AggregationSuite.scala#agg_stages

### Execute Aggregation

Expand All @@ -19,10 +19,10 @@ MongoDB support an easy to use [Aggregation Handling](https://docs.mongodb.com/m
:::


<<< @/../src/test/scala/dev/mongocamp/driver/mongodb/operation/AggregationSpec.scala#agg_execute
<<< @/../src/test/scala/dev/mongocamp/driver/mongodb/operation/AggregationSuite.scala#agg_execute

### Convert Result

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

<<< @/../src/test/scala/dev/mongocamp/driver/mongodb/operation/AggregationSpec.scala#agg_convert
<<< @/../src/test/scala/dev/mongocamp/driver/mongodb/operation/AggregationSuite.scala#agg_convert
4 changes: 2 additions & 2 deletions docs/documentation/collection/analyse-schema.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ The driver supports an automated detection of the schema of an existing collecti
### Schema Analysis
Analyse a collection to detect the values for each field and the percentage distribution of the types.

<<< @/../src/test/scala/dev/mongocamp/driver/mongodb/schema/SchemaSpec.scala#schema-analysis
<<< @/../src/test/scala/dev/mongocamp/driver/mongodb/schema/SchemaSuite.scala#schema-analysis

### Detect Schema
The Schema Detector can be used to detect the schema of a collection and is based on [Schema Anaysis](analyse-schema.md#schema-analysis). The schema is used to detect the types of the columns and generate a [JSON Schema](https://json-schema.org) for the collection. In case of multiple types of a field the Generation of the JSON Schema use the type with the most elements.
Expand All @@ -15,4 +15,4 @@ The Schema Detector can be used to detect the schema of a collection and is base
The [JSON Schema](https://json-schema.org) format can be use to validate or generate data, as well to secure your [Mongo Collection](https://www.mongodb.com/docs/manual/core/schema-validation/).
:::

<<< @/../src/test/scala/dev/mongocamp/driver/mongodb/schema/SchemaSpec.scala#schema-explorer
<<< @/../src/test/scala/dev/mongocamp/driver/mongodb/schema/SchemaSuite.scala#schema-explorer
8 changes: 4 additions & 4 deletions docs/documentation/collection/pagination.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,16 +8,16 @@ In many cases you want to have the possibility to paginate over the response of
The Pagination over an aggregation pipeline supports only the response of `Document`, also if you use an case class MongoDAO you will got an `Document` back.
:::

<<< @/../src/test/scala/dev/mongocamp/driver/mongodb/pagination/PaginationAggregationSpec.scala#aggregation-pagination
<<< @/../src/test/scala/dev/mongocamp/driver/mongodb/pagination/PaginationAggregationSuite.scala#aggregation-pagination

## Find Pagination

<<< @/../src/test/scala/dev/mongocamp/driver/mongodb/pagination/PaginationFilterSpec.scala#filter-pagination
<<< @/../src/test/scala/dev/mongocamp/driver/mongodb/pagination/PaginationFilterSuite.scala#filter-pagination

## Foreach over Pagination result

### With default row count
<<< @/../src/test/scala/dev/mongocamp/driver/mongodb/pagination/PaginationIterationSpec.scala#foreach-default-rows
<<< @/../src/test/scala/dev/mongocamp/driver/mongodb/pagination/PaginationIterationSuite.scala#foreach-default-rows

### With specific row count
<<< @/../src/test/scala/dev/mongocamp/driver/mongodb/pagination/PaginationIterationSpec.scala#foreach-with-rows
<<< @/../src/test/scala/dev/mongocamp/driver/mongodb/pagination/PaginationIterationSuite.scala#foreach-with-rows
27 changes: 16 additions & 11 deletions docs/documentation/database/bson.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,31 +14,36 @@ BSON converter is used for bidirectional converting of BSON data.
### toBson

```scala
val result = BsonConverter.toBson(3) // result = BsonInt32(3)
val result = BsonConverter.toBson(3) // result = BsonInt32(3)
```


### fromBson

```scala
val result = BsonConverter.fromBson(BsonInt32(3)) // result = 3
val result = BsonConverter.fromBson(BsonInt32(3)) // result = 3
```

### toDocument

```scala
case class Base(int: Int, Long: Long, float: Float, double: Double,
string: String, date: Date = new Date())

object Base {
def apply(): Base = new Base(1, 2, 3, 4, "test")
}
case class Base(int: Int, Long: Long, float: Float, double: Double, string: String, date: Date = new Date())

val document = Converter.toDocument(Base())
object Base {
def apply(): Base = new Base(1, 2, 3, 4, "test")
}

// Document((float,BsonDouble{value=3.0}), (string,BsonString{value='test'}),
// (double,BsonDouble{value=4.0}), (Long,BsonInt64{value=2}), (date,
// BsonDateTime{value=1531166757627}), (int,BsonInt32{value=1}))
val document = Converter.toDocument(Base())

// Document(
// (float,BsonDouble{value=3.0}),
// (string,BsonString{value='test'}),
// (double,BsonDouble{value=4.0}),
// (Long,BsonInt64{value=2}),
// (date, BsonDateTime{value=1531166757627}),
// (int,BsonInt32{value=1})
// )
```

## Plugins
Expand Down
4 changes: 1 addition & 3 deletions docs/documentation/database/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ mongo.db.test {

Scala Code Snippet
```scala
val customConfig: MongoConfig = MongoConfig.fromPath("mongodb.db.prod")
val customConfig: MongoConfig = MongoConfig.fromPath("mongodb.db.prod")
```


Expand Down Expand Up @@ -76,5 +76,3 @@ It is used for DatabaseProvider creation.
| minSize | 0 |
| DefaultMaintenanceInitialDelay | 0 |

## Multiple databases access

8 changes: 4 additions & 4 deletions docs/documentation/database/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,10 @@ DatabaseProvider is the central repository for MongoClient, registries, database
Every [Mongo DAO](../mongo-dao/index.md) / [GridFs DAO](../gridfs-dao/index.md) Instance needs this class.

```scala
val provider: DatabaseProvider = DatabaseProvider(MongoConfig.fromPath())
val provider: DatabaseProvider = DatabaseProvider(MongoConfig.fromPath())

val database: MongoDatabase = provider.database()
val database: MongoDatabase = provider.database()

// Infos for all collections in the default database
val collectionInfos: List[CollectionInfo] = provider.collectionInfos()
// Infos for all collections in the default database
val collectionInfos: List[CollectionInfo] = provider.collectionInfos()
```
6 changes: 3 additions & 3 deletions docs/documentation/database/lucene.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,17 +6,17 @@ MongoCamp Mongo Driver support the usage of [Lucene Query](https://lucene.apache
### Explicit Usage
The LuceneConverter has the methods to parse a String to and `Query` and a other to the document conversion.

<<< @/../src/test/scala/dev/mongocamp/driver/mongodb/lucene/LuceneSearchSpec.scala#lucene-parser-with-explicit
<<< @/../src/test/scala/dev/mongocamp/driver/mongodb/lucene/LuceneSearchSuite.scala#lucene-parser-with-explicit

### Implicit Usage
Like the Map to Bson conversion there is also an implicit method to convert `Query` to find Bson.

<<< @/../src/test/scala/dev/mongocamp/driver/mongodb/lucene/LuceneSearchSpec.scala#lucene-parser-with-implicit
<<< @/../src/test/scala/dev/mongocamp/driver/mongodb/lucene/LuceneSearchSuite.scala#lucene-parser-with-implicit

### Parse String to Query
We have an individual parser to parse an string to Lucene Query, because the default Lucene Analyser is case-insensitive and convert all search data into lower case. So the best way to seach in MongoDb with Lucene Query is to use this code.

<<< @/../src/test/scala/dev/mongocamp/driver/mongodb/lucene/LuceneSearchSpec.scala#lucene-parser
<<< @/../src/test/scala/dev/mongocamp/driver/mongodb/lucene/LuceneSearchSuite.scala#lucene-parser

## Read More
[Lucene Cheatsheet](https://www.lucenetutorial.com/lucene-query-syntax.html)
33 changes: 8 additions & 25 deletions docs/documentation/database/provider.md
Original file line number Diff line number Diff line change
@@ -1,37 +1,20 @@
# DatabaseProvider

DatabaseProvider is the central repository for MongoClient, registries, databases and collections.
DatabaseProvider is the central repository for MongoClient, databases, collections and DocumentDAO`s.

DatabaseProvider gives access to

* MongoClient
* MongoDatabase
* MongoCollection

## Registries

::: tip ScalaDriverDocs
Additional Info for [Registries](https://mongodb.github.io/mongo-java-driver/4.0/driver-scala/getting-started/quick-start-case-class/#configuring-case-classes)
:::

### Create Case Classes
```scala
case class Student(_id: Long, name: String, scores: List[Score])

case class Score(score: Double, `type`: String)

case class Grade(_id: ObjectId, student_id: Long, class_id: Long, scores: List[Score])
```

### Create Registry
```scala
val registry: CodecRegistry = fromProviders(classOf[Student], classOf[Score], classOf[Grade])

val providerWithRegistry: DatabaseProvider = DatabaseProvider(MongoConfig.fromPath(), registry)
```
## Multiple databases access


## DocumentDAO
From an DocumentDAO you can perform DocumentDAO initialization and caching. On this DAO you can perform CRUD operations.

<<< @/../src/test/scala/dev/mongocamp/driver/mongodb/database/DatabaseProviderSuite.scala#document-dao

## ~~Registries~~

::: danger
Registries are no longer supported for automatic case class conversion. For scala 3 support we changed from mongodb driver conversion to circe conversion.
:::
18 changes: 10 additions & 8 deletions docs/documentation/database/relationships.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,14 +20,16 @@ Simple Setup.
* Friend Collection

```scala
case class User(id: Long, name: String, loginId: String)
case class Login(id: String, email: String, password: String)
case class Friend(id: Long, name: String, userId: Long)

object UserDAO extends MongoDAO[User](database, "user")
object LoginDAO extends MongoDAO[Login](database, "login")
object FriendDAO extends MongoDAO[Friend](database, "friend")

import dev.mongocamp.driver.mongodb.json._
import io.circe.generic.auto._

case class User(id: Long, name: String, loginId: String)
case class Login(id: String, email: String, password: String)
case class Friend(id: Long, name: String, userId: Long)

object UserDAO extends MongoDAO[User](database, "user")
object LoginDAO extends MongoDAO[Login](database, "login")
object FriendDAO extends MongoDAO[Friend](database, "friend")
```

For relationship setup we create two Relationships in the UserDAO.
Expand Down
13 changes: 8 additions & 5 deletions docs/documentation/gridfs-dao/crud.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Possible Metadata types:
Return Observable of ObjectId.

```scala
ImageFilesDAO.insertOne(filename, stream, metadata)
ImageFilesDAO.insertOne(filename, stream, metadata)
```

## Update
Expand All @@ -31,8 +31,11 @@ With implicit conversion you can use for OID Parameter:
* String

```scala
// for implicit conversion usage
import dev.mongocamp.driver.mongodb._

ImageFilesDAO.deleteOne(oid)
// for implicit conversion usage
import dev.mongocamp.driver.mongodb._
// case class conversion only needed in the DAO Holder Class
import dev.mongocamp.driver.mongodb.json._
import io.circe.generic.auto._

ImageFilesDAO.deleteOne(oid)
```
19 changes: 9 additions & 10 deletions docs/documentation/gridfs-dao/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,15 +19,14 @@ A [MongoDatabase](http://mongodb.github.io/mongo-scala-driver/2.3/scaladoc/org/m
### Create DAO

```scala

/**
* use bucket name fs
*/
object ImageFilesDAO extends GridFSDAO(database)

/**
* use bucket name images
*/
object ImageFilesDAO extends GridFSDAO(database, "images")
/**
* use bucket name fs
*/
object ImageFilesDAO extends GridFSDAO(database)

/**
* use bucket name images
*/
object ImageFilesDAO extends GridFSDAO(database, "images")

```
7 changes: 3 additions & 4 deletions docs/documentation/gridfs-dao/metadata.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,9 @@ UpdateMetadataElement/s update some part of the metadata by a given filter.


```scala

val elements = Map("category"->"logos")
val filter = Map() // all files
ImageFilesDAO.updateMetadataElements(filter, elements)
val elements = Map("category"->"logos")
val filter = Map() // all files
ImageFilesDAO.updateMetadataElements(filter, elements)
```


Expand Down
2 changes: 1 addition & 1 deletion docs/documentation/mongo-dao/base.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ Sometimes we need Raw Support (DAO maps to Document).
This is automatically included in the MongoDAO class.
Simply call Raw on your DAO Object.

<<< @/../src/test/scala/dev/mongocamp/driver/mongodb/operation/AggregationSpec.scala#agg_execute
<<< @/../src/test/scala/dev/mongocamp/driver/mongodb/operation/AggregationSuite.scala#agg_execute

## Base Functions

Expand Down
Loading

0 comments on commit 382eb35

Please sign in to comment.