RowBatcher (MarkLogic Java Client API 7.0.0)

Type Parameters:

T - the Java class that stores a batch of retrieved roles

All Superinterfaces:

Batcher
```
public interface RowBatcher<T>
extends Batcher
```
Coordinates threads to export all of the rows from a view in batches.
To construct a RowBatcher, use the DataMovementManager.newRowBatcher() factory method. You pass a sample handle (that is, an adapter for the Java class that stores a batch of retrieved rows). The sample handle must implement both the ContentHandle and StructuredReadHandle interfaces. Because RowBatcher can retrieve rows in multiple formats, you must specify the format or mime type on the sample handle if the handle can be used for multiple row formats. The RowBatcher takes a generic type for the Java class adapted by the sample handle.

The following example constructs a RowBatcher for retrieving the rows in CSV format as a Java String. The factory call passes a StringHandle configured with the appropriate format and mime type:
```
    RowBatcher<String> rowBatcher = dataMovementMgr.newRowBatcher(
        new StringHandle().withFormat(Format.TEXT).withMimetype("text/csv")
        );
```
After constructing the RowBatcher, use the getRowManager() method to get the RowManager for the rows. You can use the RowManager's setDatatypeStyle() method to emit data types in the header and setRowStructureStyle() method to emit rows as objects or arrays. The RowManager's newPlanBuilder() method provides a factory for constructing a PlanBuilder.

Use the RowManager's PlanBuilder to build a plan for retrieving the rows from a view. The plan must have the following characteristics:
- Must start with a fromView() operation that specifies the view with the rows to be exported.
- May filter the exported rows with a where() operation prior to any joins.
- May project columns from the exported rows with a select() operation prior to any joins.
- Must not limit, group, or sort over the exported view (either before or after any joins).
- May join other views with the exported view, applying any operation to a joined view prior to the join.
- May join documents or uris with the exported view.
- Must not specify parameter placeholders.
Pass the built plan to the withBatchView() method to initialize the RowBatcher with the plan.

Specify the number of threads for retrieving rows with the withThreadCount() method and the number of rows in a batch with the withBatchSize() method.

Specify a success listener for processing each batch of rows retrieved from the server. The RowBatcher passes a response event to the success listener. The success listener calls the RowBatchResponseEvent.getRowsDoc() method to to get the rows in the batch. The rows are returned as an instance of the Java class adapted by the sample handle passed to the factory that constructs the RowBatcher (that is, the generic type of the RowBatcher).
```
    RowBatcher<String> rowBatcher = ...construct the row batcher...;
    rowBatcher.onSuccess(event -> {
        String rowBatch = event.getRowsDoc();
        ...process the batch of rows...
        });
```
Specify a failure listener to handle any errors during retrieval.
See Also:

Exporting a TDE View

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`boolean`	`awaitCompletion()` Suspends execution of the current thread until either all rows have been retrieved from the view or the job is stopped.
`boolean`	`awaitCompletion(long timeout, java.util.concurrent.TimeUnit unit)` Suspends execution of the current thread until either all rows have been retrieved from the view, the job is stopped, or a timeout expires.
`long`	`getBatchCount()` The total number of batches of rows retrieved from the view.
`long`	`getFailedBatches()` The number of batches that the RowBatcher failed to retrieve from the view.
`RowBatchFailureListener[]`	`getFailureListeners()` Gets the callback functions for errors.
`long`	`getRowEstimate()` After the job is started, provides an estimate of the total number of rows to be exported from the view.
`RowManager`	`getRowManager()` Gets the RowManager for retrieving rows.
`java.lang.Long`	`getServerTimestamp()` If `withConsistentSnapshot` was used before starting the job, will return the MarkLogic server timestamp associated with the snapshot.
`RowBatchSuccessListener<T>[]`	`getSuccessListeners()` Gets the callback functions for successfully retrieved rows.
`RowBatcher<T>`	`onFailure(RowBatchFailureListener listener)` Supplies a callback function (typically, a lambda) for logging and specifying the disposition of errors.
`RowBatcher<T>`	`onSuccess(RowBatchSuccessListener<T> listener)` Supplies a callback function (typically, a lambda) for processing the batch of rows.
`void`	`setFailureListeners(RowBatchFailureListener... listeners)` Specifies the callback functions for errors when more than one callback function is needed.
`void`	`setSuccessListeners(RowBatchSuccessListener<T>... listeners)` Specifies the callback functions for successfully retrieved rows when more than one callback function is needed.
`RowBatcher<T>`	`withBatchSize(int batchSize)` Specifies the number of rows in each batch retrieved from the view.
`RowBatcher<T>`	`withBatchView(PlanBuilder.ModifyPlan viewPlan)` Specifies the plan for getting rows from a view with PlanBuilder.
`RowBatcher<T>`	`withBatchView(RawPlanDefinition viewPlan)` Specifies the plan for getting rows from a view from a serialized AST in JSON format.
`RowBatcher<T>`	`withBatchView(RawQueryDSLPlan viewPlan)` Specifies the plan for getting rows from a view from a serialized Query DSL in JavaScript format.
`RowBatcher<T>`	`withConsistentSnapshot()` Enables retrieval of rows that were present in the view at the time that the first batch was retrieved, ignoring subsequent changes to the view.
`RowBatcher<T>`	`withForestConfig(ForestConfiguration forestConfig)` Specifies the forest configuration, which also identifies the enodes for the cluster when not using a load balancer.
`RowBatcher<T>`	`withJobId(java.lang.String jobId)` Specifies the identifier for the job executed by the RowBatcher.
`RowBatcher<T>`	`withJobName(java.lang.String jobName)` Specifies the name for the job executed by the RowBatcher.
`RowBatcher<T>`	`withThreadCount(int threadCount)` Specifies how many batches of rows to retrieve concurrently from the view.

