Permalink
Browse files

Integrate the four official Activator templates into the manual.

We can use Lightbend’s Example Code Service to make pre-packaged zip
files available for download. We need to move away from Activator
because it will be shut down soon.

I updated the sample code for 3.2 and tried to integrate the tutorials
back into the manual. Some more polishing could be done in order to
retire FirstExample.scala and PlainSQL.scala from doc/code and take
all snippets on gettingstarted.md and sql.md from the sample projects.
  • Loading branch information...
szeiger committed Mar 24, 2017
1 parent 7922989 commit 8b342b4a177770431223c2a2559041a009eda9f3
Showing with 2,247 additions and 125 deletions.
  1. +2 −2 doc/code/FirstExample.scala
  2. +2 −4 doc/ornate.conf
  3. +117 −3 doc/src/database.md
  4. +152 −50 doc/src/gettingstarted.md
  5. +0 −1 doc/src/introduction.md
  6. +3 −4 doc/src/sql.md
  7. +22 −60 doc/src/testkit.md
  8. +4 −0 doc/src/userdefined.md
  9. +33 −1 project/Build.scala
  10. +1 −0 project/build.properties
  11. +121 −0 samples/hello-slick/COPYING
  12. +8 −0 samples/hello-slick/LICENSE
  13. +2 −0 samples/hello-slick/README
  14. +12 −0 samples/hello-slick/build.sbt
  15. +1 −0 samples/hello-slick/project/build.properties
  16. +6 −0 samples/hello-slick/src/main/resources/application.conf
  17. +41 −0 samples/hello-slick/src/main/scala/CaseClassMapping.scala
  18. +200 −0 samples/hello-slick/src/main/scala/HelloSlick.scala
  19. +75 −0 samples/hello-slick/src/main/scala/QueryActions.scala
  20. +37 −0 samples/hello-slick/src/main/scala/Tables.scala
  21. +49 −0 samples/hello-slick/src/test/scala/TablesSuite.scala
  22. +21 −0 samples/override.sbt
  23. +4 −0 samples/resources/application.conf
  24. +121 −0 samples/slick-multidb/COPYING
  25. +8 −0 samples/slick-multidb/LICENSE
  26. +2 −0 samples/slick-multidb/README
  27. +12 −0 samples/slick-multidb/build.sbt
  28. +1 −0 samples/slick-multidb/project/build.properties
  29. +25 −0 samples/slick-multidb/src/main/resources/application.conf
  30. +11 −0 samples/slick-multidb/src/main/scala/Util.scala
  31. +35 −0 samples/slick-multidb/src/main/scala/basic/DAO.scala
  32. +13 −0 samples/slick-multidb/src/main/scala/basic/DAOHelper.scala
  33. +41 −0 samples/slick-multidb/src/main/scala/basic/MultiDBExample.scala
  34. +10 −0 samples/slick-multidb/src/main/scala/cake/DAL.scala
  35. +49 −0 samples/slick-multidb/src/main/scala/cake/MultiDBCakeExample.scala
  36. +24 −0 samples/slick-multidb/src/main/scala/cake/PictureComponent.scala
  37. +6 −0 samples/slick-multidb/src/main/scala/cake/ProfileComponent.scala
  38. +31 −0 samples/slick-multidb/src/main/scala/cake/UserComponent.scala
  39. +39 −0 samples/slick-multidb/src/main/scala/databaseconfig/SimpleExample.scala
  40. +57 −0 samples/slick-multidb/src/main/scala/native/CallNativeDBFunction.scala
  41. +121 −0 samples/slick-plainsql/COPYING
  42. +8 −0 samples/slick-plainsql/LICENSE
  43. +2 −0 samples/slick-plainsql/README
  44. +15 −0 samples/slick-plainsql/build.sbt
  45. +1 −0 samples/slick-plainsql/project/build.properties
  46. +15 −0 samples/slick-plainsql/src/main/resources/application.conf
  47. +11 −0 samples/slick-plainsql/src/main/resources/create-schema.sql
  48. +84 −0 samples/slick-plainsql/src/main/scala/Interpolation.scala
  49. +36 −0 samples/slick-plainsql/src/main/scala/PlainSQL.scala
  50. +15 −0 samples/slick-plainsql/src/main/scala/Transfer.scala
  51. +28 −0 samples/slick-plainsql/src/main/scala/TypedSQL.scala
  52. +121 −0 samples/slick-testkit-example/COPYING
  53. +8 −0 samples/slick-testkit-example/LICENSE
  54. +2 −0 samples/slick-testkit-example/README
  55. +19 −0 samples/slick-testkit-example/build.sbt
  56. +1 −0 samples/slick-testkit-example/project/build.properties
  57. +255 −0 samples/slick-testkit-example/src/main/scala/MyPostgresProfile.scala
  58. +54 −0 samples/slick-testkit-example/src/test/resources/logback-test.xml
  59. +15 −0 samples/slick-testkit-example/src/test/resources/testkit-reference.conf
  60. +30 −0 samples/slick-testkit-example/src/test/scala/MyPostgresTest.scala
  61. +8 −0 samples/slick-testkit-example/test-dbs/testkit.conf
