com.memority.toolkit.rule.api.Rule Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of toolkit-rule-api Show documentation

This artifact provides the API classes that are necessary to implement the contracts of Memority configuration Rules.

There is a newer version: 3.43.1

/*
 * Copyright (c) 2016-2023 Memority. All Rights Reserved.
 *
 * This file is part of Memority Toolkit API , a Memority project.
 *
 * This file is released under the Memority Public Artifacts End-User License Agreement,
 * see 
 * Unauthorized copying of this file, via any medium is strictly prohibited.
 */
package com.memority.toolkit.rule.api;

import com.memority.toolkit.rule.api.context.Context;
import com.memority.toolkit.rule.api.context.RuleContext;

import java.lang.annotation.Annotation;
import java.util.HashMap;

/**
 * A Rule is a function that is executed with a given {@link Context}
 * and that returns a value that will be used for business purposes. A Rule execution should never have
 * a side effect and must be thread safe.
 *
 * The various Rule signatures, for each {@link RuleType}, are expressed by child interfaces.
 */
public interface Rule {

    /**
     * @return the rule category
     */
    RuleCategory getCategory();

    /**
     * @return the rule type
     */
    RuleType getRuleType();

    /**
     * @return the Api available to this rule
     */
    Api getApi();

    /**
     * Retrieves some metadata about the rule in the form of an annotation. Where the annotation comes from is engine
     * specific. For example, the groovy engine may retrieve the annotations from the underlying groovy class.
     * @param annotationType the wanted annotation type
     * @param useCache instructs the rule engine to use its cache or not, if any. Useful eg. with groovy engine, when
     *                 temporarily overriding the compiler configuration.
     * @param  the wanted annotation type
     * @return the corresponding annotation (maybe null)
     */
    default  T getRuleAnnotation(Class annotationType, boolean useCache) {
        return null;
    }

    /**
     * Equivalent to {{@link #getRuleAnnotation(Class, boolean)}} with useCache = true.
     * @param annotationType the wanted annotation type
     * @param  the wanted annotation type
     * @return the corresponding annotation (maybe null)
     */
    @SuppressWarnings("unused") //API method
    default  T getRuleAnnotation(Class annotationType) {
        return getRuleAnnotation(annotationType, true);
    }

    /**
     * A simple Map representing the API that is available to the Rule. This can include
     * any data or service that is made available to the rule when executing. Actual
     * content is dependant upon the environment and rule characteristics.
     */
    class Api extends HashMap {
        @SuppressWarnings("unchecked") // known risk, utility method
        public  O obtain(String key) {
            return (O) this.get(key);
        }
    }

    /**
     * Used to reset timeout for the stateful object returned by rule
     * See Jira issue CTD-6826


     *
     * Implementation notes: implementation is engine dependent. For Sandboxed Groovy, see
     * GroovySandbox#resetTimeout
     *
     * @param objectToReset the stateful object returned by rule
     */
    default void resetTimeout(Object objectToReset) {
        //NOOP by default, as timeout is only applicable to sandboxed script rules
    }
}