ENH: Add convenience functions

src/CaosDB.jl

@@ -37,7 +37,12 @@ export connect, connect_manually
 # Exports from module Entity
 # Creators
 export create_entity,
-    create_parent, create_property, create_property_entity, create_record, create_recordtype
+    create_parent,
+    create_property,
+    create_property_entity,
+    create_record,
+    create_recordtype,
+    create_file_entity
 
 # getters
 export get_id,
@@ -96,7 +101,11 @@ export create_transaction,
     get_result_at,
     get_results,
     execute_query,
-    retrieve
+    retrieve,
+    insert_entity,
+    update_entity,
+    delete_by_id,
+    retrieve_and_download_file_by_id
 
 using Libdl
 

src/Entity.jl

@@ -24,7 +24,12 @@ module Entity
 
 # Creators
 export create_entity,
-    create_parent, create_property, create_property_entity, create_record, create_recordtype
+    create_parent,
+    create_property,
+    create_property_entity,
+    create_record,
+    create_recordtype,
+    create_file_entity
 
 # getters
 export get_id,
@@ -343,7 +348,35 @@ function create_property(;
     return property
 
 end
+"""
+function create_file_entity(;
+    name::AbstractString = "",
+    local_path::AbstractString,
+    remote_path::AbstractString)
 
+Return a new entity object with role File.
+`local_path` is the path of the file on the local file system. An exception is
+thrown if this file is not existent. `remote_path` is the path of the file on
+the remote caosdb server.
+"""
+function create_file_entity(;
+    local_path::AbstractString,
+    remote_path::AbstractString,
+    name::AbstractString = "",
+)
+    if isfile(local_path) == false
+        throw(
+            CaosDB.Exceptions.ClientException("Cannot find the local file '$local_path'."),
+        )
+    end
+
+    file_entity = create_entity(name)
+    set_role(file_entity, "FILE")
+    set_local_path(file_entity, local_path)
+    set_remote_path(file_entity, remote_path)
+
+    return file_entity
+end
 """
     function create_parent(; name::AbstractString = "", id::AbstractString = "")
 

src/Transaction.jl

@@ -36,7 +36,11 @@ export create_transaction,
     get_result_at,
     get_results,
     execute_query,
-    retrieve
+    retrieve,
+    insert_entity,
+    update_entity,
+    delete_by_id,
+    retrieve_and_download_file_by_id
 
 using CaosDB
 
@@ -606,5 +610,56 @@ function retrieve(
 
     return get_results(transaction)
 end
+"""
+    function insert_entity(entity::Ref{CaosDB.Entity._Entity})
+
+Insert a single Entity.
+"""
+function insert_entity(entity::Ref{CaosDB.Entity._Entity})
+
+    transaction = create_transaction()
+    add_insert_entity(transaction, entity)
+    execute(transaction)
+    return get_results(transaction)
+end
+"""
+    function update_entity(entity::Ref{CaosDB.Entity._Entity})
+
+Update a single Entity.
+"""
+function update_entity(entity::Ref{CaosDB.Entity._Entity})
+
+    transaction = create_transaction()
+    add_update_entity(transaction, entity)
+    execute(transaction)
+    return get_results(transaction)
+end
+"""
+    function delete_by_id(id::AbstractString)
+
+Delete a single Entity identified by its `id`.
+"""
+function delete_by_id(id::AbstractString)
+
+    transaction = create_transaction()
+    add_delete_by_id(transaction, id)
+    execute(transaction)
+    return get_results(transaction)
+end
+"""
+    function retrieve_and_download_file_by_id(
+        id::AbstractString, 
+        download_path::AbstractString)
+
+Retrieve and download a single File-Entity identified by its `id`.
+`download_path` is the path where the file will be downloaded.
+"""
+function retrieve_and_download_file_by_id(id::AbstractString, download_path::AbstractString)
+
+    transaction = create_transaction()
+    add_retrieve_and_download_file_by_id(transaction, id, download_path)
+    execute(transaction)
+    return get_results(transaction)
+end
 
 end # Transaction

test/runtests.jl

@@ -164,6 +164,21 @@ using CaosDB
         @test CaosDB.Entity.get_name(
             CaosDB.Entity.get_properties(rec_with_parent_and_props)[2],
         ) == "Property3"
+        
+        f = touch("caosdbfilefortests.txt")
+        write(f, "Content")
+        file_ent = CaosDB.Entity.create_file_entity(name= "TestFile", 
+            local_path = string(pwd(),"/","caosdbfilefortests.txt"), 
+            remote_path = "/remote_path/file.txt")
+        @test CaosDB.Entity.get_role(file_ent) == "FILE"
+        @test CaosDB.Entity.get_name(file_ent) == "TestFile"
+        # local file not found
+        rm(string(pwd(),"/","caosdbfilefortests.txt"))
+        @test_throws CaosDB.Exceptions.ClientException CaosDB.Entity.create_file_entity(
+            name= "TestFile",
+            local_path = string(pwd(),"/","caosdbfilefortests.txt"), 
+            remote_path = "/remote_path/file.txt"
+        )
     end
 
     @testset "Datatype and values" begin