Provides a virtual only interface for a connection. Allows the creation of a FakeConnection subclass, or a real Connection subclass. More...

#include <Connection.hpp>

Inheritance diagram for mlclient::IConnection:

Public Member Functions
MLCLIENT_API	IConnection ()=default
	Creates a Connection instance. More...

virtual	~IConnection ()=default

connection_configuration Connection configuration functions
virtual MLCLIENT_API void	configure (const std::string &hostname, const std::string &port, const std::string &username, const std::string &password, const bool usessl=false)=0

virtual MLCLIENT_API bool	connect ()=0
	Connects or tests the authentication in the connection. May not actually connect. More...

virtual MLCLIENT_API void	disconnect ()=0
	Frees up resources held by the connection, until the next call to connect. More...

virtual MLCLIENT_API void	setDatabaseName (const std::string &db)=0
	Sets the name of the database to query/update. Defaults to Documents. More...

virtual MLCLIENT_API std::string	getDatabaseName ()=0
	Returns the database name we're querying/updating. Defaults to Documents. More...

http_raw RAW HTTP commands
virtual MLCLIENT_API Response *	doGet (const std::string &pathAndQuerystring)=0
	Performs a HTTP GET Request against MarkLogic Server. More...

virtual MLCLIENT_API Response *	doPut (const std::string &pathAndQuerystring, const IDocumentContent &payload)=0
	Performs a HTTP PUT Request against MarkLogic Server. More...

virtual MLCLIENT_API Response *	doPost (const std::string &pathAndQuerystring, const IDocumentContent &payload)=0
	Performs a HTTP POST Request against MarkLogic Server. More...

virtual MLCLIENT_API Response *	doDelete (const std::string &pathAndQueryString)=0
	TODO multipart payload. More...

wrap_rest Convenience wrapper function calls for common MarkLogic REST API calls.
TODO PATCH and other HTTP synonyms
virtual MLCLIENT_API Response *	getDocument (const std::string &uri)=0
	Retrieves a document from the server, at the given document URI (MarkLogic unique document ID) More...

virtual MLCLIENT_API Response *	getDocument (Document &inout_document)=0
	TODO add optional call parameters (E.g. fetch properties also) More...

virtual MLCLIENT_API Response *	getDocumentContent (Document &inout_document)=0
	Populates the content of the specified document (MUST have a uri). More...

virtual MLCLIENT_API Response *	getDocumentProperties (Document &inout_document)=0
	Populates the properties of the specified document (MUST have a uri). More...

virtual MLCLIENT_API Response *	getDocumentPermissions (Document &inout_document)=0
	Populates the permissions of the specified document (MUST have a uri). More...

virtual MLCLIENT_API Response *	saveDocumentContent (const std::string &uri, const IDocumentContent &payload)=0
	Saves a document to MarkLogic (either as new or an update), at the given document URI (MarkLogic unique document ID) More...

virtual MLCLIENT_API Response *	saveDocuments (const DocumentSet &documents, const long startPosInclusive, const long endPosInclusive)=0
	Saves a set of documents as a single batch to MarkLogic Server. More...

virtual MLCLIENT_API Response *	saveDocument (const Document &doc)=0
	Saves a document to MarkLogic (either as new or an update), at the given document URI (MarkLogic unique document ID) More...

virtual MLCLIENT_API Response *	deleteDocument (const std::string &uri)=0
	Deletes the specified document by URI. More...

virtual MLCLIENT_API Response *	search (const SearchDescription &desc)=0
	Performs a search against the MarkLogic database given the provided search query, text and options. More...

virtual MLCLIENT_API Response *	searchExtension (const std::string &extensionName, const SearchDescription &desc)=0
	Performs a search against a REST extension that is compatible with POST /v1/search (i.e. Connection::search) More...

virtual MLCLIENT_API Response *	saveSearchOptions (const std::string &optionsName, const IDocumentContent *optionsDoc)=0
	Saves search options to the server. More...

virtual MLCLIENT_API Response *	values (const std::string &valuesName, const std::string &optionsName)=0
	Performs a values lookup in MarkLogic Server, returning the top values from the lexicon as per the search options configuration used. More...

virtual MLCLIENT_API Response *	valuesExtension (const std::string &extensionName, const std::string &valuesName, const std::string &optionsName, const SearchDescription &desc)=0
	Performs a values against a REST extension that is compatible with POST /v1/search (i.e. Connection::search) More...

virtual MLCLIENT_API Response *	listRootCollections ()=0
	Lists the top level collections. I.e. ones starting without a / or ones starting with a / but not containing a / character. More...

