Improve documentation and port copyDataObjectsByValue with SWIG

Renamed parameters for clarity in copyToDataspace and copyDataObjectsByValue methods, updated method documentation for accuracy and detail, and added copyDataObjectsByValue in SWIG interface.

Author: philippeVerney

cmake/swigEtp1_2Include.i.in

@@ -1943,37 +1943,37 @@ namespace ETP_NS
 		std::vector<Energistics::Etp::v12::Datatypes::Object::Dataspace> getDataspaceInfo(const std::map<std::string, std::string>& dataspaceUris);
 
 		/**
-		* Copy by reference some dataspaces into another one.
+		* A customer sends to a store to lock or unlock one or more dataspaces.
 		* This function should be used with caution if Dataspace OSDU Handlers have been overidden.
-		* It actually sends a message and block the current thread until a response has been received from the store.
+		* It actually sends a message and blocks the current thread until a response has been received from the store.
+		* An OSDU locked dataspace will have its custom data "locked" to true. It will also have its custom datm "read-only" to true for all users.
+		* As a reminder, a custom data "read-only" can be true with a custom data "locked" to false in case the dataspace is not locked but in read only for the particular current ETP user.
 		*
-		* @param sourceDataspaceUris  ETP general map : One each for each source dataspace to be copied. They are identified by their URI.
-		* @param targetDataspaceUri  The URI of the ETP dataspace where the sourceDataspaces have to be copied by reference.
-		* @param return	The map keys corresponding to the dataspaces which have been successfully copied into the target dataspace.
-		*/
-		std::vector<std::string> copyDataspacesContent(const std::map<std::string, std::string>& sourceDataspaceUris, const std::string& targetDataspaceUri);
+		* @param dataspaceUris	ETP general map where the values must be the URIs for the dataspaces the customer wants to lock or unlock.
+		* @param lock			true for locking the dataspaces, false to unlock the dataspaces
+		std::vector<std::string> lockDataspaces(const std::map<std::string, std::string>& dataspaceUris, bool lock);
 
 		/**
-		* A customer sends to a store to lock or unlock one or more dataspaces.
+		* Copy by reference some dataspaces into another one.
 		* This function should be used with caution if Dataspace OSDU Handlers have been overidden.
-		* It actually sends a message and block the current thread until a response has been received from the store.
+		* It actually sends a message and blocks the current thread until a response has been received from the store.
 		*
-		* @param dataspaceUris  ETP general map where the values must be the URIs for the dataspaces the customer wants to lock or unlock.
-		* @param lock true for locking the dataspaces, false to unlock the dataspaces
-		* @param return	The map keys corresponding to the dataspaces which have been successfully locked or unlocked.
+		* @param sourceDataspaceUris	ETP general map : One each for each source dataspace to be copied. They are identified by their URI.
+		* @param targetDataspaceUri		The URI of the ETP dataspace where the sourceDataspaces have to be copied by reference.
+		* @param return					The map keys corresponding to the dataspaces which have been successfully copied into the target dataspace.
 		*/
-		std::vector<std::string> lockDataspaces(const std::map<std::string, std::string>& dataspaceUris, bool lock);
+		std::vector<std::string> copyDataspacesContent(const std::map<std::string, std::string>& sourceDataspaceUris, const std::string& targetDataspaceUri);
 
 		/**
 		* Copy by reference some dataobjects into another dataspace.
 		* This function should be used with caution if Dataspace OSDU Handlers have been overidden.
-		* It actually sends a message and block the current thread until a response has been received from the store.
+		* It actually sends a message and blocks the current thread until a response has been received from the store.
 		*
-		* @param sourceUris  ETP general map : One each for each source dataobject to be copied. They are identified by their URI.
-		* @param targetDataspaceUri  The URI of the ETP dataspace where the source dataobjects have to be copied by reference.
-		* @param return	The map keys corresponding to the dataobjects which have been successfully copied into the target dataspace.
+		* @param sourceDataobjectUris	ETP general map : One for each source dataobject to be copied. They are identified by their URI.
+		* @param targetDataspaceUri		The URI of the ETP dataspace where the source dataobjects have to be copied by reference.
+		* @param return					The map keys corresponding to the dataobjects which have been successfully copied into the target dataspace.
 		*/