Methods inherited from interface com.marklogic.client.datamovement.Batcher
getBatchSize, getForestConfig, getJobEndTime, getJobId, getJobName, getJobStartTime, getJobTicket, getPrimaryClient, getThreadCount, isStarted, isStopped

- Method Detail
  - getRowManager
```
RowManager getRowManager()
```
    Gets the RowManager for retrieving rows.
    
    Returns:
    
    the RowManager for retrieving rows
  - withBatchView
```
RowBatcher<T> withBatchView(PlanBuilder.ModifyPlan viewPlan)
```
    Specifies the plan for getting rows from a view with PlanBuilder.
    
    Parameters:
    
    viewPlan - the PlanBuilder view providing the rows exported by the RowBatcher
    
    Returns:
    
    the RowBatcher for chaining other initializations
    
    See Also:
    
    RowManager.newPlanBuilder(), PlanBuilder.fromView(String, String)
  - withBatchView
```
RowBatcher<T> withBatchView(RawPlanDefinition viewPlan)
```
    Specifies the plan for getting rows from a view from a serialized AST in JSON format.
    
    Parameters:
    
    viewPlan - the raw AST for the rows exported by the RowBatcher
    
    Returns:
    
    the RowBatcher for chaining other initializations
    
    See Also:
    
    RowManager.newRawPlanDefinition(JSONWriteHandle)
  - withBatchView
```
RowBatcher<T> withBatchView(RawQueryDSLPlan viewPlan)
```
    Specifies the plan for getting rows from a view from a serialized Query DSL in JavaScript format.
    
    Parameters:
    
    viewPlan - the raw Query DSL for the rows exported by the RowBatcher
    
    Returns:
    
    the RowBatcher for chaining other initializations
    
    See Also:
    
    RowManager.newRawQueryDSLPlan(TextWriteHandle)
  - withConsistentSnapshot
```
RowBatcher<T> withConsistentSnapshot()
```
    Enables retrieval of rows that were present in the view at the time that the first batch was retrieved, ignoring subsequent changes to the view.
    
    Returns:
    
    the RowBatcher for chaining other initializations
  - onSuccess
```
RowBatcher<T> onSuccess(RowBatchSuccessListener<T> listener)
```
    Supplies a callback function (typically, a lambda) for processing the batch of rows. The callback receives a RowBatchResponseEvent parameter and can call the event's getRowsDoc() method to get the rows as an instance of the Java class adapted by the sample handle used to construct the RowBatcher.
    
    Parameters:
    
    listener - The callback function that receives the rows
    
    Returns:
    
    the RowBatcher for chaining other initializations
  - onFailure
```
RowBatcher<T> onFailure(RowBatchFailureListener listener)
```
    Supplies a callback function (typically, a lambda) for logging and specifying the disposition of errors. The callback receives a RowBatchFailureEvent parameter for inspecting the number of retries of the error and overall failures and for setting the disposition of the error.
    
    Parameters:
    
    listener - The callback function that receives any errors
    
    Returns:
    
    the RowBatcher for chaining other initializations
  - withBatchSize
```
RowBatcher<T> withBatchSize(int batchSize)
```
    Specifies the number of rows in each batch retrieved from the view.
    
    Specified by:
    
    withBatchSize in interface Batcher
    
    Parameters:
    
    batchSize - the number of rows in a batch
    
    Returns:
    
    the RowBatcher for chaining other initializations
  - withForestConfig
