javax.servlet.jsp.tagext.SimpleTag Maven / Gradle / Ivy
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 1997-2010 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*
*
* This file incorporates work covered by the following copyright and
* permission notice:
*
* Copyright 2004 The Apache Software Foundation
*
* Licensed 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 javax.servlet.jsp.JspContext;
/**
* Interface for defining Simple Tag Handlers.
*
* Simple Tag Handlers differ from Classic Tag Handlers in that instead
* of supporting doStartTag() and doEndTag(),
* the SimpleTag interface provides a simple
* doTag() method, which is called once and only once for any
* given tag invocation. All tag logic, iteration, body evaluations, etc.
* are to be performed in this single method. Thus, simple tag handlers
* have the equivalent power of BodyTag, but with a much
* simpler lifecycle and interface.
*
* To support body content, the setJspBody()
* method is provided. The container invokes the setJspBody()
* method with a JspFragment object encapsulating the body of
* the tag. The tag handler implementation can call
* invoke() on that fragment to evaluate the body as
* many times as it needs.
*
* A SimpleTag handler must have a public no-args constructor. Most
* SimpleTag handlers should extend SimpleTagSupport.
*
* Lifecycle
*
* The following is a non-normative, brief overview of the
* SimpleTag lifecycle. Refer to the JSP Specification for details.
*
*
* - A new tag handler instance is created each time by the container
* by calling the provided zero-args constructor. Unlike classic
* tag handlers, simple tag handlers are never cached and reused by
* the JSP container.
* - The
setJspContext() and setParent()
* methods are called by the container. The setParent()
* method is only called if the element is nested within another tag
* invocation.
* - The setters for each attribute defined for this tag are called
* by the container.
* - If a body exists, the
setJspBody() method is called
* by the container to set the body of this tag, as a
* JspFragment. If the action element is empty in
* the page, this method is not called at all.
* - The
doTag() method is called by the container. All
* tag logic, iteration, body evaluations, etc. occur in this
* method.
* - The
doTag() method returns and all variables are
* synchronized.
*
*
* @see SimpleTagSupport
* @since JSP 2.0
*/
public interface SimpleTag extends JspTag {
/**
* Called by the container to invoke this tag.
* The implementation of this method is provided by the tag library
* developer, and handles all tag processing, body iteration, etc.
*
*
* The JSP container will resynchronize any AT_BEGIN and AT_END
* variables (defined by the associated tag file, TagExtraInfo, or TLD)
* after the invocation of doTag().
*
* @throws javax.servlet.jsp.JspException If an error occurred
* while processing this tag.
* @throws javax.servlet.jsp.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 java.io.IOException If there was an error writing to the
* output stream.
*/
public void doTag()
throws javax.servlet.jsp.JspException, java.io.IOException;
/**
* Sets the parent of this tag, for collaboration purposes.
*
* The container invokes this method only if this tag invocation is
* nested within another tag invocation.
*
* @param parent the tag that encloses this tag
*/
public void setParent( JspTag parent );
/**
* Returns the parent of this tag, for collaboration purposes.
*
* @return the parent of this tag
*/
public JspTag getParent();
/**
* Called by the container to provide this tag handler with
* the JspContext for this invocation.
* An implementation should save this value.
*
* @param pc the page context for this invocation
* @see Tag#setPageContext
*/
public void setJspContext( JspContext pc );
/**
* Provides the body of this tag as a JspFragment object, able to be
* invoked zero or more times by the tag handler.
*
* This method is invoked by the JSP page implementation
* object prior to doTag(). If the action element is
* empty in the page, this method is not called at all.
*
* @param jspBody The fragment encapsulating the body of this tag.
*/
public void setJspBody( JspFragment jspBody );
}