DHF Server-Side Library

The /MarkLogic/data-hub-framework/dhf.xqy library module exposes functions to make interacting with the Data Hub Framework from your XQuery or JavaScript code easier.

Including the Library

JavaScript
XQuery

const dhf = require('/data-hub/4/dhf.xqy');

import module namespace dhf = "http://marklogic.com/dhf" at "/data-hub/4/dhf.xqy";

DHF-LIB Functions

Run
Run Writer
Make Envelope
Make Legacy Envelope
Context
Content Context
Headers Context
Triples Context
Writer Context
Add Trace Input
Log Trace

Run

Runs a given function as a plugin. This method provides tracing around your function. Tracing will catch uncaught exceptions and log them into the traces database.

declare function dhf:run($context as json:object, $func)

Parameters

context - the context for this plugin
func - the function to run

Returns

returns whatever your function returns

const dhf = require('/data-hub/4/dhf.xqy');

var context = dhf.context('My Plugin');
var result = dhf.run(context, function() {
  return 1;
});

import module namespace dhf = "http://marklogic.com/dhf"
  at "/data-hub/4/dhf.xqy";

let $context := dhf:context("My Plugin")
let $result := dhf:run($context, function() {
  return 1
})
return
  $result

Run Writer

Runs a writer plugin. This function is needed to run a writer in update mode. All of the DHF plugins run in query-only mode and thus cannot persist data. Running your writer with this function allows you to persist data.

declare function dhf:run-writer($writer-function, $id as xs:string+, $envelope as item(), $options as map:map)

Parameters

writer-function - the writer function to run. It must be an xdmp:function. See the examples below for more info.
id - the id for the current flow execution
envelope - the envelope to write
options - a map:map of options

Usage

JavaScript
XQuery

const dhf = require('/data-hub/4/dhf.xqy');
const writerPlugin = require('./writer.sjs');

// we are hand waving how the envelope gets constructed
var envelope = {};

/*
 note how we refer to the path of the writer sjs module. For this to work
 your sjs module must export the function properly.

 function write(id, envelope, options) {
 }
 module.exports = write;
*/

dhf.runWriter(writerPlugin, id, envelope, options);

import module namespace dhf = "http://marklogic.com/dhf"
  at "/data-hub/4/dhf.xqy";
import module namespace writer = "http://marklogic.com/data-hub/plugins" 
  at "writer.xqy";

let $envelope := <envelope/>
return
  (:
  : writers must conform to this signature
  :
  : declare function plugin:write($id as xs:string, $envelope as node(), $options as map:map) as empty-sequence()
  :)
  dhf:run-writer(xdmp:function(xs:QName("writer:write")), $id, $envelope, $options)

Make Envelope

Creates an envelope in the desired format (XML or JSON). If the data format is XML, then the namespace is http://marklogic.com/entity-services.

declare function dhf:make-envelope($content, $headers, $triples, $data-format) as document-node()

Parameters

content - the content section of the envelope
headers - the headers section of the envelope
triples - the triples section of the envelope
data-format - the format to use for making the envelope (xml json)

Returns

Either an XML or JSON envelope (depending on data-format).

Usage

JavaScript
XQuery

const dhf = require('/data-hub/4/dhf.xqy');

var content = { a: 'a!' };
var headers = {
  header1: 1,
  header2: 2
};
var triples = [
  sem.triple('subject1', 'predicate1', 'object1'),
  sem.triple('subject2', 'predicate2', 'object2')
];
var result = dhf.run(context, function() {
  return 1;
});

var dataFormat = 'json' // can also be 'xml'
var envelope = dhf:makeEnvelope(content, headers, triples, dataFormat);

import module namespace dhf = "http://marklogic.com/dhf"
  at "/data-hub/4/dhf.xqy";

let $content := <a>a!</a>
let $headers := (<header1>1</header1>, <header1>2</header2>)
let $triples := (
  sem:triple("subject1", "predicate1", "object1"),
  sem:triple("subject2", "predicate2", "object2")
)
let $data-format := "xml" (: can also be "json" :)
let $envelope := dhf:make-envelope($content, $headers, $triples, $data-format)
return
  $envelope

Make Legacy Envelope

Creates a legacy envelope in the desired format (XML or JSON). If the data format is XML then the namespace is http://marklogic.com/data-hub/envelope. This function is for users who upgraded from 1.x and have legacy envelopes already in production.

declare function dhf:make-legacy-envelope($content, $headers, $triples, $data-format) as document-node()

Parameters

content - the content section of the envelope
headers - the headers section of the envelope
triples - the triples section of the envelope
data-format - the format to use for making the envelope (xml json)

Returns

Either an XML or JSON envelope (depending on data-format).

Usage

JavaScript
XQuery

const dhf = require('/data-hub/4/dhf.xqy');

var content = { a: 'a!' };
var headers = {
  header1: 1,
  header2: 2
};
var triples = [
  sem.triple('subject1', 'predicate1', 'object1'),
  sem.triple('subject2', 'predicate2', 'object2')
];
var result = dhf.run(context, function() {
  return 1;
});

var dataFormat = 'json' // can also be 'xml'
var envelope = dhf:makeLegacyEnvelope(content, headers, triples, dataFormat);

import module namespace dhf = "http://marklogic.com/dhf"
  at "/data-hub/4/dhf.xqy";