virtual MLCLIENT_API Response *	listCollections (const std::string &parentCollection)=0
	Lists the immediate child collections of the specified parent Collections. More...

Detailed Description

Provides a virtual only interface for a connection. Allows the creation of a FakeConnection subclass, or a real Connection subclass.

Author: Adam Fowler adam..nosp@m.fowe.nosp@m.r@mar.nosp@m.klog.nosp@m.ic.co.nosp@m.m

Since: 8.0.0

Date: 2016-05-15

Constructor & Destructor Documentation

MLCLIENT_API mlclient::IConnection::IConnection ( )

default

Creates a Connection instance.

Defaults connection to admin/admin, localhost, nossl, port 8002, and the Documents database.

Since: 8.0.0

virtual mlclient::IConnection::~IConnection ( )

virtualdefault

Destroys a Connection instance.

Member Function Documentation

virtual MLCLIENT_API void mlclient::IConnection::configure	(	const std::string &	hostname,
		const std::string &	port,
		const std::string &	username,
		const std::string &	password,
		const bool	usessl = `false`
	)

pure virtual

Configures this connection, providing connection override information - host, port, username, password and SSL usage

Since: 8.0.0

Parameters

[in]	hostname	The hostname or IP address of the MarkLogic Server (or load balancer) to connect to
[in]	port	A String representing the (numerical) port number of the MarkLogic Server (or load balancer) to connect to
[in]	username	The username of the used to connect to MarkLogic Server as
[in]	password	The plain text password used to authenticate the user to MarkLogic server with
[in]	usessl	A bool representation whether to use SSL (i.e. a HTTPS url) or not

Implemented in mlclient::Connection, and mlclient::internals::FakeConnection.

virtual MLCLIENT_API bool mlclient::IConnection::connect ( )

pure virtual

Connects or tests the authentication in the connection. May not actually connect.

Note: Should be called prior to any use of functions. Is not called for the developer

Implemented in mlclient::Connection, and mlclient::internals::FakeConnection.

virtual MLCLIENT_API Response* mlclient::IConnection::deleteDocument ( const std::string & uri )

pure virtual

Deletes the specified document by URI.

Parameters

[in] uri The document URI to delete

Returns: A unique_ptr for the Response object. The caller is repsonsible for deleting the pointer.

Test:: Tested by ConnectionDocumentCrudTest::testDeleteJson and ConnectionDocumentCrudTest::testDeleteXml and ConnectionDocumentCrudTest::testDeleteText

Exceptions

NoCredentialsException The credentials for the Connection were not accepted by MarkLogic Server, or permission is denied for this request.

Since: 8.0.0

Implemented in mlclient::Connection, and mlclient::internals::FakeConnection.

virtual MLCLIENT_API void mlclient::IConnection::disconnect ( )

pure virtual

Frees up resources held by the connection, until the next call to connect.

Note: Should be called by a class' destructor

Implemented in mlclient::Connection, and mlclient::internals::FakeConnection.

virtual MLCLIENT_API Response* mlclient::IConnection::doDelete ( const std::string & pathAndQueryString )

pure virtual

TODO multipart payload.

Performs a HTTP DELETE Request against MarkLogic Server.

Allows mlclient based applications to call any arbitrary REST endpoint on MarkLogic. Just in case we don't yet provide a specific convenience method to invoke it.

Performs a HTTP DELETE REST request to an arbitrary URL on MarkLogic Server

Since: 8.0.0

Parameters

[in] pathAndQueryString the path and query string for the entire delete request. E.g. /v1/documents?uri=/my/doc.json

Returns: A unique_ptr for a Response instance. The caller is responsible for destroying the pointer.

Exceptions

NoCredentialsException The credentials for the Connection were not accepted by MarkLogic Server, or permission is denied for this request.

Note: This function is not limited to the REST API, and can be used for the management REST API or any arbitrary MarkLogic web application URL.

Implemented in mlclient::Connection, and mlclient::internals::FakeConnection.

virtual MLCLIENT_API Response* mlclient::IConnection::doGet ( const std::string & pathAndQuerystring )

pure virtual

Performs a HTTP GET Request against MarkLogic Server.

Allows mlclient based applications to call any arbitrary REST endpoint on MarkLogic. Just in case we don't yet provide a specific convenience method to invoke it.

Performs a RESTful HTTP GET request to an arbitrary URL on MarkLogic Server

Since: 8.0.0

Parameters