```
RowBatcher<T> withForestConfig(ForestConfiguration forestConfig)
```
    Specifies the forest configuration, which also identifies the enodes for the cluster when not using a load balancer.
    
    Specified by:
    
    withForestConfig in interface Batcher
    
    Parameters:
    
    forestConfig - the updated forest configuration
    
    Returns:
    
    the RowBatcher for chaining other initializations
  - withJobId
```
RowBatcher<T> withJobId(java.lang.String jobId)
```
    Specifies the identifier for the job executed by the RowBatcher.
    
    Specified by:
    
    withJobId in interface Batcher
    
    Parameters:
    
    jobId - the unique id you would like to assign to this job
    
    Returns:
    
    the RowBatcher for chaining other initializations
  - withJobName
```
RowBatcher<T> withJobName(java.lang.String jobName)
```
    Specifies the name for the job executed by the RowBatcher.
    
    Specified by:
    
    withJobName in interface Batcher
    
    Parameters:
    
    jobName - the name you would like to assign to this job
    
    Returns:
    
    the RowBatcher for chaining other initializations
  - withThreadCount
```
RowBatcher<T> withThreadCount(int threadCount)
```
    Specifies how many batches of rows to retrieve concurrently from the view.
    
    Specified by:
    
    withThreadCount in interface Batcher
    
    Parameters:
    
    threadCount - the number of threads to use in this Batcher
    
    Returns:
    
    the RowBatcher for chaining other initializations
  - getSuccessListeners
```
RowBatchSuccessListener<T>[] getSuccessListeners()
```
    Gets the callback functions for successfully retrieved rows.
    
    Returns:
    
    the success listeners
  - getFailureListeners
```
RowBatchFailureListener[] getFailureListeners()
```
    Gets the callback functions for errors.
    
    Returns:
    
    the failure listeners
  - setSuccessListeners
```
void setSuccessListeners(RowBatchSuccessListener<T>... listeners)
```
    Specifies the callback functions for successfully retrieved rows when more than one callback function is needed.
    
    Parameters:
    
    listeners - the success listeners
  - setFailureListeners
```
void setFailureListeners(RowBatchFailureListener... listeners)
```
    Specifies the callback functions for errors when more than one callback function is needed.
    
    Parameters:
    
    listeners - the failure listeners
  - awaitCompletion
```
boolean awaitCompletion()
```
    Suspends execution of the current thread until either all rows have been retrieved from the view or the job is stopped.
    
    Returns:
    
    true if all batches were processed
  - awaitCompletion
```
boolean awaitCompletion(long timeout,
                        java.util.concurrent.TimeUnit unit)
                 throws java.lang.InterruptedException
```
    Suspends execution of the current thread until either all rows have been retrieved from the view, the job is stopped, or a timeout expires.
    
    Parameters:
    
    timeout - the amount for the timeout
    
    unit - the unit of measure for the amount
    
    Returns:
    
    true if all batches were processed
    
    Throws:
    
    java.lang.InterruptedException - on interruption before the job finishes or timeout expires
  - getRowEstimate
```
long getRowEstimate()
```
    After the job is started, provides an estimate of the total number of rows to be exported from the view. To estimate progress, the row estimate can be compared to the rows retrieved so far, which can be estimated with getBatchCount() * getBatchSize() .
    
    Returns:
    
    the estimate of the view rows
  - getBatchCount
```
long getBatchCount()
```
    The total number of batches of rows retrieved from the view.
    
    Returns:
    
    the number of row batches
  - getFailedBatches
```
long getFailedBatches()
```
    The number of batches that the RowBatcher failed to retrieve from the view.
    
    Returns:
    
    the number of row batches
  - getServerTimestamp
```
java.lang.Long getServerTimestamp()
```
    If withConsistentSnapshot was used before starting the job, will return the MarkLogic server timestamp associated with the snapshot. Returns null otherwise.
    
    Returns:
    
    the timestamp or null

Interface RowBatcher<T>

Method Summary

Methods inherited from interface com.marklogic.client.datamovement.Batcher

Method Detail

getRowManager

withBatchView

withBatchView

withBatchView

withConsistentSnapshot

onSuccess

onFailure

withBatchSize

withForestConfig

withJobId

withJobName

withThreadCount

getSuccessListeners

getFailureListeners

setSuccessListeners

setFailureListeners

awaitCompletion

awaitCompletion

getRowEstimate

getBatchCount

getFailedBatches

getServerTimestamp