-		std::vector<std::string> copyToDataspace(const std::map<std::string, std::string>& sourceUris, const std::string& targetDataspaceUri);
+		std::vector<std::string> copyToDataspace(const std::map<std::string, std::string>& sourceDataobjectUris, const std::string& targetDataspaceUri);
 
 		/****************
 		*** DISCOVERY ***
@@ -2051,6 +2051,26 @@ namespace ETP_NS
 		*/
 		std::vector<std::string> deleteDataObjects(const std::map<std::string, std::string>& uris);
 
+		/*********************
+		***** STORE OSDU *****
+		**********************/
+
+		/**
+		* A customer sends to a store to copy by value a dataobject in the same dataspace with potentially some of its sources based on their datatypes.
+		* This function should be used with caution if Store OSDU Handlers have been overidden.
+		* It actually sends a message and blocks the current thread until a response has been received from the store.
+		*
+		* @param sourceDataobjectUri	The URI of the dataobject to be copied.
+		* @param sourcesDepth			The "depth" or how many "levels" (or "jumps") in the data model (graph) from the starting point (specified by the URI) that you want to copy
+		*								Depth MUST always be greater than zero.
+		* @param dataObjectTypes		Optionally, specify the types of data objects that you want to copy.
+		*								The default is an empty array, which means ALL data types negotiated for the current ETP session.
+		*								They ARE case sensitive. EXAMPLES: "witsml20.Well", "witsml20.Wellbore", "prodml21.WellTest", "resqml20.obj_TectonicBoundaryFeature", "eml21.DataAssuranceRecord"
+		*								To indicate that all data objects within a data schema version are supported, you can use a star (*) as a wildcard, EXAMPLE: "witsml20.*", "prodml21.*", "resqml20.*"
+		* @param return					The received dataobjects in a map where the key makes the link between the asked uris and the received dataobjects.
+		*/
+		std::vector<std::string> copyDataObjectsByValue(const std::string& sourceDataobjectUri, int32_t sourcesDepth = 0, const std::vector<std::string>& dataObjectTypes = {});
+
 		/****************
 		** TRANSACTION **
 		****************/

src/etp/AbstractSession.cpp

@@ -276,15 +276,15 @@ std::vector<std::string> AbstractSession::lockDataspaces(const std::map<std::str
 	return result;
 }
 
-std::vector<std::string> AbstractSession::copyToDataspace(const std::map<std::string, std::string>& sourceUris, const std::string& targetDataspaceUri)
+std::vector<std::string> AbstractSession::copyToDataspace(const std::map<std::string, std::string>& sourceDataobjectUris, const std::string& targetDataspaceUri)
 {
 	std::shared_ptr<DataspaceOSDUHandlers> handlers = getDataspaceOSDUProtocolHandlers();
 	if (handlers == nullptr) {
 		throw std::logic_error("You did not register any dataspace OSDU protocol handlers.");
 	}
 
 	Energistics::Etp::v12::Protocol::DataspaceOSDU::CopyToDataspace msg;
-	msg.uris = sourceUris;
+	msg.uris = sourceDataobjectUris;
 	msg.dataspaceUri = targetDataspaceUri;
 	sendAndBlock(msg, 0, 0x02);
 	std::vector<std::string> result = handlers->getSuccessKeys();
@@ -441,15 +441,15 @@ std::vector<std::string> AbstractSession::deleteDataObjects(const std::map<std::
 ***** STORE OSDU ****
 *********************/
 
-std::vector<std::string> AbstractSession::copyDataObjectsByValue(const std::string& uri, int32_t sourcesDepth, const std::vector<std::string>& dataObjectTypes)
+std::vector<std::string> AbstractSession::copyDataObjectsByValue(const std::string& sourceDataobjectUri, int32_t sourcesDepth, const std::vector<std::string>& dataObjectTypes)
 {
 	std::shared_ptr<StoreOSDUHandlers> handlers = getStoreOSDUProtocolHandlers();
 	if (handlers == nullptr) {
 		throw std::logic_error("You did not register any store OSDU protocol handlers.");
 	}
 
 	Energistics::Etp::v12::Protocol::StoreOSDU::CopyDataObjectsByValue msg;
-	msg.uri = uri;
+	msg.uri = sourceDataobjectUri;
 	msg.sourcesDepth = sourcesDepth;
 	msg.dataObjectTypes = dataObjectTypes;
 	sendAndBlock(msg, 0, 0x02);