let $content := <a>a!</a>
let $headers := (<header1>1</header1>, <header1>2</header2>)
let $triples := (
  sem:triple("subject1", "predicate1", "object1"),
  sem:triple("subject2", "predicate2", "object2")
)
let $data-format := "xml" (: can also be "json" :)
let $envelope := dhf:make-legacy-envelope($content, $headers, $triples, $data-format)
return
  $envelope

Context

Creates a generic context for use in any plugin. Contexts are passed to the the Run function. A Context defines information needed for proper tracing.

declare function dhf:context($label as xs:string) as json:object

Parameters

label - the label to give this plugin for tracing

Returns

A context object for use in the Run function

Usage

JavaScript
XQuery

const dhf = require('/data-hub/4/dhf.xqy');

var context = dhf.context('My Plugin');
var result = dhf.run(context, function() {
  return 1;
});

import module namespace dhf = "http://marklogic.com/dhf"
  at "/data-hub/4/dhf.xqy";

let $context := dhf:context("My Plugin")
let $result := dhf:run($context, function() {
  return 1
})
return
  $result

Content Context

Creates a context for a content plugin. This is a convenience method for Context and merely uses the label “content”.

declare function dhf:content-context([$raw-content]) as json:object

Parameters

raw-content (optional) - the raw content passed into an input flow

Returns

A context object for use in the Run function. This context object contains the label “content”

Usage

JavaScript
XQuery

const dhf = require('/data-hub/4/dhf.xqy');

var context = dhf.contentContext();
var result = dhf.run(context, function() {
  return 1;
});

import module namespace dhf = "http://marklogic.com/dhf"
  at "/data-hub/4/dhf.xqy";

let $context := dhf:content-context()
let $result := dhf:run($context, function() {
  return 1
})
return
  $result

Headers Context

Creates a context for a headers plugin. This is a convenience method for Context and merely uses the label “headers”.

declare function dhf:headers-context($content) as json:object

Parameters

content - the output from the content plugin

Returns

A context object for use in the Run function. This context object contains the label “headers”

Usage

JavaScript
XQuery

const dhf = require('/data-hub/4/dhf.xqy');

var content = {};
var context = dhf.headersContext(content);
var result = dhf.run(context, function() {
  return 1;
});

import module namespace dhf = "http://marklogic.com/dhf"
  at "/data-hub/4/dhf.xqy";

let $content := <content/>
let $context := dhf:headers-context($content)
let $result := dhf:run($context, function() {
  return 1
})
return
  $result

Triples Context

Creates a context for a triples plugin. This is a convenience method for Context and merely uses the label “triples”.

declare function dhf:triples-context($content, $headers) as json:object

Parameters

content - the output from the content plugin
headers - the output from the headers plugin

Returns

A context object for use in the Run function. This context object contains the label “triples”

Usage

JavaScript
XQuery

const dhf = require('/data-hub/4/dhf.xqy');

var content = {};
var headers = {};
var context = dhf.triplesContext(content, headers);
var result = dhf.run(context, function() {
  return 1;
});

import module namespace dhf = "http://marklogic.com/dhf"
  at "/data-hub/4/dhf.xqy";

let $content = <content/>
let $headers = ()
let $context := dhf:triples-context($content, $headers)
let $result := dhf:run($context, function() {
  return 1
})
return
  $result

Writer Context

Creates a context for a writer plugin. This is a convenience method for Context and merely uses the label “writer”.

declare function dhf:writer-context($envelope) as json:object

Parameters

envelope - the envelope you constructed

Returns

A context object for use in the Log Trace function. This context object contains the label “writer”

Usage

JavaScript
XQuery

const dhf = require('/data-hub/4/dhf.xqy');

var envelope = {};
dhf.logTrace(dhf.writerContext(envelope));

import module namespace dhf = "http://marklogic.com/dhf"
  at "/data-hub/4/dhf.xqy";

let $envelope := <envelope/>
let $_ := dhf:log-trace(dhf:writer-context($envelope))
return
  $envelope

Add Trace Input

Adds a trace input to the context. You can add as many trace inputs as you like so long as each one has a unique label. These inputs are later logged into traces if/when they are logged.

declare function dhf:add-trace-input($context as json:object, $input-label as xs:string, $input) as json:object

Parameters

context - the context
input-label - the label for the input
input - the input to add to the context

Returns

Returns the passed in $context with the new inputs added.

Usage

JavaScript
XQuery

const dhf = require('/data-hub/4/dhf.xqy');

var expenseReport = {};
var context = dhf.context('My Plugin');
var context = dhf.addTraceInput(context, 'expense report', expenseReport);
var result = dhf.run(context, function() {
  return 1;
});

import module namespace dhf = "http://marklogic.com/dhf"
  at "/data-hub/4/dhf.xqy";

let $expense-report := <expense-report/>
let $context := dhf:context("My Plugin")
let $context := dhf:add-trace-input($context, "expense report", $expense-report)
let $result := dhf:run($context, function() {
  return 1
})
return
  $result

Log Trace

Logs a trace, but only if tracing is enabled.

declare function dhf:log-trace($context as json:object)

Parameters

context - the context

Returns

Nothing

Usage

JavaScript
XQuery

const dhf = require('/data-hub/4/dhf.xqy');

var envelope = {};
dhf.logTrace(dhf.writerContext(envelope));

import module namespace dhf = "http://marklogic.com/dhf"
  at "/data-hub/4/dhf.xqy";

let $envelope := <envelope/>
let $_ := dhf:log-trace(dhf:writer-context($envelope))
return
  $envelope