Expose functions execute_query_and_handle_result and execute_plain_query

tencnivel · tencnivel · commit 50799b7c9704 · 2021-06-15T13:03:18.000+02:00
diff --git a/Manifest.toml b/Manifest.toml
@@ -88,12 +88,6 @@ git-tree-sha1 = "9d4f64f79012636741cf01133158a54b24924c32"
 uuid = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
 version = "0.8.4"
 
-[[Documenter]]
-deps = ["Base64", "Dates", "DocStringExtensions", "IOCapture", "InteractiveUtils", "JSON", "LibGit2", "Logging", "Markdown", "REPL", "Test", "Unicode"]
-git-tree-sha1 = "3ebb967819b284dc1e3c0422229b58a40a255649"
-uuid = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
-version = "0.26.3"
-
 [[Downloads]]
 deps = ["ArgTools", "LibCURL", "NetworkOptions"]
 uuid = "f43a241f-c20a-4ad4-852c-f6b1247861c6"
@@ -122,12 +116,6 @@ version = "0.4.2"
 deps = ["Random"]
 uuid = "9fa8497b-333b-5362-9e8d-4d0656e87820"
 
-[[IOCapture]]
-deps = ["Logging"]
-git-tree-sha1 = "377252859f740c217b936cebcd918a44f9b53b59"
-uuid = "b5f81e59-6552-4d32-b1f0-c071b021bf89"
-version = "0.1.1"
-
 [[Infinity]]
 deps = ["Dates", "Random", "Requires"]
 git-tree-sha1 = "633bac4f993e1237ad9745ae8df9c8378c6ef27a"
@@ -220,9 +208,9 @@ uuid = "8f399da3-3557-5675-b5ff-fb832c97cbdb"
 
 [[Libiconv_jll]]
 deps = ["Artifacts", "JLLWrappers", "Libdl", "Pkg"]
-git-tree-sha1 = "8d22e127ea9a0917bc98ebd3755c8bd31989381e"
+git-tree-sha1 = "42b62845d70a619f063a7da093d995ec8e15e778"
 uuid = "94ce4f54-9a6c-5748-9c1c-f9c7231a4531"
-version = "1.16.1+0"
+version = "1.16.1+1"
 
 [[LinearAlgebra]]
 deps = ["Libdl"]
diff --git a/Project.toml b/Project.toml
@@ -1,12 +1,11 @@
 name = "PostgresORM"
 uuid = "748b5efa-ed57-4836-b183-a38105a77fdd"
 authors = ["Vincent Laugier <vincent.laugier@gmail.com>"]
-version = "0.1.0"
+version = "0.1.1"
 
 [deps]
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
-Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 IterTools = "c8e1da08-722c-5040-9ed9-7db0dc04731e"
 JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
 LibPQ = "194296ae-ab2e-5f79-8cd4-7183a0a5a0d1"
@@ -18,14 +17,13 @@ TimeZones = "f269a46b-ccf7-5d73-abea-4c690281aa53"
 UUIDs = "cf7118a7-6976-5b1a-9a39-7adc72f591a4"
 
 [compat]
-julia = "1"
-Documenter="0.25.0,1"
-IterTools = "1.1.0,2"
 DataFrames = "0.19.0,1"
+IterTools = "1.1.0,2"
 JSON = "0.21,1"
 LibPQ = "1.1.0,2"
 Query = "1.0.0,2"
 StringCases = "0.1.0,1"
 Tables = "1.0.0,2"
 TickTock = "1.0.0,2"
 TimeZones = "1.3.0,2"
+julia = "1"
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -0,0 +1,5 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+
+[compat]
+Documenter = "0.27"
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,5 +1,5 @@
 import Pkg;
