uruk.core
Marklogic XCC core functions: session management, querying, type conversion, transactions.
->content-capability
Mapping of keywords to content permission capability values. See https://docs.marklogic.com/javadoc/xcc/com/marklogic/xcc/ContentCapability.html
->doc-format
Mapping of keywords to allowed document formats. Used at insertion time. See https://docs.marklogic.com/javadoc/xcc/com/marklogic/xcc/DocumentFormat.html
->doc-repair-level
Mapping of keywords to document repair levels. Used at insertion time. See https://docs.marklogic.com/javadoc/xcc/com/marklogic/xcc/DocumentRepairLevel.html
->string-format
(->string-format s)
Returns a document format keyword describing given String.
->transaction-mode
DEPRECATED - see https://docs.marklogic.com/guide/relnotes/chap5#id_91389 Mapping of keywords to valid Session transaction modes. See https://docs.marklogic.com/javadoc/xcc/com/marklogic/xcc/Session.TransactionMode.html
->update-mode
Mapping of keywords and booleans to valid Session update modes. See https://docs.marklogic.com/javadoc/xcc/com/marklogic/xcc/Session.Update.html
->xml-str
(->xml-str xml)
Assumes that its input is valid XML in some format, returning that XML in its String representation. Accepts String, hiccup-style vectors, and clojure.data.xml.Element.
commit
(commit session)
Commit session
when current queries successfully finish.
configure-content-source
(configure-content-source content-source {:keys [default-logger preemptive-auth]})
Given a ContentSource object, modifies that object according to the given map of configuration options.
configure-session
(configure-session session {:keys [default-request-options logger user-object transaction-mode transaction-timeout auto-commit? update-mode], :as config-options})
Configures the given MarkLogic session
according to the given config-options
. See create-session
.
content-creation-options
(content-creation-options options)
Creates a ContentCreateOptions object (to pass to a ContentFactory newContent call) out of the given options map. See valid-content-creation-options
for supported keywords.
content-creation-options->map
(content-creation-options->map opts)
convert-types
(convert-types result-sequence & [type-mapping])
Return the result of applying type conversion to the given MarkLogic query result sequence. Default type mappings can be overridden (in part or in whole) with the optional parameter type-mapping
, which should contain a transformation function keyed by an XCC type string. See xml-type-str->conv-fn
above.
create-default-session
(create-default-session content-source)
(create-default-session content-source {:keys [default-request-options logger user-object transaction-mode transaction-timeout auto-commit? update-mode], :as config-options})
Returns a session according to the default login credentials of the given content-source
, which must be a com.marklogic.xcc.ContentSource object (see https://docs.marklogic.com/javadoc/xcc/com/marklogic/xcc/ContentSource.html), presumably created with one of Uruk’s make-*-content-source
functions. Optionally takes a map of config-options
to configure the session.
create-session
(create-session db-info)
(create-session db-info {:keys [default-request-options logger user-object transaction-mode transaction-timeout auto-commit? update-mode], :as config-options})
(create-session db-info content-source {:keys [default-request-options logger user-object transaction-mode transaction-timeout auto-commit? update-mode], :as config-options})
Create a Session for querying and transacting with. Parameter db-info
describing database connection information must include :uri key, and may optionally include connection information for :content-base (database name), and/or :user and :password.
See newSession
methods at https://docs.marklogic.com/javadoc/xcc/com/marklogic/xcc/ContentSource.html for detail on allowed parameter arrangements.
If optional options
map is passed, the session is configured accordingly. See https://docs.marklogic.com/javadoc/xcc/com/marklogic/xcc/Session.html for valid options. (Note that request options are distinct from session options, though default request options can be set for the session.)
If optional content-source
is passed, the Session is created from the given ContentSource rather than creating one from the database info URI.
element->content
(element->content uri element)
(element->content uri element options)
Given a clojure.data.xml.Element, returns a MarkLogic XCC Content object suitable for inserting to a database. Optionally takes a map of content creation options per content-creation-options
. Defaults to XML-formatted documents.
See https://docs.marklogic.com/javadoc/xcc/com/marklogic/xcc/Content.html and https://docs.marklogic.com/javadoc/xcc/com/marklogic/xcc/ContentFactory.html
execute-module
(execute-module session module)
(execute-module session module {:keys [options variables types shape]})
Execute the named module as a request to the database connection defined by the given session. Takes an optional configuration map describing request options
and variables
, desired shape
of the result, and overrides of default type conversion in xml-type-str->conv-fn
.
Options passed must be in valid-request-options
and conform to request-options
.
Variables may be passed as a map of Strings or with String names corresponding to maps describing the variable using mandatory key :value
and optional keys :namespace
and :type
.`
The shape of results is coerced using shape-results
if the :shape
key is passed. For example, a value of :single
will return only the first value.
Type conversion overrides must be a map using keys present in uruk.core/xml-type-str->conv-fn
and conform to use in convert-types
, that is, including values which are a function of one variable.
execute-xquery
(execute-xquery session query)
(execute-xquery session query {:keys [options variables types shape]})
Execute the given xquery query as a request to the database connection defined by the given session. Takes an optional configuration map describing request options
and variables
, desired shape
of the result, and overrides of default type conversion in xml-type-str->conv-fn
.
Options passed must be in valid-request-options
and conform to request-options
.
Variables may be passed as a map of Strings or with String names corresponding to maps describing the variable using mandatory key :value
and optional keys :namespace
and :type
.`
The shape of results is coerced using shape-results
if the :shape
key is passed. For example, a value of :single
will return only the first value.
Type conversion overrides must be a map using keys present in uruk.core/xml-type-str->conv-fn
and conform to use in convert-types
, that is, including values which are a function of one variable.
insert-element
(insert-element session uri element)
(insert-element session uri element options)
Inserts the given clojure.data.xml.Element element
at the given uri
to the database/content-base according determined by the current session
. Optionally takes a map of content creation options per content-creation-options
.
insert-string
(insert-string session uri s)
(insert-string session uri s options)
Inserts the given String s
at the given uri
to the database/content-base according determined by the current session
. Optionally takes a map of content creation options per content-creation-options
.
java->num
(java->num obj)
Reads a number from a numeric Java object of a type from com.marklogic.xcc.types. Returns nil if not a number. Designed for robust number-handling while preventing read-string security issues. Regex from http://stackoverflow.com/a/12285023/706499. See https://docs.marklogic.com/javadoc/xcc/com/marklogic/xcc/types/package-summary.html
java-json->clj-json
(java-json->clj-json java-json)
Given a MarkLogic XCC JSON object, returns a Clojure representation of its JSON data.
make-content-permissions
(make-content-permissions permissions)
Return an array of ContentPermissions decribing the given seq of content capability keys.
make-cp-content-source
(make-cp-content-source cxn-provider user password content-base)
(make-cp-content-source cxn-provider user password content-base {:keys [default-logger preemptive-auth]})
Given a ConnectionProvider, user, password, content-base, and an optional configuration map, returns a ContentSource object that will use the provided ConnectionProvider instance to obtain server connections.
WARNING from the Javadoc: ‘[This function] should only be used by advanced users. A misbehaving ConnectionProvider implementation can result in connection failures and potentially even data loss. Be sure you know what you’re doing.’
make-hosted-content-source
(make-hosted-content-source host port)
(make-hosted-content-source host port {:keys [user password content-base security-options default-logger preemptive-auth]})
Return a ContentSource object according to the given host
String and integer port
, and optionally a configuration map defining the user
and password
, content-base
, security-options
, and/or default Logger object and boolean flag for whether basic authentication should be attempted preemptively.
make-request-options
(make-request-options options)
Creates a Request Options object (to pass to a Request or a Session) out of the given options map. See valid-request-options
for supported keywords.
make-security-options
(make-security-options ssl-context)
(make-security-options ssl-context {:keys [protocols cipher-suites]})
Given an SSLContext object and, optionally, a configuration map describing cipher suites and/or protocols to enable, returns a MarkLogic SecurityOptions object configured accordingly, to be used in session or content source creation.
make-uri-content-source
(make-uri-content-source uri)
(make-uri-content-source uri {:keys [security-options default-logger preemptive-auth]})
Return a ContentSource object according to the given uri
and, optionally, a configuration map describing a SecurityOptions object, default Logger object, and boolean flag for whether basic authentication should be attempted preemptively. Accepts URI or string for uri
.
request-options->map
(request-options->map req-opts)
Given a RequestOptions object, returns a map describing those request options.
result->type
(result->type result)
Returns type string of the given query Result object. Currently assumes result is homogenous.
rollback
(rollback session)
Rollback a multi-statement transaction to reset any un-committed transactions that have already occured in that transaction; for example, delete any created items, restore any deleted items, revert back any edits, etc.
security-options->map
(security-options->map security-options)
Given a SecurityOptions object, returns a map describing its configuration.
session->map
(session->map session)
Returns a map describing configuration of the given Session object.
shape-results
(shape-results server-response shape)
Coerces the server’s MarkLogic query response to the (possibly nil
) shape
that the client would like the response to take. By default, returns the unchanged server response.
Recognized shapes include: :none - ignore the response :single - return just the first element of the response :single! - if the response is one element, return just that element; if not (i.e. if the response is more than one element) throw an error
spawn-module
(spawn-module session module)
(spawn-module session module {:keys [options variables]})
Send the named module to the server to be run asynchronously, as a request to the database connection defined by the given session.
Options passed must be in valid-request-options
and conform to request-options
.
Variables may be passed as a map of Strings or with String names corresponding to maps describing the variable using mandatory key :value
and optional keys :namespace
and :type
.`
See https://docs.marklogic.com/javadoc/xcc/com/marklogic/xcc/ModuleSpawn.html
string->content
(string->content uri s)
(string->content uri s options)
Given a String, returns a MarkLogic XCC Content object suitable for inserting to a database. Optionally takes a map of content creation options per content-creation-options
. Determines content format using ->string-format
.
See https://docs.marklogic.com/javadoc/xcc/com/marklogic/xcc/Content.html and https://docs.marklogic.com/javadoc/xcc/com/marklogic/xcc/ContentFactory.html
submit-request
(submit-request request-factory session query options variables types shape)
Construct, submit, and return raw results of request for the given session
using request-factory
and query
. Modify it with (possibly empty) options
and variables
maps. Applies type conversion to response according to defaults and xml-type-str->conv-fn
. Variables may be passed as a map of Strings or with String names corresponding to maps describing the variable using mandatory key :value
and optional keys :namespace
and :type
.`
user-credentials->map
(user-credentials->map user-credentials)
Given a UserCredentials object, returns a map describing its configuration. See also methods toHttpNegotiateAuth
and toHttpDigestAuth
.
valid-content-creation-options
Set of valid creation options for Content objects. See https://docs.marklogic.com/javadoc/xcc/com/marklogic/xcc/ContentCreateOptions.html
valid-request-options
Set of valid request options for Request objects. Can also be passed to Sessions as :default-request-options. See https://docs.marklogic.com/javadoc/xcc/com/marklogic/xcc/RequestOptions.html
valid-session-config-options
validate-session-config-options
(validate-session-config-options config-options)
Raises an error if the given configuration options are invalid for a MarkLogic session. See valid-session-config-options
and https://docs.marklogic.com/javadoc/xcc/com/marklogic/xcc/Session.html
variable-types
Mapping between Clojure keywords describing XML Schema types types and the Java representations of those types.
See https://docs.marklogic.com/javadoc/xcc/com/marklogic/xcc/types/ValueType.html
version
XCC release number. Auto-generated. See https://docs.marklogic.com/javadoc/xcc/com/marklogic/xcc/Version.html
xcc-type->xdm-conv-fn
Mapping from Clojure keywords describing XCC types to functions that will convert a Clojure value to an object appropriate for use in a MarkLogic XdmVariable.
xcc-types
Lookup table for XCC type information.
Includes all Clojure-relevant info about XCC types (and XML schema types relevant to MarkLogic XCC). Provides functions for conversion to and from XCC types and XdmVariable-suitable objects from Clojure.
Values are keyed by keyword describing the XCC type. Each value is organized as follows:
:ml->clj
maps to the function used to convert from MarkLogic to Clojure
:clj->xdm
maps to the function used to convert from Clojure to a value appropriate for use in an XDM variable
:xml-name
maps to the string used to refer to this type in XQuery (its XML schema name)
:xcc-type
maps to the corresponding com.marklogic.xcc.types.ValueType field
xdm-var->str
(xdm-var->str xdm-var)
Returns a String representation of the given XDM variable
xml-type-str->conv-fn
Default mapping from XML Schema type strings to Clojure functions that will convert such a value to Clojure types.
See https://docs.marklogic.com/javadoc/xcc/com/marklogic/xcc/types/package-summary.html