/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package javax.servlet.jsp.tagext;

import java.io.IOException;

import javax.servlet.jsp.JspContext;
import javax.servlet.jsp.JspException;
import javax.servlet.jsp.SkipPageException;

/**
 * A base class for defining tag handlers implementing SimpleTag.
 * <p>
 * The SimpleTagSupport class is a utility class intended to be used as the base class for new simple tag handlers. The
 * SimpleTagSupport class implements the SimpleTag interface and adds additional convenience methods including getter
 * methods for the properties in SimpleTag.
 *
 * @since JSP 2.0
 */
public class SimpleTagSupport implements SimpleTag {
    /** Reference to the enclosing tag. */
    private JspTag parentTag;

    /** The JSP context for the upcoming tag invocation. */
    private JspContext jspContext;

    /** The body of the tag. */
    private JspFragment jspBody;

    /**
     * Sole constructor. (For invocation by subclass constructors, typically implicit.)
     */
    public SimpleTagSupport() {
        // NOOP by default
    }

    /**
     * Default processing of the tag does nothing.
     *
     * @throws JspException      Subclasses can throw JspException to indicate an error occurred while processing this
     *                               tag.
     * @throws SkipPageException If the page that (either directly or indirectly) invoked this tag is to cease
     *                               evaluation. A Simple Tag Handler generated from a tag file must throw this
     *                               exception if an invoked Classic Tag Handler returned SKIP_PAGE or if an invoked
     *                               Simple Tag Handler threw SkipPageException or if an invoked Jsp Fragment threw a
     *                               SkipPageException.
     * @throws IOException       Subclasses can throw IOException if there was an error writing to the output stream
     *
     * @see SimpleTag#doTag()
     */
    @Override
    public void doTag() throws JspException, IOException {
        // NOOP by default
    }

    /**
     * Sets the parent of this tag, for collaboration purposes.
     * <p>
     * The container invokes this method only if this tag invocation is nested within another tag invocation.
     *
     * @param parent the tag that encloses this tag
     */
    @Override
    public void setParent(JspTag parent) {
        this.parentTag = parent;
    }

    /**
     * Returns the parent of this tag, for collaboration purposes.
     *
     * @return the parent of this tag
     */
    @Override
    public JspTag getParent() {
        return this.parentTag;
    }

    /**
     * Stores the provided JSP context in the private jspContext field. Subclasses can access the
     * <code>JspContext</code> via <code>getJspContext()</code>.
     *
     * @param pc the page context for this invocation
     *
     * @see SimpleTag#setJspContext
     */
    @Override
    public void setJspContext(JspContext pc) {
        this.jspContext = pc;
    }

    /**
     * Returns the page context passed in by the container via setJspContext.
     *
     * @return the page context for this invocation
     */
    protected JspContext getJspContext() {
        return this.jspContext;
    }

    /**
     * Stores the provided JspFragment.
     *
     * @param jspBody The fragment encapsulating the body of this tag. If the action element is empty in the page, this
     *                    method is not called at all.
     *
     * @see SimpleTag#setJspBody
     */
    @Override
    public void setJspBody(JspFragment jspBody) {
        this.jspBody = jspBody;
    }

    /**
     * Returns the body passed in by the container via setJspBody.
     *
     * @return the fragment encapsulating the body of this tag, or null if the action element is empty in the page.
     */
    protected JspFragment getJspBody() {
        return this.jspBody;
    }

    /**
     * Find the instance of a given class type that is closest to a given instance. This method uses the getParent
     * method from the Tag and/or SimpleTag interfaces. This method is used for coordination among cooperating tags.
     * <p>
     * For every instance of TagAdapter encountered while traversing the ancestors, the tag handler returned by
     * <code>TagAdapter.getAdaptee()</code> - instead of the TagAdapter itself - is compared to <code>klass</code>. If
     * the tag handler matches, it - and not its TagAdapter - is returned.
     * <p>
     * The current version of the specification only provides one formal way of indicating the observable type of a tag
     * handler: its tag handler implementation class, described in the tag-class subelement of the tag element. This is
     * extended in an informal manner by allowing the tag library author to indicate in the description subelement an
     * observable type. The type should be a subtype of the tag handler implementation class or void. This additional
     * constraint can be exploited by a specialized container that knows about that specific tag library, as in the case
     * of the JSP standard tag library.
     * <p>
     * When a tag library author provides information on the observable type of a tag handler, client programmatic code
     * should adhere to that constraint. Specifically, the Class passed to findAncestorWithClass should be a subtype of
     * the observable type.
     *
     * @param from  The instance from where to start looking.
     * @param klass The subclass of JspTag or interface to be matched
     *
     * @return the nearest ancestor that implements the interface or is an instance of the class specified
     */
    public static final JspTag findAncestorWithClass(JspTag from, Class<?> klass) {
        boolean isInterface = false;

        if (from == null || klass == null ||
                !JspTag.class.isAssignableFrom(klass) && !(isInterface = klass.isInterface())) {
            return null;
        }

        for (;;) {
            JspTag parent = null;
            if (from instanceof SimpleTag) {
                parent = ((SimpleTag) from).getParent();
            } else if (from instanceof Tag) {
                parent = ((Tag) from).getParent();
            }
            if (parent == null) {
                return null;
            }

            if (parent instanceof TagAdapter) {
                parent = ((TagAdapter) parent).getAdaptee();
            }

            if (isInterface && klass.isInstance(parent) || klass.isAssignableFrom(parent.getClass())) {
                return parent;
            }

            from = parent;
        }
    }
}
