Merge branch 'develop-72' into develop

Author: ehennum

marklogic-client-api/src/main/java/com/marklogic/client/dataservices/ExecEndpoint.java

@@ -0,0 +1,68 @@
+/*
+ * Copyright 2019 MarkLogic Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.marklogic.client.dataservices;
+
+import com.marklogic.client.DatabaseClient;
+import com.marklogic.client.SessionState;
+import com.marklogic.client.dataservices.impl.ExecEndpointImpl;
+import com.marklogic.client.io.marker.JSONWriteHandle;
+
+import java.io.InputStream;
+
+/**
+ * Provides an interface for calling an endpoint that doesn't take
+ * input data structures or return output data structures.
+ */
+public interface ExecEndpoint extends IOEndpoint {
+    /**
+     * Constructs an instance of the ExecEndpoint interface
+     * for calling the specified endpoint.
+     * @param client  the database client to use for making calls
+     * @param apiDecl  the JSON api declaration specifying how to call the endpoint
+     * @return  the ExecEndpoint instance for calling the endpoint
+     */
+    static ExecEndpoint on(DatabaseClient client, JSONWriteHandle apiDecl) {
+        return new ExecEndpointImpl(client, apiDecl);
+    }
+
+    /**
+     * Makes one call to the endpoint for the instance.
+     * @param endpointState  the current mutable state of the endpoint (which must be null if not accepted by the endpoint)
+     * @param session  the identifier for the server cache of the endpoint (which must be null if not accepted by the endpoint)
+     * @param workUnit  the definition of a unit of work (which must be null if not accepted by the endpoint)
+     * @return the endpoint state for the next call, if returned by the endpoint, or null
+     */
+    InputStream call(InputStream endpointState, SessionState session, InputStream workUnit);
+
+    /**
+     * 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 endpoint
+     */
+    BulkExecCaller bulkCaller();
+
+    /**
+     * Provides an interface for completing a unit of work
+     * by repeated calls to an endpoint that doesn't take input
+     * data structure or return output data structures.
+     *
+     * Use the inherited methods to set the endpoint state
+     * and / or work unit if accepted by the endpoint.
+     * Then, call awaitCompletion() to start making calls.
+     */
+    interface BulkExecCaller extends IOEndpoint.BulkIOEndpointCaller {
+    }
+}

marklogic-client-api/src/main/java/com/marklogic/client/dataservices/IOEndpoint.java

@@ -0,0 +1,122 @@
+/*
+ * Copyright 2019 MarkLogic Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.marklogic.client.dataservices;
+
+import com.marklogic.client.SessionState;
+import com.marklogic.client.io.marker.BufferableHandle;
+
+import java.io.InputStream;
+import java.util.function.Consumer;
+
+/**
+ * Base interface providing the methods common to all endpoints.
+ */
+public interface IOEndpoint {
+    /**
+     * Identifies the path of the endpoint in the modules database on the server.
+     * @return the path
+     */
+    String getEndpointPath();
+
+    /**
+     * Identifies whether the endpoint accepts and returns a data structure
+     * that provides a snapshot of the mutable state of the endpoint.
+     * @return  whether the endpoint takes a state
+     */
+    boolean allowsEndpointState();
+    /**
+     * Identifies whether the endpoint accepts a session identifier that
+     * the endpoint can use to access a session cache on the server.
+     * @return  whether the endpoint takes a session
+     */
+    boolean allowsSession();
+    /**
+     * Identifies whether the endpoint accepts a data structure that defines
+     * the unit of work to be done by the endpoint.
+     * @return  whether the endpoint takes a work unit
+     */
+    boolean allowsWorkUnit();
+    /**
+     * Identifies whether the endpoint accepts one or more input data structures
+     * to work on.
+     * @return  whether the endpoint takes input data structures
+     */
+    boolean allowsInput();
+
+    /**
+     * Generates an identifier for an endpoint to use when accessing a session cache
+     * on the server. The identifier can be reused for multiple calls.
+     * @return  a new identifier for a session cache on the server
+     */
+    SessionState newSessionState();
+
+    /**
+     * Base interface providing the methods common to all bulk endpoint callers.
+     */
+    interface BulkIOEndpointCaller {
+        /**
+         * Gets the current snapshot of the mutable endpoint state.
+         * @return  the data structure with the endpoint state
+         */
+        InputStream getEndpointState();
+        /**
+         * Initializes the endpoint state, typically prior to the first call.
+         * @param endpointState the data structure for the endpoint state as a byte[] array
+         */
+        void setEndpointState(byte[] endpointState);
+        /**
+         * Initializes the endpoint state, typically prior to the first call.
+         * @param endpointState the data structure for the endpoint state as an InputStream
+         */
+        void setEndpointState(InputStream endpointState);
+        /**
+         * Initializes the endpoint state, typically prior to the first call.
+         * @param endpointState the data structure for the endpoint state as a bufferable handle
+         */
+        void setEndpointState(BufferableHandle endpointState);
+
+        /**
+         * Gets the definition for the unit of  work to be done by the endpoint.
+         * @return  the data structure for the unit of work
+         */
+        InputStream getWorkUnit();
+        /**
+         * Initializes the defintion of the work unit prior to the first call.
+         * @param workUnit the data structure for the work unit as a byte[] array
+         */
+        void setWorkUnit(byte[] workUnit);
+        /**
+         * Initializes the defintion of the work unit prior to the first call.
+         * @param workUnit the data structure for the work unit as an InputStream
+         */
+        void setWorkUnit(InputStream workUnit);
+        /**
+         * Initializes the defintion of the work unit prior to the first call.
+         * @param workUnit the data structure for the work unit as a bufferable handle
+         */
+        void setWorkUnit(BufferableHandle workUnit);
+
+        /**
+         * Waits for the bulk calling to complete, first starting the calls if appropriate.
+         */
+        void awaitCompletion();
+
+        /**
+         * Interrupts the iterative bulk calls prior to completion.
+         */
+        void interrupt();
+    }
+}