[in] pathAndQueryString the path and query string for the entire get request. E.g. /v1/search?options=myoptions

Returns: A unique_ptr for a Response instance. The caller is responsible for destroying the pointer.

Exceptions

NoCredentialsException The credentials for the Connection were not accepted by MarkLogic Server, or permission is denied for this request.

Note: This function is not limited to the REST API, and can be used for the management REST API or any arbitrary MarkLogic web application URL.

Implemented in mlclient::Connection, and mlclient::internals::FakeConnection.

virtual MLCLIENT_API Response* mlclient::IConnection::doPost	(	const std::string &	pathAndQuerystring,
		const IDocumentContent &	payload
	)

pure virtual

Performs a HTTP POST Request against MarkLogic Server.

Allows mlclient based applications to call any arbitrary REST endpoint on MarkLogic. Just in case we don't yet provide a specific convenience method to invoke it.

Performs a RESTful HTTP POST request to an arbitrary URL on MarkLogic Server

Since: 8.0.0

Parameters

[in]	pathAndQueryString	the path and query string for the entire post request. E.g. /v1/search?options=myoptions
[in]	payload	The DocumentContent to send to MarkLogic Server

Returns: A unique_ptr for a Response instance. The caller is responsible for destroying the pointer.

Exceptions

NoCredentialsException The credentials for the Connection were not accepted by MarkLogic Server, or permission is denied for this request.

Note: This function is not limited to the REST API, and can be used for the management REST API or any arbitrary MarkLogic web application URL.

Implemented in mlclient::Connection, and mlclient::internals::FakeConnection.

virtual MLCLIENT_API Response* mlclient::IConnection::doPut	(	const std::string &	pathAndQuerystring,
		const IDocumentContent &	payload
	)

pure virtual

Performs a HTTP PUT Request against MarkLogic Server.

Allows mlclient based applications to call any arbitrary REST endpoint on MarkLogic. Just in case we don't yet provide a specific convenience method to invoke it.

Performs a RESTful HTTP PUT request to an arbitrary URL on MarkLogic Server

Since: 8.0.0

Parameters

[in]	pathAndQueryString	the path and query string for the entire put request. E.g. /v1/search?options=myoptions
[in]	payload	The DocumentContent to send to MarkLogic Server

Returns: A unique_ptr for a Response instance. The caller is responsible for destroying the pointer.

Exceptions

NoCredentialsException The credentials for the Connection were not accepted by MarkLogic Server, or permission is denied for this request.

Note: This function is not limited to the REST API, and can be used for the management REST API or any arbitrary MarkLogic web application URL.

Implemented in mlclient::Connection, and mlclient::internals::FakeConnection.

virtual MLCLIENT_API std::string mlclient::IConnection::getDatabaseName ( )

pure virtual

Returns the database name we're querying/updating. Defaults to Documents.

Since: 8.0.0

Returns: A string representation of the database name (not internal MarkLogic database numeric ID)

Implemented in mlclient::Connection, and mlclient::internals::FakeConnection.

virtual MLCLIENT_API Response* mlclient::IConnection::getDocument ( const std::string & uri )

pure virtual

Retrieves a document from the server, at the given document URI (MarkLogic unique document ID)

Performs a GET /v1/documents?uri HTTP call

Parameters

[in] uri The URI of the document to fetch from MarkLogic Server

Returns: A unique_ptr for the Response object. The caller is repsonsible for deleting the pointer.

Test:: Tested by ConnectionDocumentCrudTest::testGetJson and ConnectionDocumentCrudTest::testGetXml and ConnectionDocumentCrudTest::testGetText

Exceptions

NoCredentialsException The credentials for the Connection were not accepted by MarkLogic Server, or permission is denied for this request.

Since: 8.0.0

Implemented in mlclient::Connection, and mlclient::internals::FakeConnection.

virtual MLCLIENT_API Response* mlclient::IConnection::getDocument ( Document & inout_document )

pure virtual

TODO add optional call parameters (E.g. fetch properties also)

Retrieves a document from the server, at the given document URI (MarkLogic unique document ID, within the Document object)

Note: This method differs from getDocument(const std::string& uri) in that it populates the document specified, rather than returning a document from the method (or within the response). This method fetches ALL of document content AND properties AND collections AND permissions

Performs a GET /v1/documents?uri HTTP call, fetching all document information.

Parameters

[in,out] inout_document The document to fetch from MarkLogic Server. MUST have a URI.

Returns: A unique_ptr for the Response object. The caller is repsonsible for deleting the pointer.

