Create documentation

docs/usage/init-connection.md

@@ -0,0 +1,14 @@
+# Init connection
+
+Before execute any query you must instantiate the connection.
+```kotlin
+import fr.postgresjson.connexion.Connection
+
+val connection = Connection(
+    host = "localhost",
+    port = 5432,
+    database = "mydb",
+    username = "john",
+    password = "azerty"
+)
+```

docs/usage/raw-request.md

@@ -0,0 +1,46 @@
+# Raw request
+You can execute query directly from the code like this:
+(*see [Init connection](./init-connection.md) before*)
+
+```kotlin
+import fr.postgresjson.connexion.Connection
+
+val connection: Connection = TODO()
+
+val result: QueryResult = connection.exec(
+    "SELECT id FROM inventor WHERE name = :name",
+    mapOf("name" to "Nikola Tesla")
+)
+val id: String = result.rows[0].getString(0)
+```
+
+And if you must map the query result with an entity, you can do it like this:
+```kotlin
+import java.util.UUID
+import fr.postgresjson.entity.Serializable
+import fr.postgresjson.connexion.Connection
+
+val connection: Connection = TODO()
+
+data class Inventor(
+    val id: UUID = UUID.randomUUID(),
+    val name: String
+): Serializable
+
+val result: Inventor? = connection.selectOne(
+    """
+    SELECT json_build_object(
+        'id', '9e65de49-712e-47ce-8bf2-dfffae53a82e', 
+        'name', :name
+    )
+    """,
+    mapOf("name" to "Nikola Tesla")
+)
+
+val inventor = connection.selectOne<Inventor>("SELECT * FROM mytable WHERE id = :id")
+
+val inventors: List<Inventor> = connection.select("SELECT * FROM mytable WHERE status = 'done'")
+```
+
+
+See [ConnectionTest.kt](/src/test/kotlin/fr/postgresjson/ConnectionTest.kt) for more examples.

docs/usage/stored-procedure.md

@@ -0,0 +1,85 @@
+# Stored Procedure
+*Execute stored procedure with requester*
+
+You can execute a stored procedure (previously defined in a migration) via the Requester
+
+To do that:
+
+1. First, instantiate the requester
+```kotlin
+import fr.postgresjson.connexion.Requester
+import fr.postgresjson.connexion.Connection
+
+val connection: Connection = TODO()
+
+val requester = Requester.RequesterFactory(
+    connection = connection,
+    functionsDirectory = this::class.java.getResource("/sql/functions")?.toURI() ?: error("No sql function found")
+).createRequester()
+```
+
+2. then, define Entities
+```kotlin
+import java.util.UUID
+import org.joda.time.DateTime
+import fr.postgresjson.entity.Serializable
+
+enum class Roles { ROLE_USER, ROLE_ADMIN }
+
+class User(
+    id: UUID = UUID.randomUUID(),
+    override var username: String,
+    var blockedAt: DateTime? = null,
+    var roles: List<Roles> = emptyList()
+): Serializable
+
+class UserForCreate(
+    id: UUID = UUID.randomUUID(),
+    username: String,
+    val password: String,
+    blockedAt: DateTime? = null,
+    roles: List<Roles> = emptyList()
+): Serializable
+```
+3. and, define Repositories
+*[See SQL function](./migrations.md#Stored procedure migrations)*
+
+```kotlin
+import fr.postgresjson.connexion.Requester
+import fr.postgresjson.repository.RepositoryI
+import java.util.UUID
+
+class UserRepository(override var requester: Requester): RepositoryI {
+    fun findById(id: UUID): User {
+        return requester
+            .getFunction("find_user_by_id") // Use the name of the function
+            .selectOne(
+                "id" to id // You can pass parameters by their names. The underscore prefix on parameters is not required to be mapped. 
+            ) ?: throw UserNotFound(id) // Throw exception if user not found
+    }
+
+    fun insert(user: UserForCreate): User {
+        return requester
+            .getFunction("insert_user")
+            .selectOne("resource" to user)
+    }
+
+    class UserNotFound(override val message: String?, override val cause: Throwable?): Throwable(message, cause) {
+        constructor(id: UUID): this("No User with ID $id", null)
+    }
+}
+```
+
+4. And at last, execute queries
+```kotlin
+import fr.postgresjson.connexion.Requester
+import java.util.UUID
+
+val requester: Requester = TODO()
+val userRepo = UserRepository(requester)
+
+val user: User = userRepo.findById(UUID.fromString(id))
+
+val newUser: UserForCreate = TODO()
+val userInserted: User = userRepo.insert(newUser)
+```

docs/usage/usage.md

@@ -0,0 +1,5 @@
+## Usage
+
+1. [Init connection](./init-connection.md)
+2. [Raw request](./raw-request.md)
+3. [Stored Procedure](./stored-procedure.md)