# PatternWorker.java

    /*
    ** Module   : PatternWorker.java
    ** Abstract : Interface for pattern workers
    **
    ** Copyright (c) 2005-2022, Golden Code Development Corporation.
    **
    ** -#- -I- --Date-- --JPRM-- ----------------------------------Description-----------------------------------
    ** 001 ECF 20050228   @20133 Created initial version. Defines an API for
    **                           pattern engine support objects.
    ** 002 ECF 20050310   @20276 Added resolveToLiteral method. PatternEngine
    **                           uses this method to resolve constants to
    **                           literals for the expression parser.
    ** 003 ECF 20050315   @20343 Added visitAst method. This method is invoked
    **                           when a new AST is about to be processed.
    ** 004 ECF 20050430   @20963 Changes related to namespace support for user
    **                           functions and variables. Pattern engine is no
    **                           longer a parameter to the initialize and
    **                           finish methods.
    ** 005 ECF 20050525   @21289 Changes to support new expression engine
    **                           implementation. Added getLibrary method and
    **                           renamed resolveToLiteral to resolveConstant.
    ** 006 GES 20090518   @42387 Import change.
    ** 007 ECF 20220515          Added leaveAst method and made some methods no-ops by default.
    */
    /*
    ** This program is free software: you can redistribute it and/or modify
    ** it under the terms of the GNU Affero General Public License as
    ** published by the Free Software Foundation, either version 3 of the
    ** License, or (at your option) any later version.
    **
    ** This program is distributed in the hope that it will be useful,
    ** but WITHOUT ANY WARRANTY; without even the implied warranty of
    ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    ** GNU Affero General Public License for more details.
    **
    ** You may find a copy of the GNU Affero GPL version 3 at the following
    ** location: https://www.gnu.org/licenses/agpl-3.0.en.html
    **
    ** Additional terms under GNU Affero GPL version 3 section 7:
    **
    **   Under Section 7 of the GNU Affero GPL version 3, the following additional
    **   terms apply to the works covered under the License.  These additional terms
    **   are non-permissive additional terms allowed under Section 7 of the GNU
    **   Affero GPL version 3 and may not be removed by you.
    **
    **   0. Attribution Requirement.
    **
    **     You must preserve all legal notices or author attributions in the covered
    **     work or Appropriate Legal Notices displayed by works containing the covered
    **     work.  You may not remove from the covered work any author or developer
    **     credit already included within the covered work.
    **
    **   1. No License To Use Trademarks.
    **
    **     This license does not grant any license or rights to use the trademarks
    **     Golden Code, FWD, any Golden Code or FWD logo, or any other trademarks
    **     of Golden Code Development Corporation. You are not authorized to use the
    **     name Golden Code, FWD, or the names of any author or contributor, for
    **     publicity purposes without written authorization.
    **
    **   2. No Misrepresentation of Affiliation.
    **
    **     You may not represent yourself as Golden Code Development Corporation or FWD.
    **
    **     You may not represent yourself for publicity purposes as associated with
    **     Golden Code Development Corporation, FWD, or any author or contributor to
    **     the covered work, without written authorization.
    **
    **   3. No Misrepresentation of Source or Origin.
    **
    **     You may not represent the covered work as solely your work.  All modified
    **     versions of the covered work must be marked in a reasonable way to make it
    **     clear that the modified work is not originating from Golden Code Development
    **     Corporation or FWD.  All modified versions must contain the notices of
    **     attribution required in this license.
    */

    package com.goldencode.p2j.pattern;

    import com.goldencode.ast.*;

    /**
     * Each pattern engine worker class which provides variable and/or user
     * function resolution support must implement this interface to perform
     * initialization and termination processing, and to receive notifications
     * from the pattern engine of processing events, such as a new AST being
     * processed, or a new level of a call tree being processed. The worker is
     * also given a chance to resolve expression constant values to literal
     * values.
     */
    public interface PatternWorker
    {
       /**
        * This method is called once (and only once) per invocation of the
        * pattern engine's {@link PatternEngine#run} method, immediately after
        * the worker object is constructed. This hook is provided to give the
        * worker implementation an opportunity to register symbol resolution
        * libraries with the pattern engine's symbol resolver, as well as to
        * perform any internal initialization.
        */
       public default void initialize()
       {
       }

       /**
        * This method is called once (and only once) per invocation of the
        * pattern engine's {@link PatternEngine#run} method, after all rulesets
        * are processed, and after the pattern engine's own global post-rules
        * are processed. This hook is provided to allow the worker implementation
        * to perform any necessary resource cleanup or other post-processing. It
        * is safe to assume that no rule will be executed after this method
        * completes.
        */
       public default void finish()
       {
       }

       /**
        * This method should return a worker library to be registered with the
        * expression engine's symbol resolver, if the implementation wishes to
        * expose bean-like properties or user functions to user expressions.
        * <p>
        * It is invoked by a {@link RuleContainer} when it registers the
        * pattern worker implementation.
        *
        * @return  A worker library object, or <code>null</code> if the pattern
        *          worker implementation does not need to register a library.
        */
       public Object getLibrary();

       /**
        * This method is called each time the pattern engine needs to resolve
        * a string constant into a numeric, boolean, or string literal value.
        * <p>
        * It must return an object of the following type (or <code>null</code>):
        * <ul>
        * <li>Integer
        * <li>Long
        * <li>Float
        * <li>Double
        * <li>Boolean
        * <li>String
        * </ul>

        * @param   constant
        *          A string representing a constant to be resolved.
        *
        * @return  A numeric, boolean, or string literal, or <code>null</code>
        *          if <code>constant</code> was not recognized as a placeholder
        *          for a literal.
        */
       public Object resolveConstant(String constant);

       /**
        * This method is called each time a new AST is visited, just before the
        * pattern engine processes that AST. At the time this method is invoked,
        * the resolver is not yet configured with the any source or target AST
        * node, so the source AST is passed as a parameter, in case the worker
        * needs to extract information.
        *
        * @param   ast
        *          The root node of the <strong>source</strong> AST about to be processed by the pattern engine
        *          By convention, the worker should not modify this AST now or during the walk.
        */
       public default void visitAst(Aast ast)
       {
       }

       /**
        * This method is called each time an AST walk is complete, to permit cleanup scoped to that AST walk.
        *
        * @param   ast
        *          The root node of the <strong>copy</strong> AST just processed by the pattern engine. This is
        *          not the same AST instance passed to {@link #visitAst(Aast)} at the beginning of the walk;
        *          this AST may have been annotated and otherwise modified during the walk.
        */
       public default void leaveAst(Aast ast)
       {
       }
    }