Exceptions

NoCredentialsException The credentials for the Connection were not accepted by MarkLogic Server, or permission is denied for this request.

Since: 8.0.2

Implemented in mlclient::Connection.

virtual MLCLIENT_API Response* mlclient::IConnection::getDocumentContent ( Document & inout_document )

pure virtual

Populates the content of the specified document (MUST have a uri).

See getDocument(Document&) for details.

Implemented in mlclient::Connection.

virtual MLCLIENT_API Response* mlclient::IConnection::getDocumentPermissions ( Document & inout_document )

pure virtual

Populates the permissions of the specified document (MUST have a uri).

See getDocument(Document&) for details.

Implemented in mlclient::Connection.

virtual MLCLIENT_API Response* mlclient::IConnection::getDocumentProperties ( Document & inout_document )

pure virtual

Populates the properties of the specified document (MUST have a uri).

See getDocument(Document&) for details.

Implemented in mlclient::Connection.

virtual MLCLIENT_API Response* mlclient::IConnection::listCollections ( const std::string & parentCollection )

pure virtual

Lists the immediate child collections of the specified parent Collections.

Note: Parent collection must start with a /; Requires the Collection Lexicon to be enabled on the MarkLogic Database

Test:: Tested indirectly by ConnectionCollectionsTest::testListRootCollections (the Connection::listRootCollections function calls this function directly)

Since: 8.0.2

Implemented in mlclient::Connection.

virtual MLCLIENT_API Response* mlclient::IConnection::listRootCollections ( )

pure virtual

Lists the top level collections. I.e. ones starting without a / or ones starting with a / but not containing a / character.

Note: Requires the Collection Lexicon to be enabled on the MarkLogic Database

Test:: Tested by ConnectionCollectionsTest::testListRootCollections

Since: 8.0.2

Implemented in mlclient::Connection.

virtual MLCLIENT_API Response* mlclient::IConnection::saveDocument ( const Document & doc )

pure virtual

Saves a document to MarkLogic (either as new or an update), at the given document URI (MarkLogic unique document ID)

Performs a call to PUT /v1/documents?ext in order to save a Document to MarkLogic Server

Test:: Underlying code tested By DocumentBatchWriterTest

Parameters

[in] Document The Document to send to MarkLogic Server. Must have a URI and Content DocumentContent instance.

Returns: A unique_ptr for the Response object. The caller is repsonsible for deleting the pointer.

Exceptions

NoCredentialsException The credentials for the Connection were not accepted by MarkLogic Server, or permission is denied for this request.

Since: 8.0.2

Implemented in mlclient::Connection.

virtual MLCLIENT_API Response* mlclient::IConnection::saveDocumentContent	(	const std::string &	uri,
		const IDocumentContent &	payload
	)

pure virtual

Saves a document to MarkLogic (either as new or an update), at the given document URI (MarkLogic unique document ID)

Performs a call to PUT /v1/documents?ext in order to save a Document to MarkLogic Server

Parameters

[in]	uri	The URI of the document to save to MarkLogic Server
[in]	payload	The DocumentContent to send to MarkLogic Server

Returns: A unique_ptr for the Response object. The caller is repsonsible for deleting the pointer.

Test:: Tested by ConnectionDocumentCrudTest::testSaveJson and ConnectionDocumentCrudTest::testSaveXml and ConnectionDocumentCrudTest::testSaveText

Exceptions

NoCredentialsException The credentials for the Connection were not accepted by MarkLogic Server, or permission is denied for this request.

Note: This function call was renamed in 8.0.2 to saveDocumentContent from saveDocument to better reflect its usage.

Since: 8.0.0

Implemented in mlclient::Connection, and mlclient::internals::FakeConnection.

virtual MLCLIENT_API Response* mlclient::IConnection::saveDocuments	(	const DocumentSet &	documents,
		const long	startPosInclusive,
		const long	endPosInclusive
	)

pure virtual

Saves a set of documents as a single batch to MarkLogic Server.

See DocumentSet and DocumentBatchHelper and DocumentBatchWriter for how to use this call.

Note: Uses a single REST call and multi-part MIME support in the REST API

Test:: Tested By DocumentBatchWriterTest

Parameters

documents	The set of documents to upload
startPosInclusive	The first index of the document in the set to upload
endPostInclusive	The last index of the document in the set to upload

Returns: The Response object

Since: 8.0.2

Implemented in mlclient::Connection.

