com.marklogic.client.dataservices.InputOutputCaller Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of marklogic-client-api Show documentation
The official MarkLogic Java client API.
The newest version!
/*
 * Copyright © 2024 MarkLogic Corporation. All Rights Reserved.
 */
package com.marklogic.client.dataservices;

import com.marklogic.client.DatabaseClient;
import com.marklogic.client.dataservices.impl.HandleProvider;
import com.marklogic.client.dataservices.impl.InputOutputEndpointImpl;
import com.marklogic.client.io.marker.BufferableContentHandle;
import com.marklogic.client.io.marker.BufferableHandle;
import com.marklogic.client.io.marker.JSONWriteHandle;

import java.util.function.Consumer;

/**
 * Provides an interface for calling an endpoint that takes input data structures and
 * returns output data structures.
 *
 * @param   The representation for document input
 * @param  The representation for document output
 * @see Input-output endpoints
 */
public interface InputOutputCaller extends IOEndpoint {
    /**
     * Constructs an instance of the InputOutputCaller interface.
     * @param client  the database client to use for making calls
     * @param apiDecl  the JSON api declaration specifying how to call the endpoint
     * @param inputHandle  the handle for the representation of the input content (such as StringHandle)
     * @param outputHandle  the handle for the representation of the output content (such as BytesHandle)
     * @param   the content representation (such as String)
     * @param   the output content representation (such as byte[])
     * @return  the InputOutputCaller instance for calling the endpoint.
     */
    static  InputOutputCaller on(
            DatabaseClient client, JSONWriteHandle apiDecl,
            BufferableContentHandle inputHandle, BufferableContentHandle outputHandle
    ) {
      return new InputOutputEndpointImpl<>(client, apiDecl, new HandleProvider.ContentHandleProvider<>(inputHandle, outputHandle));
    }

    /**
     * Constructs an instance of the InputOutputCaller interface.
     * This factory is useful primarily for parameters or return values of the anyDocument type.
     * @param client the database client to use for making calls
     * @param apiDecl the JSON api declaration specifying how to call the endpoint
     * @param inputHandle the handles that provides the input content (such as StringHandle)
     * @param outputHandle the handles that provides the output content (such as BytesHandle)
     * @param  the content type of the input handle
     * @param  the type for the data received by the input handle
     * @param  the content type of the output handle
     * @param  the type for the data received by the output handle
     * @param  the input handle
     * @param  the output handle
     * @return the InputOutputCaller instance for calling the endpoint.
     */
    static ,O extends BufferableContentHandle> InputOutputCaller onHandles(
            DatabaseClient client, JSONWriteHandle apiDecl,
            I inputHandle, O outputHandle
    ) {
        return new InputOutputEndpointImpl(client, apiDecl, (HandleProvider) new HandleProvider.DirectHandleProvider(inputHandle, outputHandle));
    }

    /**
     * Makes one call to an endpoint that doesn't take endpoint constants, endpoint state, or a session.
     * @param input  the request data sent to the endpoint
     * @return  the response data from the endpoint
     */
    O[] call(I[] input);
    /**
     * Makes one call to an endpoint that sets endpoint constants, endpoint state, or a session
     * in the Call Context.
     * @param callContext  the context consisting of the optional endpointConstants, endpointState, and session
     * @param input  the request data sent to the endpoint
     * @return the response data from the endpoint
     */
    O[] call(CallContext callContext, I[] input);

    /**
     * Constructs an instance of a bulk caller, which completes
     * a unit of work by repeated calls to the endpoint.
     * @return  the bulk caller for the input-output endpoint
     */
    BulkInputOutputCaller bulkCaller();
    /**
     * Constructs an instance of a bulk caller, which completes
     * a unit of work by repeated calls to the endpoint. The calls occur in the current thread.
     * @param callContext  the context consisting of the optional endpointConstants, endpointState, and session
     * @return  the bulk caller for the input-output endpoint
     */
    BulkInputOutputCaller bulkCaller(CallContext callContext);
    /**
     * Constructs an instance of a bulk caller, which completes
     * a unit of work by repeated calls to the endpoint. The calls occur in worker threads.
     * @param callContexts  the collection of callContexts
     * @return  the bulk caller for the input-output endpoint
     */
    BulkInputOutputCaller bulkCaller(CallContext[] callContexts);
    /**
     * Constructs an instance of a bulk caller, which completes
     * a unit of work by repeated calls to the endpoint. The calls occur in worker threads.
     * @param callContexts  the collection of callContexts
     * @param threadCount the number of threads
     * @return  the bulk caller for the input-output endpoint
     */
    BulkInputOutputCaller bulkCaller(CallContext[] callContexts, int threadCount);

    /**
     * Provides an interface for completing a unit of work
     * by repeated calls to the input-output endpoint.
     *
     * @param   The representation for document input
     * @param  The representation for document output
     * @see Bulk Data Services
     */
    interface BulkInputOutputCaller extends BulkIOEndpointCaller {
        /**
         * Specifies the function to call on receiving output from the endpoint.
         * @param listener a function for processing the endpoint output
         */
        void setOutputListener(Consumer listener);
        /**
         * Accepts an input item for the endpoint.  Items are queued
         * and submitted to the endpoint in batches.
         * @param input  one input item
         */
        void accept(I input);
        /**
         * Accepts multiple input items for the endpoint.  Items are queued
         * and submitted to the endpoint in batches.
         * @param input  multiple input items.
         */
        void acceptAll(I[] input);

        /**
         * Provides a callback specifies the disposition of a failed call.
         * @param errorListener the lambda or other implementation of the error listener
         */
        void setErrorListener(ErrorListener errorListener);

        /**
         * A function implementation that specifies the disposition of a failed call.
         */
        interface ErrorListener {
            /**
             * The signature for the lambda or other implementation of the callback that specifies
             * the disposition of a failed call.
             *
             * The input is typed with the BufferableHandle marker interface.  The actual class
             * of the handle is
             * 
             * the same as the input handle provided when constructing the InputOutputCaller
             * if the content representation is resendable for retry (as with String)
             * a BytesHandle if the content must be buffered for retry (as with InputStream)
             * 
             * @param retryCount  the number of times the call with this input has been retried
             * @param throwable  the error received
             * @param callContext  the context for the call
             * @param input  the input for the call
             * @return  whether to retry the call, skip the call, or stop the job
             */
            ErrorDisposition processError(
                    int retryCount, Throwable throwable, CallContext callContext, BufferableHandle[] input
            );
        }
    }
}