UnRAVLAssertion.java

package com.sas.unravl.assertions;

import com.fasterxml.jackson.databind.node.ObjectNode;
import com.sas.unravl.ApiCall;
import com.sas.unravl.UnRAVL;
import com.sas.unravl.UnRAVLException;
import com.sas.unravl.UnRAVLPlugins;

/**
 * An UnRAVL script assertion. Assertion objects run as preconditions before
 * invoking an API call, or as assertions on the results of the API call,
 * checking the status code, headers, response body, or variables, etc. An
 * {@link UnRAVL} script will load UnRAVLAssertion objects while executing the
 * "preconditions" or "assert" members of the script. The first field in the
 * assertion member is used as the key, i.e.
 *
 * <pre>
 * { "headers" : specification }
 * </pre>
 *
 * is a headers assertion which uses the key "headers". The assertion class is
 * found in the {@link UnRAVLPlugins} list of assertions, and instantiated.
 * Then, the {@link #check(UnRAVL, ObjectNode, Stage, ApiCall)} method is run,
 * passing the currently executing {@link UnRAVL} script and the JsonNode
 * element that defines the assertion specification (in this case, the value
 * associated with "headers")
 * <p>
 * Assertions should extend {@link BaseUnRAVLAssertion} and their check() method
 * should invoke super.check(script,node)
 *
 * @author David.Biesack@sas.com
 */
public interface UnRAVLAssertion {

    public static enum Stage {
        PRECONDITIONS, ASSERT;
        public String getName() {
            return toString().toLowerCase();
        }
    };

    /**
     * execute the assertion within the given script
     *
     * @param script
     *            the currently running script
     * @param assertion
     *            the JSON object node which defines this assertion.
     * @param stage
     *            Indicates which stage is running, "preconditions" or "assert"
     * @param call
     *            The currently running API call
     * @throws UnRAVLAssertionException
     *             if the assertion fails
     * @throws UnRAVLException
     *             if the assertion definition is invalid
     */
    public void check(UnRAVL script, ObjectNode assertion, Stage stage,
            ApiCall call) throws UnRAVLAssertionException, UnRAVLException;

    /**
     * Return the UnRAVLAssertionException, if running this assertion had an
     * exception
     * 
     * @return a caught assertion exception
     */
    public UnRAVLAssertionException getUnRAVLAssertionException();

    /**
     * Set the UnRAVLAssertionException, if running this assertion had an
     * exception
     * 
     * @param e
     *            an exception
     */
    public void setUnRAVLAssertionException(UnRAVLAssertionException e);

    /**
     * Set the scriptlet that defines this assertion
     * 
     * @param node
     *            the current node this assertion is processing
     */
    public void setAssertion(ObjectNode node);

    /**
     * Get the scriptlet that defines this assertion
     * 
     * @return the current assertion element scirptlet
     */
    public ObjectNode getAssertion();

    /**
     * Set the UnRAVL script that this instance is running in
     * 
     * @param script
     *            the current UnRAVL script
     */
    public void setScript(UnRAVL script);

    /**
     * Get the UnRAVL script that this instance is running in
     * 
     * @return the script object
     */
    public UnRAVL getScript();

    /**
     * Set the UnRAVL stage (PRECONDITIONS, ASSERT) that this instance is
     * running in
     * 
     * @param stage
     *            which ssertion stage this instance is running in
     */
    public void setStage(Stage stage);

    /**
     * @return the UnRAVL stage (PRECONDITIONS, ASSERT) that this instance is
     *         running in.
     */
    public Stage getStage();
}