virtual MLCLIENT_API Response* mlclient::IConnection::saveSearchOptions	(	const std::string &	optionsName,
		const IDocumentContent *	optionsDoc
	)

pure virtual

Saves search options to the server.

Parameters

[in]	optionsName	The name of the options on the server
[in]	optionsDoc	The document containing the options

Test:: Tested by SearchOptionsBuilderTest::testSave

Since: 8.0.2

Implemented in mlclient::Connection.

virtual MLCLIENT_API Response* mlclient::IConnection::search ( const SearchDescription & desc )

pure virtual

Performs a search against the MarkLogic database given the provided search query, text and options.

Uses a SearchDescription value object to wrap complex search parameters for MarkLogic Server.

Performs a POST /v1/search HTTP POST to MarkLogic Server

Parameters

[in] desc The SearchDescription defining the search, options, and query string

Returns: A unique_ptr for the Response object. The caller is repsonsible for deleting the pointer.

Test:: Tested directly by ConnectionSearchTest::testEmptySearch and ConnectionSearchTest::testQueryText and ConnectionSearchTest::testWordQuery Tested indirectly by tests within SearchBuilderTest and SearchResultSetTest

Exceptions

NoCredentialsException The credentials for the Connection were not accepted by MarkLogic Server, or permission is denied for this request.

Since: 8.0.0

Implemented in mlclient::Connection, and mlclient::internals::FakeConnection.

virtual MLCLIENT_API Response* mlclient::IConnection::searchExtension	(	const std::string &	extensionName,
		const SearchDescription &	desc
	)

pure virtual

Performs a search against a REST extension that is compatible with POST /v1/search (i.e. Connection::search)

Note: Useful when your extension places extra criteria on the search that the REST API does not support.; This could be used to effectively create 'stored procedures' that took a search to restrict the documents the work occurs over, returning a result set just like Connection::search (i.e. POST /v1/search)

See also Connection::valuesExtension for similar functionality for aggregate/values extensions

Parameters

[in]	extensionName	The REST API extension name (file name without .xqy or .sjs) to invoke
[in]	desc	The SearchDescription defining the search, options, and query string

Since: 8.0.2

Implemented in mlclient::Connection.

virtual MLCLIENT_API void mlclient::IConnection::setDatabaseName ( const std::string & db )

pure virtual

Sets the name of the database to query/update. Defaults to Documents.

Since: 8.0.0

Parameters

[in] The string name (not internal MarkLogic numeric ID) of the database to query.

Implemented in mlclient::Connection, and mlclient::internals::FakeConnection.

virtual MLCLIENT_API Response* mlclient::IConnection::values	(	const std::string &	valuesName,
		const std::string &	optionsName
	)

pure virtual

Performs a values lookup in MarkLogic Server, returning the top values from the lexicon as per the search options configuration used.

Note: What is returned from the call is entirely dependent upon the search options configuration used.; Invokes GET /v1/values/VALUESNAME?options=OPTIONSNAME

Test:: Tested by ConnectionValuesTest::testValues

Parameters

[in]	valuesName	The name of the values Configuration within the search options to use
[in]	optionsName	The name of the installed search options to specify (no default)

Since: 8.0.2

Implemented in mlclient::Connection.

virtual MLCLIENT_API Response* mlclient::IConnection::valuesExtension	(	const std::string &	extensionName,
		const std::string &	valuesName,
		const std::string &	optionsName,
		const SearchDescription &	desc
	)

pure virtual

Performs a values against a REST extension that is compatible with POST /v1/search (i.e. Connection::search)

Note: Useful when your extension places extra criteria on the search that the REST API does not support.; This could be used to effectively create 'stored procedures' that took a search to restrict the documents the work occurs over, returning a result set just like Connection::search (i.e. POST /v1/search)

See also Connection::searchExtension for similar functionality for aggregate/values extensions

Invokes POST /v1/values/VALUESNAME?options=OPTIONSNAME and not GET

Note: Because the values endpoint takes a name in the URL and REST extensions do not support this, the valuesName variable is passed to the 'values' parameter on the querystring of the request.

Test:: Tested by ConnectionValuesTest::testValuesExtension

Parameters

[in]	extensionName	The REST API extension name (file name without .xqy or .sjs) to invoke
[in]	valuesName	The name of the values Configuration within the search options to use
[in]	optionsName	The name of the installed search options to specify (no default)
[in]	desc	The SearchDescription defining the search, options, and query string

Since: 8.0.2

Implemented in mlclient::Connection.

The documentation for this class was generated from the following file:

include/mlclient/Connection.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation