Package org.jesterj.ingest.processors

Class WrappingProcessor

  • All Implemented Interfaces:
    Configurable, DocumentProcessor
    public class WrappingProcessor
extends java.lang.Object
implements DocumentProcessor
    A processor that can execute arbitrary code before/after an existing processor. Note that it is an anti-pattern to build a chain of WrappingProcessors one wrapping the other because this defeats the fault tolerance features of the framework by turning several steps into a single step.

    • Constructor Detail

      • WrappingProcessor

        public WrappingProcessor()

    • Method Detail

      • processDocument

        public Document[] processDocument​(Document document)
        Description copied from interface: DocumentProcessor
        Mutate, validate or transmit a document. Implementations must not throw any * Throwable that is not a JVM Error and should be written expecting the possibility that the code might be interrupted at any point. Practically this means Document processors should perform no more than one persistent or externally visible actions and that action should be transactional. Large complex processors that write to disk, DB, or elsewhere multiple times run the risk of partial completion. Similarly, since JesterJ is a long-running system it will often cease operation due to unexpected outages (power cord, etc.), so it is not a good idea to hold resources that require an explicit release or "return". "Check then write" is of course a performance anti-pattern with respect to external networked or disk resources since network and disk io are typically slow to access. Processors should feel free to set the status of a document and add a status message via Document.setStatus(Status, String, java.io.Serializable...) however the easiest way to communicate a failure (for which all further processing is in error) is to simply throw a runtime exception. The document processor has no need to add the document to the next step in the plan as this will be handled by the infrastructure in StepImpl based on the status of the document so long as the document is emitted via the return value of this method. If the document enters via the parameters and is not emitted for any reason the processor MUST set an appropriate status before the end of this method, though it is preferable to just set the status and emit it.
        Specified by:
        processDocument in interface DocumentProcessor
        Parameters:
        document - the item to process
        Returns:
        The documents that result from the processing in this step. Documents with status of Status.PROCESSING will be processed by subsequent steps, and documents with any other status will have their status recorded and will not be processed by subsequent steps.

      • getName

        public java.lang.String getName()
        Description copied from interface: Configurable
        A name for this object to distinguish it from other objects. This value is generally supplied by the plan author. Every object in a plan must have a unique name, begin with a letter and only contain letters, digits, underscores and periods.
        Specified by:
        getName in interface Configurable
        Returns:
        The user supplied name for this step

      • before

        public void before​(Document document)
        Execute some code before a document is processed. Possibly used to cache field values or clear threadlocal variables etc. If this method throws an exception the wrapped processor will not execute, but error and always will.
        Parameters:
        document - the document to be processed by the wrapped processor

      • success

        public Document[] success​(Document[] results)
        Override to execute some code after a document has successfully been processed by the wrapped processor. Successful is defined as "not throwing an exception". If this method throws an exception it will be processed by the error method of this class, but the
        Parameters:
        results - the document(s) produced by the action of the wrapped procesor
        Returns:
        the (possibly edited) documents to be passed on to subsequent steps. No element of this array should be null. If documents need to be removed, then a new array should be created omitting the desired documents.

      • error

        public boolean error​(java.lang.Exception e,
                     Document original,
                     Document[][] results)
        Override to execute some code in the even that the wrapped processor throws an exception. The exception can be swallowed by returning false, but the default implementation returns true. It is possible to use this method to entirely edit the reslts of processing and continue (or not) in the event of an error. The return value controls whether or not the error is re-thrown, or the code may simply throw it's own preferred RuntimeException. If the error is not re-thrown this method must verify and ensure that results[0] contains an array of at least one document and no null documents.
        Parameters:
        e - the exception that lead to the invocation of this method.
        original - the document that caused the exception
        results - 1 by N array of documents setting a new array into results[0] will replace the results entirely, whereas setting results[0][n] will replace a single document. If this method returns false (indicating no error) then results[0] will be passed to the next step.
        Returns:
        true if the exception should be re-thrown, or false if it should be swallowed.

      • always

        public void always​(Document original)
        Override to execute some code regardless of the success, failure or any other machinations of any of the other methods. This can be used for things like clearing thread locals or other code that really must run no matter how ugly the prior processing gets. This is the sole method executed in a finally block following the processing of all other methods. The following implementation is guaranteed: 
        
   public Document[] processDocument(Document document) {
     // nothing that can throw/fail here
     try {
       // stuff that might succceed
     } catch (Exception e) {
       // anything we do if things go wrong
     } finally {
       always(document);
     }
   }
        Parameters:
        original - the original document that was passed to the processDocumentMethod. NOTE: this is not a copy of the document as it was, but the result whatever processing was attempted. If you need a faithful copy of the original you should make one in an overridden before() method, hold it in a field and use/clear the field here.

      • setName

        public void setName​(java.lang.String name)