marklogic-client-api/src/main/java/com/marklogic/client/dataservices/InputEndpoint.java

@@ -0,0 +1,73 @@
+/*
+ * Copyright 2019 MarkLogic Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.marklogic.client.dataservices;
+
+import java.io.InputStream;
+
+import com.marklogic.client.DatabaseClient;
+import com.marklogic.client.SessionState;
+import com.marklogic.client.dataservices.impl.InputEndpointImpl;
+import com.marklogic.client.io.marker.JSONWriteHandle;
+
+/**
+ * Provides an interface for calling an endpoint that takes input data structures.
+ */
+public interface InputEndpoint extends IOEndpoint {
+	/**
+     * Constructs an instance of the InputEndpoint interface.
+     * @param client  the database client to use for making calls
+     * @param apiDecl  the JSON api declaration specifying how to call the endpoint
+     * @return  the InputEndpoint instance for calling the endpoint.
+     */
+	static InputEndpoint on(DatabaseClient client, JSONWriteHandle apiDecl) {
+		return new InputEndpointImpl(client, apiDecl);
+	}
+
+	/**
+	 * Makes one call to the endpoint for the instance
+	 * @param endpointState  the current mutable state of the endpoint (which must be null if not accepted by the endpoint)
+	 * @param session  the identifier for the server cache of the endpoint (which must be null if not accepted by the endpoint)
+	 * @param workUnit  the definition of a unit of work (which must be null if not accepted by the endpoint)
+	 * @param input  the request data sent to the endpoint
+	 * @return the endpoint state for the next call, if returned by the endpoint, or null
+	 */
+	InputStream call(InputStream endpointState, SessionState session, InputStream workUnit, InputStream[] 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 endpoint
+     */
+	BulkInputCaller bulkCaller();
+
+	/**
+     * Provides an interface for completing a unit of work
+     * by repeated calls to the input endpoint.
+     */
+	interface BulkInputCaller extends IOEndpoint.BulkIOEndpointCaller {
+		/**
+		 * Accepts an input item for the endpoint.  Items are queued
+		 * and submitted to the endpoint in batches.
+		 * @param input  one input item
+		 */
+		void accept(InputStream 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(InputStream[] input);
+	}
+}

marklogic-client-api/src/main/java/com/marklogic/client/dataservices/InputOutputEndpoint.java

@@ -0,0 +1,75 @@
+/*
+ * Copyright 2019 MarkLogic Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.marklogic.client.dataservices;
+
+import com.marklogic.client.DatabaseClient;
+import com.marklogic.client.SessionState;
+import com.marklogic.client.dataservices.impl.InputOutputEndpointImpl;
+import com.marklogic.client.io.marker.JSONWriteHandle;
+
+import java.io.InputStream;
+import java.util.function.Consumer;
+
+/**
+ * Provides an interface for calling an endpoint that takes input data structures and
+ * returns output data structures.
+ */
+public interface InputOutputEndpoint extends IOEndpoint {
+    static InputOutputEndpoint on(DatabaseClient client, JSONWriteHandle apiDecl) {
+        return new InputOutputEndpointImpl(client, apiDecl);
+    }
+
+    /**
+     * Makes one call to the endpoint for the instance
+     * @param endpointState  the current mutable state of the endpoint (which must be null if not accepted by the endpoint)
+     * @param session  the identifier for the server cache of the endpoint (which must be null if not accepted by the endpoint)
+     * @param workUnit  the definition of a unit of work (which must be null if not accepted by the endpoint)
+     * @param input  the request data sent to the endpoint
+     * @return  the endpoint state if produced by the endpoint followed by the response data from the endpoint
+     */
+    InputStream[] call(InputStream endpointState, SessionState session, InputStream workUnit, InputStream[] 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();
+
+    /**
+     * Provides an interface for completing a unit of work
+     * by repeated calls to the input-output endpoint.
+     */
+    interface BulkInputOutputCaller extends IOEndpoint.BulkIOEndpointCaller {
+        /**
+         * Specifies the function to call on receiving output from the endpoint.
+         * @param listener a function for processing the endpoint output
+         */
+        void setOutputListener(Consumer<InputStream> 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(InputStream 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(InputStream[] input);
+    }
+}