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)
{
}
}