Data Services for IO

Document IO With Data Service Endpoints

The Data Services approach provides an interface on a middle tier or other backend server for data operations implemented by an endpoint on a MarkLogic enode. This approach supports a good division of responsibilities between the middle-tier or backend generalist and the MarkLogic specialist as well as encapsulation of database knowledge within the data service.

As described elsewhere, the Java API provides tooling for generating a Java interface based on an endpoint declaration. For more information about that approach, see:

http://docs.marklogic.com/guide/java/DataServices

The Java API also provides the following out-of-the-box interfaces in the dataservices package for Data Service endpoints that implement document IO:

Interface	Behavior required for the implementing endpoint
InputEndpoint	Takes zero or more documents as input with no output
OutputEndpoint	Returns zero or more documents as output with no input
InputOutputEndpoint	Both takes documents as input and returns documents as output
ExecEndpoint	Executes with neither input or output

An instance of one of the interfaces is constructed by calling its on() factory method with

• a DatabaseClient specifying the appserver and user authentication
• a JSONWriteHandle providing the *.api declaration for the endpoint

The following example constructs an InputEndpoint instance for calling an endpoint that takes document input without returning any output:

InputEndpoint caller = InputEndpoint.on(dbClient, apiDeclaration);

The *.api declaration must have an endpoint property specifying the full path of the main module in the modules database. Any functionName property in the *.api declaration is ignored when using an out-of-the-box IO endpoint interface.

Input endpoints

When constructing an InputEndpoint instance, the endpoint must conform to the following *.api declaration:

  {
    "endpoint": "INPUT_ENDPOINT_PATH",
    "params": [
      {"name":"input", "datatype":"DOCUMENT_TYPE", "multiple":true,  "nullable":true}
      ]
    }

To call the specified input endpoint, use the InputEndpoint.call() method:

void call(InputStream[] input);

Output endpoints

When constructing an OutputEndpoint instance, the endpoint must conform to the following *.api declaration:

{
  "endpoint": "OUTPUT_ENDPOINT_PATH", 
  "return": {"datatype":"DOCUMENT_TYPE", "multiple":true, "nullable":true}
  }

To call the specified output endpoint, use the OutputEndpoint.call() method:

InputStream[] call();

Input-output endpoints

When constructing an InputOutputEndpoint instance, the endpoint must conform to the following *.api declaration:

  {
    "endpoint": "INPUT_OUTPUT_ENDPOINT_PATH", 
    "params": [
      {"name":"input", "datatype":"DOCUMENT_TYPE", "multiple":true,  "nullable":true}
      ],
    "return": {"datatype":"DOCUMENT_TYPE", "multiple":true, "nullable":true}
    }

To call the specified input-output endpoint, use the InputOutputEndpoint.call() method:

InputStream[] call(InputStream[] input);

Exec endpoints

When constructing an ExecEndpoint instance, the endpoint must conform to the following *.api declaration:

    {
      "endpoint": "EXEC_ENDPOINT_PATH"
      }

To call the specified exec endpoint, use the ExecEndpoint.call() method:

void call();

Note: The same interfaces are also used for constructing bulk IO callers when Integrating Dataflow Frameworks With MarkLogic.