diff --git a/docs/src/api.md b/docs/src/api.md index 14cdb0cca131652c8f5b8ceeeb20edc3377a174a..46eb41c9707cca5621789cda6fa456c5fd2bcc86 100644 --- a/docs/src/api.md +++ b/docs/src/api.md @@ -5,16 +5,24 @@ interface. You also find the documentation of the internal API which is meant for expert use only. Only use those if you know what you're doing. +```@index +Order = [:module, :function, :macro, :type, :constant] +``` + ## Public API ```@autodocs -Modules=[CaosDB, CaosDB.Exceptions, CaosDB.Info, CaosDB.Utility, CaosDB.Connection, CaosDB.Authentication, CaosDB.Entity] +Modules=[CaosDB, CaosDB.Exceptions, CaosDB.Info, CaosDB.Utility, + CaosDB.Connection, CaosDB.Authentication, CaosDB.Entity, + CaosDB.Transaction] Private=false ``` ## Expert-use only API functions ```@autodocs -Modules=[CaosDB, CaosDB.Exceptions, CaosDB.Info, CaosDB.Utility, CaosDB.Connection, CaosDB.Authentication, CaosDB.Entity] +Modules=[CaosDB, CaosDB.Exceptions, CaosDB.Info, CaosDB.Utility, + CaosDB.Connection, CaosDB.Authentication, CaosDB.Entity, + CaosDB.Transaction] Public=false ``` diff --git a/src/Transaction.jl b/src/Transaction.jl index a3a1549d25cb47c0e5aa355fd6ebb3219aef0739..3d4bd53d0fd241a40344fa120bf9c0a27d700a6d 100644 --- a/src/Transaction.jl +++ b/src/Transaction.jl @@ -23,7 +23,7 @@ module Transaction -export create_transaction +export create_transaction, add_retrieve_by_id, add_query using CaosDB @@ -86,4 +86,84 @@ function create_transaction(connection::Ref{CaosDB.Connection._Connection}) return transaction end +""" + function add_retrieve_by_id(transaction::Ref{_Transaction}, id::AbstractString) + +Add a sub-request to retrieve a single entity by its `id` to the given +`transaction`. + +!!! info + + This does not execute the transaction. +""" +function add_retrieve_by_id(transaction::Ref{_Transaction}, id::AbstractString) + + err_code = ccall( + (:caosdb_transaction_transaction_retrieve_by_id, CaosDB.library_name), + Cint, + (Ref{_Transaction}, Cstring), + transaction, + id, + ) + + CaosDB.Exceptions.evaluate_return_code(err_code) +end + +""" + function add_retrieve_by_id( + transaction::Ref{_Transaction}, + ids::Vector{T}, + ) where {T<:AbstractString} + +Add a sub-request to retrieve several entities by their `ids` to the +given `transaction`. + +!!! info + + This does not execute the transaction. +""" +function add_retrieve_by_id( + transaction::Ref{_Transaction}, + ids::Vector{T}, +) where {T<:AbstractString} + + err_code = ccall( + (:caosdb_transaction_transaction_retrieve_by_ids, CaosDB.library_name), + Cint, + (Ref{_Transaction}, Ptr{Ptr{Cchar}}), + transaction, + ids, + ) + + CaosDB.Exceptions.evaluate_return_code(err_code) +end + + +""" + function add_query(transaction::Ref{_Transaction}, query::AbstractString) + +Add a query sub-request to the given `transaction`. + +!!! warning + + Only COUNT queris and FIND queries (and no SELECT queries) are + currently supported. + +!!! info + + This dows not execute the transaction +""" +function add_query(transaction::Ref{_Transaction}, query::AbstractString) + + err_code = ccall( + (:caosdb_transaction_transaction_query, CaosDB.library_name), + Cint, + (Ref{_Transaction}, Cstring), + transaction, + query, + ) + + CaosDB.Exceptions.evaluate_return_code(err_code) +end + end # Transaction diff --git a/test/runtests.jl b/test/runtests.jl index 9036bec2439f07eaeb86f36e05abc2e3110429b2..99a8e12390f27224508a49f9cead6ddd44b3cf19 100644 --- a/test/runtests.jl +++ b/test/runtests.jl @@ -71,15 +71,16 @@ using CaosDB @test CaosDB.Transaction.create_transaction() != nothing @test CaosDB.Transaction.create_transaction("default") != nothing conn = CaosDB.Connection.get_connection() - @test CaosDB.Transaction.create_transaction != nothing + @test CaosDB.Transaction.create_transaction(conn) != nothing # Retrieval works by a single id, by a list of ids, or by querying trans1 = CaosDB.Transaction.create_transaction() @test CaosDB.Transaction.add_retrieve_by_id(trans1, "some_id") == nothing trans2 = CaosDB.Transaction.create_transaction() - @test CaosDB.Transaction.add_retrieve_by_id(["id1", "id2", "id3"]) == nothing + @test CaosDB.Transaction.add_retrieve_by_id(trans2, ["id1", "id2", "id3"]) == + nothing trans3 = CaosDB.Transaction.create_transaction() - @test CaosDB.Transaction.add_query("FIND ENTITY WITH id=123") == nothing + @test CaosDB.Transaction.add_query(trans3, "FIND ENTITY WITH id=123") == nothing end