-Pkg.add("Documenter")
+#Pkg.add("Documenter")
 using Documenter, PostgresORM
 
 makedocs(
@@ -9,7 +9,8 @@ makedocs(
                  "Getting started" => "getting-started.md",
                  "Modules" => [
                         "modules/PostgresORM.md",
-                        "modules/PostgresORM.Controller.md"]
+                        # "modules/PostgresORM.Controller.md"
+                        ]
                  ],
 )
 deploydocs(; repo = "github.com/JuliaPostgresORM/PostgresORM.jl.git",
diff --git a/docs/src/getting-started.md b/docs/src/getting-started.md
@@ -2,15 +2,16 @@
 
 ## Pre-requisites
 ### Install LibPQ.jl
-`MyProject> add LibPQ`
+`(MyProject) pkg> add LibPQ`
 
 ### Install PostgresORM.jl
-`MyProject> add https://github.com/JuliaPostgresORM/PostgresORM.jl`
+`(MyProject) pkg> add PostgresORM`
 
 ## Example projects
 You can look at the following projects to see how PostgresORM is used :
   * [IMDBTestApp.jl](https://github.com/JuliaPostgresORM/IMDBTestApp.jl)
 
+
 ## Concepts
 
 ### Classes
@@ -143,6 +144,60 @@ Julia enums are the counterpart of PostgreSQL custom enumeration types.
 Many PostgresORM functions expects a `LibPQ.Connection` as one of the arguments.
 The developer is in charge of managing the connections and the transactions.
 
+## Design choices
+
+### Retrieval of _complex properties_
+Methods `retrieve_entity` and `retrieve_one_entity` expects the argument
+`retrieve_complex_props` to tell them if they need to make additional queries
+to retrieve the properties of the _complex properties_.
+If `retrieve_complex_props == false` then the properties of a _complex_property_
+will be set to missing except the properties used as IDs.
+
+### Retrieval of _properties of IEntities_
+Reminder, methods `retrieve_entity` and `retrieve_one_entity` expects the argument
+`retrieve_complex_props` to tell them if they need to make additional queries
+to retrieve the properties of the  _complex properties_. There is no such thing
+for _properties of IEntities_, PostgresORM never loads them (the properties of
+will be equal to missing). It is up to the package user to enrich the instance
+if he wants to.
+
+### Update of a _properties of IEntities_
+`update_entity` does not update properties of type vector of IEntities.
+If the user wants to update a property of type vector of IEntities, he needs to
+use `update_vector_property!`.
+
+### Beware! missing has two meanings
+A property with value missing can mean that:
+  * the value is missing for this entity
+  * the value has not been loaded yet
+
+We could have make use of `Nothing` for the second case but we decided not to
+because the benefit was too small compare to the complexity it was adding.
+Nevertheless, the developer must be well aware of this when updating an instance.
+Here are two code snippets to show what is the risk:
+
+```
+  # Load the film with retrieve_complex_props set to true
+  film = retrieve_one_entity(Film(codeName = "cube"),
+                             true, # retrieve the complex props
+                             dbconn)
+  @test ismissing(film.director.id) # false
+  @test ismissing(film.director.birthDate) # false
+  update_entity(film.director, dbconn) # This is OK
+
+
+  # Load the film with retrieve_complex_props set to false
+  film = retrieve_one_entity(Film(codeName = "cube"),
+                             false, # do not retrieve the complex props
+                             dbconn)
+  @test ismissing(film.director.id) # false
+  @test ismissing(film.director.birthDate) # true
+  update_entity(film.director, dbconn) # This is NOT OK! the director will loose
+                                       #   its birthDate
+
+
+```
+
 ## Reverse engineer the database
 The easiest way to get started is to ask PostgresORM to generate the _classes_,
 the ORM modules and the enums. Once done, you can copy the files in the _src_
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -9,8 +9,6 @@ This resource aims to teach you everything you need to know to get up and runnin
 ```@contents
 Depth = 2
 Pages = ["getting-started.md",
-         "modules/PostgresORM.md",
-         "modules/PostgresORM.Controller.md",
-         "modules/PostgresORM.PostgresORMUtil.md",
+         "modules/PostgresORM.md",         
          ]
 ```
diff --git a/docs/src/modules/PostgresORM.Controller.md b/docs/src/modules/PostgresORM.Controller.md
@@ -1 +1,3 @@
 # Module PostgresORM.Controller
+
+TODO
diff --git a/docs/src/modules/PostgresORM.PostgresORMUtil.md b/docs/src/modules/PostgresORM.PostgresORMUtil.md
@@ -0,0 +1,3 @@
+# Module PostgresORMUtil
+
+TODO
diff --git a/docs/src/modules/PostgresORM.md b/docs/src/modules/PostgresORM.md
@@ -1,6 +1,12 @@
 # Module PostgresORM
 
 ```@docs
-PostgresORM.retrieve_one_entity
+PostgresORM.create_entity!
+PostgresORM.create_in_bulk_using_copy
 PostgresORM.retrieve_entity
+PostgresORM.retrieve_one_entity
+PostgresORM.update_entity!
+PostgresORM.update_vector_property!
+PostgresORM.delete_entity
+PostgresORM.delete_entity_alike
 ```
diff --git a/src/PostgresORM.jl b/src/PostgresORM.jl
@@ -1,9 +1,8 @@
 module PostgresORM
 
   export greet, get_orm, create_entity!, create_in_bulk_using_copy,
-         delete_entity, delete_entity_alike,
-         retrieve_entity,
-         update_entity!, update_vector_property!
+         delete_entity, delete_entity_alike, retrieve_entity, update_entity!,
+         update_vector_property!, execute_plain_query
 
   export IEntity, IAppUser, Modification
 
diff --git a/src/exposed-functions-from-submodules.jl b/src/exposed-functions-from-submodules.jl
@@ -1,4 +1,18 @@
 # CREATE
+"""
+    create_entity!(new_object::IEntity,
+                   dbconn::LibPQ.Connection;
+                   creator::Union{IAppUser,Missing} = missing)
+
+Persists an instance to the database.
+Properties of type vector of IEntity are not persisted
+(see function `update_vector_property!` for that usage).
+The instance gets enriched by the values generated by the database in the process
+(eg. autogenerated primary keys).
+If the optional argument 'creator' is given and that the ORM module of the class
+is configured to track the creator then a entry will be inserted in the
+modification table
+"""
 function create_entity!(new_object::IEntity,
                        dbconn::LibPQ.Connection;
                        creator::Union{IAppUser,Missing} = missing)
@@ -8,6 +22,12 @@ function create_entity!(new_object::IEntity,
                              creator = creator)
 end
 
+"""
+    function create_in_bulk_using_copy(entities::Vector{T},
+                                       dbconn::LibPQ.Connection) where T <: IEntity
+
+Persists many instances to the database using PostgreSQL 'COPY'
+"""
 function create_in_bulk_using_copy(entities::Vector{T},
                                    dbconn::LibPQ.Connection) where T <: IEntity
 
@@ -23,6 +43,10 @@ end
 
 Retrieves a vector or T instances that match the filter.
 If there is no match, it returns an empty vector.
+If `retrieve_complex_props` is true then a complex prop (i.e. a property of
+type IEntity) is fully loaded using an additional query to the database ;
+if not, an instance of IEntity is simply created using the values of the foreign
+key, the other properties are left to missing.
 """
 function retrieve_entity(filter_object::IEntity,
                          retrieve_complex_props::Bool,
@@ -44,7 +68,7 @@ If there are more than one match, an error is thrown.
 If `retrieve_complex_props` is true then a complex prop (i.e. a property of
 type IEntity) is fully loaded using an additional query to the database ;
 if not, an instance of IEntity is simply created using the values of the foreign
-key
+key, the other properties are left to missing.
 """
 function retrieve_one_entity(filter_object::T,
                              retrieve_complex_props::Bool,
@@ -54,7 +78,21 @@ function retrieve_one_entity(filter_object::T,
                                      dbconn)
 end
 
-# UPDATE
+
+"""
+    update_entity!(updated_object::IEntity,
+                   dbconn::LibPQ.Connection;
+                   editor::Union{IAppUser,Missing} = missing)
+
+Updates an instance to the database.
+Properties of type vector of IEntity are not updated
+(see function `update_vector_property!` for that usage).
+The instance gets enriched by the values generated by the database in the process
+(eg. values generated by triggers).
+If the optional argument 'editor' is given and that the ORM module of the class
+is configured to track the editor then a entry will be inserted in the
+modification table
+"""
 function update_entity!(updated_object::IEntity,
                        dbconn::LibPQ.Connection;
                        editor::Union{IAppUser,Missing} = missing
@@ -65,6 +103,15 @@ function update_entity!(updated_object::IEntity,
                               )
 end
 
+"""
+    update_vector_property!(updated_object::IEntity,
+                            updated_property::Symbol,
+                            dbconn::Union{Missing, LibPQ.Connection};
+                            editor::Union{Missing, IAppUser} = missing)
+
+Updates a property of type vector of IEntity
+
+"""
 function update_vector_property!(updated_object::IEntity,
                                  updated_property::Symbol,
                                  dbconn::Union{Missing, LibPQ.Connection};
@@ -77,7 +124,13 @@ function update_vector_property!(updated_object::IEntity,
 
 end
 
-# DELETE
+"""
+    delete_entity(deleted_object::IEntity,
+                  dbconn::LibPQ.Connection;
+                  editor::Union{IAppUser,Missing} = missing)
+
+Deletes an entity on the basis of its ID
+"""
 function delete_entity(deleted_object::IEntity,
                        dbconn::LibPQ.Connection;
                        editor::Union{IAppUser,Missing} = missing
@@ -88,6 +141,13 @@ function delete_entity(deleted_object::IEntity,
                              )
 end
 
+"""
+    delete_entity_alike(filter_object::IEntity,
+                        dbconn::LibPQ.Connection;
+                        editor::Union{IAppUser,Missing} = missing)
+
+Deletes all entities matching the the filter
+"""
 function delete_entity_alike(filter_object::IEntity,
                        dbconn::LibPQ.Connection;
                        editor::Union{IAppUser,Missing} = missing
@@ -97,3 +157,41 @@ function delete_entity_alike(filter_object::IEntity,
                                    editor = editor
                                    )
 end
+
+"""
+      execute_plain_query(query_string::String,
+                          query_args::Union{Vector,Missing},
+                          dbconn::LibPQ.Connection)
+
+Execute a query and with the given arguments returns a dataframe
+"""
+function execute_plain_query(query_string::String,
+                             query_args::Union{Vector,Missing},
+                             dbconn::LibPQ.Connection)
+   Controller.execute_plain_query(query_string,
+                                  query_args,
+                                  dbconn)
+end
+
+"""
+      execute_query_and_handle_result(query_string::String,
+                                      data_type::DataType,
+                                      query_args::Union{Vector,Missing},
+                                      retrieve_complex_props::Bool,
+                                      dbconn::LibPQ.Connection)
+
+Execute a query and with the given arguments and convert the rows to the given
+data_type in the same way that `retrieve_entity` would do it.
+"""
+function execute_query_and_handle_result(query_string::String,
+                                         data_type::DataType,
+                                         query_args::Union{Vector,Missing},
+                                         retrieve_complex_props::Bool,
+                                         dbconn::LibPQ.Connection)
+
+    Controller.execute_query_and_handle_result(query_string,
+                                               data_type,
+                                               query_args,
+                                               retrieve_complex_props,
+                                               dbconn)
+end

Original file line number	Diff line number	Diff line change
`@@ -1 +1,3 @@`
`1`	`1`	`# Module PostgresORM.Controller`
	`2`	`+`
	`3`	`+TODO`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Module PostgresORMUtil`
	`2`	`+`
	`3`	`+TODO`