@@ -52,7 +52,7 @@ object FirstExample extends App {
//#setup
val db = Database.forConfig("h2mem1")
try {
// ...
// val resultFuture: Future[_] = { ... }
//#setup
//#create
@@ -149,9 +149,9 @@ object FirstExample extends App {
db.run(q3.result).map(_.foreach { case (s1, s2) => println(" " + s1 + " supplied by " + s2) })
}
//#setup
Await.result(resultFuture, Duration.Inf)
lines.foreach(Predef.println _)
//#setup
} finally db.close
//#setup
}
View
@@ -58,10 +58,6 @@ extension.globalRefs.refs {
"Oracle": "https://www.oracle.com/database/"
"SQL Server": "http://www.microsoft.com/en-us/server-cloud/products/sql-server/"
"JMX": "https://en.wikipedia.org/wiki/Java_Management_Extensions"
"Hello Slick template": "https://typesafe.com/activator/template/hello-slick-"${shortVersion}
"Slick Plain SQL Queries template": "https://typesafe.com/activator/template/slick-plainsql-"${shortVersion}
"Slick Multi-DB Patterns template": "http://typesafe.com/activator/template/slick-multidb-"${shortVersion}
"Slick TestKit Example template": "https://typesafe.com/activator/template/slick-testkit-example-"${shortVersion}
}
extension.includeCode {
@@ -94,6 +90,8 @@ extension.externalLinks {
uri = "https://issues.scala-lang.org/browse/SI-[all]"
text = "SI-[all]"
}
samplezip.uri = "https://example.lightbend.com/v1/download/[all]-"${shortVersion}
samplerepo.uri = "https://github.com/slick/slick/tree/"${shortVersion}"/samples/[all]"
}
extension.highlightjs {
View
@@ -111,13 +111,127 @@ should therefore enable prepared statement caching in the connection pool's conf
DatabaseConfig
--------------
> {.note}
> This section is based on the **MultiDB** sample ([github](samplerepo:slick-multidb),
> [zip](samplezip:slick-multidb)) which provides ready-to-run apps to demonstrate the features.
On top of the configuration syntax for `Database`, there is another layer in the form of
<api:slick.basic.DatabaseConfig> which allows you to configure a Slick profile plus a
matching `Database` together. This makes it easy to abstract over different kinds of
database systems by simply changing a configuration file.
Here is a typical `DatabaseConfig` with a Slick profile object in `profile` and the database
configuration in `db`:
You can see it in action in `SimpleExample.scala`. First we load the DatabaseConfig and then import the
Slick API from its profile:
```scala src=../../samples/slick-multidb/src/main/scala/databaseconfig/SimpleExample.scala#dc
```
The `JdbcProfile` type annotation specifies the profile level whose API you get. You have to configure a profile of
a matching type in the external configuration file. Since we're using the basic `forConfig` method with only a path
("h2_dc"), the configuration must be located in the global application config, usually found in `application.conf`:
```scala src=../../samples/slick-multidb/src/main/resources/application.conf#--doc-h2_db
```
You can use different database systems in your application by either switching out or overriding the application
config (e.g. different `application.conf` files for development and production) or by passing a config path into
the application. This way of implementing multi-database support is also used when building a Play app with Slick.
Other Multi-DB Patterns
-----------------------
> {.note}
> This section is based on the **MultiDB** sample ([github](samplerepo:slick-multidb),
> [zip](samplezip:slick-multidb)) which provides ready-to-run apps to demonstrate the features.
Since its addition in Slick 3.0 `DatabaseConfig` (see [above](#databaseconfig)) is the recommended solution.
More complex scenarios (for example, where you need to map custom functions differently for different database
systems, or where you cannot use the simple application.conf syntax) may require abstracting over databases in Scala
code. The following sections explain two different ways of accomplishing this.
### A DAO Class
We start with a simple DAO (data access object) class, `DAO.scala`. It contains some database-related definitions
(for a `PROPS` table that acts as a simple key/value store) and methods (for storing and reading entries).
```yaml src=../code/application.conf#tsql
The class is parameterized by a concrete `JdbcProfile` and it imports all API features from this profile's api object:
```scala src=../../samples/slick-multidb/src/main/scala/basic/DAO.scala#dao
```
Slick has multiple abstract profiles but in most cases you will want to use `JdbcProfile` which contains all the
features that you also get when importing directly from one of Slick's concrete profiles for JDBC databases.
Outside of the DAO class, you can still refer to its profile and the other features, but you have to get the imports
from the profile in order to work with queries. This can be seen in `DAOHelper.scala`. It defines a new method
`restrictKey` which we could have also put directly into the DAO class.
To gain access to all of the profile's features, we parameterize the `DAOHelper` with the `DAO` and import from its
profile:
```scala src=../../samples/slick-multidb/src/main/scala/basic/DAOHelper.scala#daohelper
```
Note the use of the type projection `DAO#Props` in the definition of `restrictKey`. This points to the `Props` type
coming from any `DAO` instance. This is less type-safe than using a path-dependent type like `dao.Props` but
generally easier to use. You still need to ensure not to mix drivers when you do this.
We are using the `DAO` and `DAOHelper` in `MultiDBExample.scala`. The `run` method is parameterized with both,
a Slick profile and a matching JDBC `Database`:
```scala src=../../samples/slick-multidb/src/main/scala/basic/MultiDBExample.scala#run
```
Since we don't have the convenience of a single profile's `api._` import at this point, we need to import the
`Database` and `DBIO` types directly:
```scala src=../../samples/slick-multidb/src/main/scala/basic/MultiDBExample.scala#imports
```
In the body of `MultiDBExample`, we create two `DAO` instances with matching `Database` objects in order to run the
same code on both, H2 and SQLite:
```scala src=../../samples/slick-multidb/src/main/scala/basic/MultiDBExample.scala#create
```
### The Cake Pattern
In more complex designs where you want to split up the database code into separate modules that deal with different
database entities, but still have dependencies between these modules, you can use the Cake Pattern to structure your
code.
We are doing this here in the app `MultiDBCakeExample.scala`. From the point of view of this main app, the new
approach looks exactly like the previous one: You create a DAL (data access layer) object with a Slick profile, and
use it together with a matching `Database`.
The most basic slice of the cake is the `ProfileComponent`. It provides a `JdbcProfile` which is kept abstract at
this point:
```scala src=../../samples/slick-multidb/src/main/scala/cake/ProfileComponent.scala
```
Through the use of a self-type, the `PictureComponent` requires a `ProfileComponent` to me mixed in, so that it can
import the query language features from the profile:
```scala src=../../samples/slick-multidb/src/main/scala/cake/PictureComponent.scala#outline
```
Using the imported features, `PictureComponent` provides definitions and methods for working with `Picture` objects
in the database. `UserComponent` does the same for `User` entities. In addition to `ProfileComponent` it also
requires `PictureComponent`:
```scala src=../../samples/slick-multidb/src/main/scala/cake/UserComponent.scala#outline
```
The `PictureComponent` dependency allows `UserComponent` to insert a new `Picture` when needed:
```scala src=../../samples/slick-multidb/src/main/scala/cake/UserComponent.scala#insert
```
We put all slices of the cake together in `DAL.scala`. The `DAL` class inherits from all components and adds the
missing profile through a field in the constructor:
```scala src=../../samples/slick-multidb/src/main/scala/cake/DAL.scala
```
This is also a good place to add functionality that affects all components, like the `create` method.
Oops, something went wrong.

0 comments on commit 8b342b4

Please sign in to comment.