Implementing a Sweep Action Handler

When you develop a sweep action handler, it is recommended that you code the handler in accordance with the following best practices, as demonstrated in the examples that follow:

• Use HandlerCallContext for trace logging.
• Use HandlerCallContext to determine whether the server is in the process of shutting down when the handler is called. At that top of your sweepItems processing loop, call the isShuttingDown method.
• By using a try-catch block, set the outcome for each item in the batch. For a SweepItem object processed successfully, the handler sets the item's outcome to SweepItemOutcome.PROCESSED. But if an exception is thrown, the handler's catch block sets the item's outcome to SweepItemOutcome.FAILED. For failure outcomes, the status value is persisted in the form of a CmSweepResult object.

  In general, handle all exceptions and do not allow them to propagate to the caller.

• Use the getRequiredProperties method. This method returns an array of names that specify the properties that are required for handler processing.

  The example handler requires the Id property because it logs that information for each SweepItem that it processes.

Java Example

import com.filenet.api.sweep.*;
import com.filenet.api.engine.SweepActionHandler;
import com.filenet.api.engine.SweepItemOutcome;
import com.filenet.api.core.*;
import com.filenet.api.constants.*;
import com.filenet.api.exception.*;

public class CustomSweepHandler implements SweepActionHandler
{
   // Implement for custom job and queue sweeps.
   public void onSweep(CmSweep sweepObject, SweepActionHandler.SweepItem [] sweepItems)
       throws EngineRuntimeException
   {
         HandlerCallContext hcc = HandlerCallContext.getInstance();
         hcc.traceDetail("Entering CustomSweepHandler.onSweep");
         hcc.traceDetail("sweepObject = " 
              + sweepObject.getProperties().getIdValue(PropertyNames.ID)
              + "  sweepItems.length = " + sweepItems.length);

        // Iterate the sweepItems and change the class.
        for (int i = 0; i < sweepItems.length; i++)
        {
           // At the top of your loop, always check to make sure 
           // that the server is not shutting down. 
           // If it is, clean up and return control to the server.
          
           if (hcc != null && hcc.isShuttingDown())
           { 
              throw new EngineRuntimeException(ExceptionCode.E_BACKGROUND_TASK_TERMINATED, 
                 this.getClass().getSimpleName() 
                 + " is terminating prematurely because the server is shutting down");
           }

           // Extract the target object from the SweepItem array.
           IndependentlyPersistableObject obj = sweepItems[i].getTarget();
           String msg = "sweepItems[" + i + "]= " + obj.getProperties().getIdValue("ID");
           hcc.traceDetail(msg);

           try 
           {
               Document doc = (Document) obj;
               doc.changeClass("{5C1D0459-7F8A-4D6F-A9D1-63C7B3F6A7A9}");
               doc.save(RefreshMode.NO_REFRESH);

               // Set outcome to PROCESSED if item processed successfully.
               sweepItems[i].setOutcome(SweepItemOutcome.PROCESSED,
                  "item processed by " + this.getClass().getSimpleName());
           }
           // Set failure status on objects that fail to process.
           catch (EngineRuntimeException e)
           {
               sweepItems[i].setOutcome(SweepItemOutcome.FAILED, 
                   "CustomSweepHandler: " + e.getMessage());
           }
       }
       hcc.traceDetail("Exiting CustomSweepHandler.onSweep");
    }

    /* 
     * Called automatically when the handler is invoked by a custom sweep job or sweep policy.
     * Specify properties required by the handler, if any.
     * If you return an empty array, then all properties are fetched.
     */
    public String [] getRequiredProperties()
    {
        String [] names = {PropertyNames.ID};
        return names;
    }
	
    /* Implement for custom sweep policies.
     * This method is not implemented because this is an example of a custom sweep job.
     */
    public void onPolicySweep(CmSweep sweepObject,CmSweepPolicy policyObject, 
        SweepActionHandler.SweepItem [] sweepItems)
    {}
}

JavaScript Example

importPackage(Packages.com.filenet.api.core);
importPackage(Packages.com.filenet.api.constants);
importPackage(Packages.com.filenet.api.exception);
importPackage(Packages.com.filenet.api.sweep);
importPackage(Packages.com.filenet.api.engine);

// Implement for custom job and queue sweeps.
function onSweep (sweepObject, sweepItems)
{	
    var hcc = HandlerCallContext.getInstance();
    hcc.traceDetail("Entering CustomSweepHandler.onSweep");
    hcc.traceDetail("sweepObject = " 
              + sweepObject.getProperties().getIdValue(PropertyNames.ID)
              + "sweepItems.length = " + sweepItems.length);

    // Iterate the sweepItems and change the class.
    ii = 0;
    for (ii = 0; ii < sweepItems.length; ii++)
    {
       // At the top of your loop, always check to make sure 
       // that the server is not shutting down. 
       // If it is, clean up and return control to the server.
       if (hcc != null && hcc.isShuttingDown())
       { 
          throw new EngineRuntimeException(ExceptionCode.E_BACKGROUND_TASK_TERMINATED,        
            this.constructor.name + " is terminating prematurely because the server is shutting down");
       }

       var item = sweepItems[ii].getTarget();
       var msg = "sweepItems[" + ii + "]= " + item.getProperties().getIdValue("ID");
       hcc.traceDetail(msg);

       try 
       {
          var doc = Document (item);
          doc.changeClass("{5C1D0459-7F8A-4D6F-A9D1-63C7B3F6A7A9}");
          doc.save(RefreshMode.NO_REFRESH);

          // Set outcome to PROCESSED if item processed successfully.
          sweepItems[ii].setOutcome(SweepItemOutcome.PROCESSED,
                "item processed by " + this.constructor.name);
       }
       // Set failure status on objects that fail to process.
       catch (ioe)
       {
          sweepItems[ii].setOutcome(SweepItemOutcome.FAILED, "CustomSweepHandler: " +
              ioe.rhinoException.getMessage());
       }
    }
    hcc.traceDetail("Exiting CustomSweepHandler.onSweep");
}

/* 
 * Called automatically when the handler is invoked by a custom sweep job 
 * or sweep policy. Specify properties required by the handler, if any.
 * If you return an empty array, then all properties are fetched.
 */
function getRequiredProperties()
{
    var pnames = ['Id'];
    return pnames.toString();	
}

/* Implement for custom sweep policies.
 * This method is not implemented because this is an example of a custom sweep job.
 */
function onPolicySweep (sweepObject, policyObject, sweepItems)
{}