rename workUnit to endpointConstants #1250

Author: ehennum

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

@@ -36,12 +36,12 @@ static ExecCaller on(DatabaseClient client, JSONWriteHandle apiDecl) {
     }
 
     /**
-     * Makes one call to an endpoint that doesn't take an endpoint state, session, or work unit.
+     * Makes one call to an endpoint that doesn't take endpoint constants, endpoint state, or a session.
      */
     void call();
     /**
      * Makes one call to the endpoint for the instance and sets the endpoint state in the Call Context.
-     * @param callContext the collection of endpointState, sessionState and workUnit
+     * @param callContext the context consisting of the optional endpointConstants, endpointState, and session
      */
     void call(CallContext callContext);
 
@@ -54,7 +54,7 @@ static ExecCaller on(DatabaseClient client, JSONWriteHandle apiDecl) {
     /**
      * 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 collection of endpointState, sessionState and workUnit
+     * @param callContext the context consisting of the optional endpointConstants, endpointState, and session
      * @return  the bulk caller for the endpoint
      */
     BulkExecCaller bulkCaller(CallContext callContext);
@@ -79,9 +79,7 @@ static ExecCaller on(DatabaseClient client, JSONWriteHandle apiDecl) {
      * 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.
+     * Call awaitCompletion() to start making calls.
      */
     interface BulkExecCaller extends BulkIOEndpointCaller {
         void setErrorListener(ErrorListener errorListener);

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

@@ -73,9 +73,7 @@ private BulkLocal(EndpointLocal<I,O> endpoint) {
      * 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.
+     * Call awaitCompletion() to start making calls.
      */
     @Deprecated
     interface BulkExecCaller extends ExecCaller.BulkExecCaller {

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

@@ -49,7 +49,14 @@ public interface IOEndpoint {
      * the unit of work to be done by the endpoint.
      * @return  whether the endpoint takes a work unit
      */
+    @Deprecated
     boolean allowsWorkUnit();
+    /**
+     * Identifies whether the endpoint accepts a data structure that defines
+     * constant input to provide to the endpoint.
+     * @return  whether the endpoint takes endpoint constants
+     */
+    boolean allowsEndpointConstants();
     /**
      * Identifies whether the endpoint accepts one or more input data structures
      * to work on.
@@ -70,49 +77,57 @@ public interface IOEndpoint {
     interface BulkIOEndpointCaller {
         /**
          * Gets the current snapshot of the mutable endpoint state.
+         * Provide a CallContext when constructing the bulk caller instead of using this deprecated method.
          * @return  the data structure with the endpoint state
          */
         @Deprecated
         InputStream getEndpointState();
         /**
          * Initializes the endpoint state, typically prior to the first call.
+         * Provide a CallContext when constructing the bulk caller instead of using this deprecated method.
          * @param endpointState the data structure for the endpoint state as a byte[] array
          */
         @Deprecated
         void setEndpointState(byte[] endpointState);
         /**
          * Initializes the endpoint state, typically prior to the first call.
+         * Provide a CallContext when constructing the bulk caller instead of using this deprecated method.
          * @param endpointState the data structure for the endpoint state as an InputStream
          */
         @Deprecated
         void setEndpointState(InputStream endpointState);
         /**
          * Initializes the endpoint state, typically prior to the first call.
+         * Provide a CallContext when constructing the bulk caller instead of using this deprecated method.
          * @param endpointState the data structure for the endpoint state as a bufferable handle
          */
         @Deprecated
         void setEndpointState(BufferableHandle endpointState);
 
         /**
          * Gets the definition for the unit of  work to be done by the endpoint.
+         * Provide a CallContext with endpoint constants when constructing the bulk caller instead of using this deprecated method.
          * @return  the data structure for the unit of work
          */
         @Deprecated
         InputStream getWorkUnit();
         /**
-         * Initializes the defintion of the work unit prior to the first call.
+         * Initializes the definition of the work unit prior to the first call.
+         * Provide a CallContext with endpoint constants when constructing the bulk caller instead of using this deprecated method.
          * @param workUnit the data structure for the work unit as a byte[] array
          */
         @Deprecated
         void setWorkUnit(byte[] workUnit);
         /**
-         * Initializes the defintion of the work unit prior to the first call.
+         * Initializes the definition of the work unit prior to the first call.
+         * Provide a CallContext with endpoint constants when constructing the bulk caller instead of using this deprecated method.
          * @param workUnit the data structure for the work unit as an InputStream
          */
         @Deprecated
         void setWorkUnit(InputStream workUnit);
         /**
-         * Initializes the defintion of the work unit prior to the first call.
+         * Initializes the definition of the work unit prior to the first call.
+         * Provide a CallContext with endpoint constants when constructing the bulk caller instead of using this deprecated method.
          * @param workUnit the data structure for the work unit as a bufferable handle
          */
         @Deprecated
@@ -128,52 +143,68 @@ interface BulkIOEndpointCaller {
          */
         void interrupt();
 
+        /**
+         * Indicates the disposition of an error.
+         */
         enum ErrorDisposition {
-            RETRY, SKIP_CALL, STOP_CONTEXT_CALLS, STOP_ALL_CALLS;
+            RETRY, SKIP_CALL, STOP_ALL_CALLS;
         }
     }
     /**
-     * Gets the current snapshot of the endpoint state, work unit and session.
-     * @return  the data structure with the endpoint state, work unit and session.
+     * Constructs a context for the calls that specifying the optional endpoint constants,
+     * endpoint state, and session.
+     * @return  the context for calls
      */
     CallContext newCallContext();
 
+    /**
+     * Provides the optional endpoint constants, endpoint state, and session as a context
+     * for calls to the server.
+     */
     interface CallContext {
         /**
-         * Gets the current snapshot of the mutable endpoint state.
+         * Gets the current snapshot of the mutable state of the endpoint.
          * @return  the data structure with the endpoint state
          */
         BytesHandle getEndpointState();
         /**
-         * Initializes the endpoint state.
-         * @param endpointState the data structure for the endpoint state as a bufferable handle
+         * Initializes the stateful properties of the endpoint prior to the first call to the endpoint.
+         * The endpoint returns the state as the first value in the response.
+         * The caller resends the modified state on the next call to the endpoint.
+         * @param endpointState the data structure for the endpoint state in a representation supported by a bufferable content handle
          * @return the callContext
          */
         CallContext withEndpointState(BufferableHandle endpointState);
         /**
-         * Initializes the endpoint state.
-         * @param endpointState the data structure for the endpoint state as an InputStream
+         * Initializes the stateful properties of the endpoint prior to the first call to the endpoint.
+         * The endpoint returns the state as the first value in the response.
+         * The caller resends the modified state on the next call to the endpoint.
+         * @param endpointState the data structure for the endpoint state in a representation supported by a bufferable content handle
          * @return the callContext
          */
         CallContext withEndpointStateAs(Object endpointState);
 
         /**
-         * Gets the definition for the unit of  work to be done by the endpoint.
-         * @return  the data structure for the unit of work
+         * Gets the definition for constant inputs to the endpoint.
+         * @return  the data structure for the constants
          */
-        BytesHandle getWorkUnit();
+        BytesHandle getEndpointConstants();
         /**
-         * Initializes the defintion of the work unit.
-         * @param workUnit the data structure for the work unit as a bufferable handle
+         * Sets the constant inputs prior to the first call to the endpoint.
+         * Examples of such constants might include the query when paging
+         * over a result set or the provenance when ingesting records.
+         * @param constants the data structure in a representation supported by a bufferable content handle
          * @return the callContext
          */
-        CallContext withWorkUnit(BufferableHandle workUnit);
+        CallContext withEndpointConstants(BufferableHandle constants);
         /**
-         * Initializes the defintion of the work unit.
-         * @param workUnit the data structure for the work unit as an InputStream
+         * Sets the constant inputs prior to the first call to the endpoint.
+         * Examples of such constants might include the query when paging
+         * over a result set or the provenance when ingesting records.
+         * @param constants the data structure in a representation supported by a bufferable content handle
          * @return  the callContext
          */
-        CallContext withWorkUnitAs(Object workUnit);
+        CallContext withEndpointConstantsAs(Object constants);
 
         /**
          * Returns an identifier for an endpoint to use when accessing a session cache on the server.

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

@@ -37,13 +37,13 @@ static <I> InputCaller<I> on(DatabaseClient client, JSONWriteHandle apiDecl, Buf
 	}
 
 	/**
-	 * Makes one call to an endpoint that doesn't take an endpoint state, session, or work unit.
+	 * 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
 	 */
 	void call(I[] input);
 	/**
 	 * Makes one call to the endpoint for the instance and sets the endpoint state in the Call Context.
-	 * @param callContext  the collection of endpointState, sessionState and workUnit
+	 * @param callContext  the context consisting of the optional endpointConstants, endpointState, and session
 	 * @param input  the request data sent to the endpoint
 	 */
 	void call(CallContext callContext, I[] input);
@@ -57,7 +57,7 @@ static <I> InputCaller<I> on(DatabaseClient client, JSONWriteHandle apiDecl, Buf
 	/**
 	 * 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 collection of endpointState, sessionState and workUnit
+	 * @param  callContext the context consisting of the optional endpointConstants, endpointState, and session
 	 * @return  the bulk caller for the input endpoint
 	 */
 	BulkInputCaller<I> bulkCaller(CallContext callContext);

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

@@ -45,15 +45,15 @@ static <I,O> InputOutputCaller<I,O> on(
     }
 
     /**
-     * Makes one call to an endpoint that doesn't take an endpoint state, session, or work unit.
+     * 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 doesn't take an endpoint state, session, or work unit and sets the
-     * endpoint state in the Call Context.
-     * @param callContext  the collection of endpointState, sessionState and workUnit
+     * 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
      */
@@ -68,7 +68,7 @@ static <I,O> InputOutputCaller<I,O> on(
     /**
      * 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 collection of endpointState, sessionState and workUnit
+     * @param callContext  the context consisting of the optional endpointConstants, endpointState, and session
      * @return  the bulk caller for the input-output endpoint
      */
     BulkInputOutputCaller<I,O> bulkCaller(CallContext callContext);

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

@@ -41,13 +41,13 @@ static <O> OutputCaller<O> on(
     }
 
     /**
-     * Makes one call to an endpoint that doesn't take an endpoint state, session, or work unit.
+     * Makes one call to an endpoint that doesn't take endpoint constants, endpoint state, or a session.
      * @return  the response data from the endpoint
      */
     O[] call();
     /**
      * Makes one call to the endpoint for the instance and sets the endpoint state in the Call Context.
-     * @param callContext the collection of endpointState, sessionState and workUnit
+     * @param callContext the context consisting of the optional endpointConstants, endpointState, and session
      * @return  the response data from the endpoint
      */
     O[] call(CallContext callContext);
@@ -61,7 +61,7 @@ static <O> OutputCaller<O> on(
     /**
      * Constructs an instance of a bulk caller, which completes
      * a unit of work by repeated calls to the endpoint. The calls occur in current thread.
-     * @param callContext the collection of endpointState, sessionState and workUnit
+     * @param callContext the context consisting of the optional endpointConstants, endpointState, and session
      * @return  the bulk caller for the output endpoint
      */
     BulkOutputCaller<O> bulkCaller(CallContext callContext);

marklogic-client-api/src/main/java/com/marklogic/client/dataservices/impl/CallContextImpl.java

@@ -33,7 +33,7 @@ class CallContextImpl<I,O> implements IOEndpoint.CallContext {
     private final boolean legacyContext;
 
     private BytesHandle endpointState;
-    private BytesHandle workUnit;
+    private BytesHandle endpointConstants;
     private SessionState session;
 
     CallContextImpl(IOEndpointImpl<I,O> endpoint, boolean legacyContext) {
@@ -42,8 +42,8 @@ class CallContextImpl<I,O> implements IOEndpoint.CallContext {
         if (endpoint.allowsEndpointState()) {
             endpointState = new BytesHandle().withFormat(endpoint.getEndpointStateParamdef().getFormat());
         }
-        if (endpoint.allowsWorkUnit()) {
-            workUnit = new BytesHandle().withFormat(endpoint.getWorkUnitParamdef().getFormat());
+        if (endpoint.allowsEndpointConstants()) {
+            endpointConstants = new BytesHandle().withFormat(endpoint.getEndpointConstantsParamdef().getFormat());
         }
     }
 
@@ -58,6 +58,9 @@ DatabaseClient getClient() {
     boolean isLegacyContext() {
         return legacyContext;
     }
+    String getEndpointConstantsParamName() {
+        return isLegacyContext() ? "workUnit" : "endpointConstants";
+    }
 
     @Override
     public BytesHandle getEndpointState() {
@@ -80,19 +83,19 @@ public CallContextImpl<I,O> withEndpointStateAs(Object endpointState) {
     }
 
     @Override
-    public BytesHandle getWorkUnit() {
-        return this.workUnit;
+    public BytesHandle getEndpointConstants() {
+        return this.endpointConstants;
     }
     @Override
-    public CallContextImpl<I,O> withWorkUnit(BufferableHandle workUnit) {
-        return assignBytes(this.workUnit, workUnit);
+    public CallContextImpl<I,O> withEndpointConstants(BufferableHandle constants) {
+        return assignBytes(this.endpointConstants, constants);
     }
-    CallContextImpl<I,O> withWorkUnitAs(InputStream workUnit) {
-        return assignBytes(this.workUnit, workUnit);
+    CallContextImpl<I,O> withEndpointConstantsAs(InputStream contants) {
+        return assignBytes(this.endpointConstants, contants);
     }
     @Override
-    public CallContextImpl<I,O> withWorkUnitAs(Object workUnit) {
-        return assignBytes(this.workUnit, workUnit);
+    public CallContextImpl<I,O> withEndpointConstantsAs(Object constants) {
+        return assignBytes(this.endpointConstants, constants);
     }
 
     @Override

marklogic-client-api/src/main/java/com/marklogic/client/dataservices/impl/ExecEndpointImpl.java

@@ -53,11 +53,11 @@ public void call(CallContext callContext) {
     }
 
     @Deprecated
-    public InputStream call(InputStream endpointState, SessionState session, InputStream workUnit) {
+    public InputStream call(InputStream endpointState, SessionState session, InputStream endpointConstants) {
         CallContextImpl<I,O> callContext = newCallContext(true)
                 .withEndpointStateAs(endpointState)
                 .withSessionState(session)
-                .withWorkUnitAs(workUnit);
+                .withEndpointConstantsAs(endpointConstants);
         call(callContext);
         return callContext.getEndpointStateAsInputStream();
     }
@@ -215,14 +215,14 @@ private boolean processOutput(CallContextImpl<I,O> callContext){
                 case INTERRUPTING:
                     setPhase(WorkPhase.INTERRUPTED);
                     logger.info("exec interrupted endpoint={} count={} work={}",
-                            callContext.getEndpoint().getEndpointPath(), getCallCount(), callContext.getWorkUnit());
+                            callContext.getEndpoint().getEndpointPath(), getCallCount(), callContext.getEndpointConstants());
                     return false;
                 case RUNNING:
                     if (!continueCalling) {
                         if(getCallerThreadPoolExecutor() == null || aliveCallContextCount.get() == 0)
                             setPhase(WorkPhase.COMPLETED);
                         logger.info("exec completed endpoint={} count={} work={}",
-                                callContext.getEndpoint().getEndpointPath(), getCallCount(), callContext.getWorkUnit());
+                                callContext.getEndpoint().getEndpointPath(), getCallCount(), callContext.getEndpointConstants());
                         return false;
                     }
                     return true;