com.marklogic.client.datamovement

Class ApplyTransformListener

java.lang.Object

com.marklogic.client.datamovement.ApplyTransformListener

All Implemented Interfaces:

BatchListener<QueryBatch>, QueryBatchListener

public class ApplyTransformListener
extends java.lang.Object
implements QueryBatchListener

Modifies documents in-place in the database by applying a server-side transform. If the transform modifies documents to no longer match the query, ApplyTransformListener should only be used when:

1. merge timestamp is enabled and QueryBatcher.withConsistentSnapshot() is called, or
2. newQueryBatcher(Iterator<String>) is used to traverse a static data set

For example, given the REST transform myTransform.sjs:

    function transform_function(context, params, content) {
      var document = content.toObject();
      document.someProperty = params.newValue;
      return document;
    };
    exports.transform = transform_function;

installed in the server like so (using the MarkLogic Java Client API):

    restAdminClient.newServerConfigManager().newTransformExtensionsManager().writeJavascriptTransform(
      "myTransform", new FileHandle(new File("myTransform.sjs")));

you can run the transform on documents matching a query like so:

    ServerTransform transform = new ServerTransform(transformName2)
      .addParameter("newValue", "some new value");
    ApplyTransformListener listener = new ApplyTransformListener()
      .withTransform(transform)
      .withApplyResult(ApplyResult.REPLACE);
    QueryBatcher batcher = moveMgr.newQueryBatcher(query)
      .onUrisReady(listener);
    JobTicket ticket = moveMgr.startJob( batcher );
    batcher.awaitCompletion();
    moveMgr.stopJob(ticket);

As with all the provided listeners, this listener will not meet the needs of all applications but the source code for it should serve as helpful sample code so you can write your own custom listeners.

In this listener, we initialize only the HostAvailabilityListener's RetryListener and not NoResponseListener's RetryListener because if we get empty responses when we try to apply a transform to the batch of URIs retrieved from the server, we are not sure what happened in the server - if the transform has been applied or it has not been applied. Retrying in those scenarios would apply the transform twice if the transform has been already applied and this is not desirable.

In order to handle such scenarios where we get an empty response, it is recommended to add a BatchFailureListener which would take care of apply transform failures and retry only for those URIs for which the apply transform has failed. If the transform is idempotent, we can just initialize the RetryListener of the NoResponseListener by calling NoResponseListener.initializeRetryListener(this) and add it to the BatchFailureListeners similar to what we have in the other listeners.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ApplyTransformListener.ApplyResult Either ApplyTransformListener.ApplyResult.REPLACE each document with the result of the transform, or run the transform with each document as input, but ApplyTransformListener.ApplyResult.IGNORE the result.

Constructor Summary

Constructors

Constructor and Description
ApplyTransformListener()

Method Summary

Modifier and Type	Method and Description
void	initializeListener(QueryBatcher queryBatcher) This implementation of initializeListener adds this instance of ApplyTransformListener to the two RetryListener's in this QueryBatcher so they will retry any batches that fail during the apply-transform request.
ApplyTransformListener	onFailure(BatchFailureListener<QueryBatch> listener) When a batch fails or a callback throws an Exception, run this listener code.
ApplyTransformListener	onSkipped(QueryBatchListener listener) When documents were not found and therefore not transformed, run this listener code.
ApplyTransformListener	onSuccess(QueryBatchListener listener) When a batch has been successfully transformed, run this listener code.
void	processEvent(QueryBatch batch) The standard BatchListener action called by QueryBatcher.
ApplyTransformListener	withApplyResult(ApplyTransformListener.ApplyResult applyResult) Whether to REPLACE each document with the result of the transform, or run the transform with each document as input, but IGNORE the result.
ApplyTransformListener	withTransform(ServerTransform transform) The ServerTransform to run on each document from each batch.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ApplyTransformListener

public ApplyTransformListener()

Method Detail

initializeListener

public void initializeListener(QueryBatcher queryBatcher)

This implementation of initializeListener adds this instance of ApplyTransformListener to the two RetryListener's in this QueryBatcher so they will retry any batches that fail during the apply-transform request.

Specified by:

initializeListener in interface QueryBatchListener

Parameters:

queryBatcher - the QueryBatcher which will call this Listener

processEvent

public void processEvent(QueryBatch batch)

The standard BatchListener action called by QueryBatcher.

Specified by:

processEvent in interface BatchListener<QueryBatch>

Specified by:

processEvent in interface QueryBatchListener

Parameters:

batch - the batch of uris and some metadata about the current status of the job

onSuccess

public ApplyTransformListener onSuccess(QueryBatchListener listener)

When a batch has been successfully transformed, run this listener code. Multiple listeners can be registered with this method.

Parameters:

listener - the code to run when a batch is successfully transformed

Returns:

this instance for method chaining

onSkipped

public ApplyTransformListener onSkipped(QueryBatchListener listener)

When documents were not found and therefore not transformed, run this listener code. Multiple listeners can be registered with this method.

Parameters:

listener - the code to run when documents were not transformed

Returns:

this instance for method chaining

onFailure

public ApplyTransformListener onFailure(BatchFailureListener<QueryBatch> listener)

When a batch fails or a callback throws an Exception, run this listener code. Multiple listeners can be registered with this method.

Parameters:

listener - the code to run when a failure occurs

Returns:

this instance for method chaining

withTransform

public ApplyTransformListener withTransform(ServerTransform transform)

The ServerTransform to run on each document from each batch.

Parameters:

transform - the ServerTransform to run on each document from each batch

Returns:

this instance for method chaining

withApplyResult

public ApplyTransformListener withApplyResult(ApplyTransformListener.ApplyResult applyResult)

Whether to REPLACE each document with the result of the transform, or run the transform with each document as input, but IGNORE the result.

Parameters:

applyResult - the behavior required after each transform is run

Returns:

this instance for method chaining