uruk.core — uruk 0.3.12

Marklogic XCC core functions: session management, querying, type conversion, transactions.

->content-capability clj

Mapping of keywords to content permission capability values. See https://docs.marklogic.com/javadoc/xcc/com/marklogic/xcc/ContentCapability.html

->doc-format clj

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 clj

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 clj

(->string-format s)

Returns a document format keyword describing given String.

->transaction-mode clj

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 clj

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 clj

(->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 clj

(commit session)

Commit session when current queries successfully finish.

configure-content-source clj

(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 clj

(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 clj

(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 clj

(content-creation-options->map opts)

convert-types clj

(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 clj

(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 clj

(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 clj

(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 clj

(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 clj

(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 clj

(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.

See https://docs.marklogic.com/javadoc/xcc/com/marklogic/xcc/Session.html#insertContent(com.marklogic.xcc.Content)

insert-string clj

(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.

See https://docs.marklogic.com/javadoc/xcc/com/marklogic/xcc/Session.html#insertContent(com.marklogic.xcc.Content)

java->num clj

(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 clj

(java-json->clj-json java-json)

Given a MarkLogic XCC JSON object, returns a Clojure representation of its JSON data.

make-content-permissions clj

(make-content-permissions permissions)

Return an array of ContentPermissions decribing the given seq of content capability keys.

make-cp-content-source clj

(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 clj

(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 clj

(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 clj

(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 clj

(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 clj

(request-options->map req-opts)

Given a RequestOptions object, returns a map describing those request options.

result->type clj

(result->type result)

Returns type string of the given query Result object. Currently assumes result is homogenous.

rollback clj

(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 clj

(security-options->map security-options)

Given a SecurityOptions object, returns a map describing its configuration.

session->map clj

(session->map session)

Returns a map describing configuration of the given Session object.

shape-results clj

(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 clj

(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 clj

(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 clj

(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 clj

(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 clj

Set of valid creation options for Content objects. See https://docs.marklogic.com/javadoc/xcc/com/marklogic/xcc/ContentCreateOptions.html

valid-request-options clj

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 clj

validate-session-config-options clj

(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 clj

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 clj

XCC release number. Auto-generated. See https://docs.marklogic.com/javadoc/xcc/com/marklogic/xcc/Version.html

xcc-type->xdm-conv-fn clj

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 clj

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 clj

(xdm-var->str xdm-var)

Returns a String representation of the given XDM variable

xml-type-str->conv-fn clj

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