001 /* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017 018 package javax.servlet.jsp.tagext; 019 020 import java.io.IOException; 021 import java.io.Writer; 022 import javax.servlet.jsp.*; 023 024 /** 025 * Encapsulates a portion of JSP code in an object that 026 * can be invoked as many times as needed. JSP Fragments are defined 027 * using JSP syntax as the body of a tag for an invocation to a SimpleTag 028 * handler, or as the body of a <jsp:attribute> standard action 029 * specifying the value of an attribute that is declared as a fragment, 030 * or to be of type JspFragment in the TLD. 031 * <p> 032 * The definition of the JSP fragment must only contain template 033 * text and JSP action elements. In other words, it must not contain 034 * scriptlets or scriptlet expressions. At translation time, the 035 * container generates an implementation of the JspFragment abstract class 036 * capable of executing the defined fragment. 037 * <p> 038 * A tag handler can invoke the fragment zero or more times, or 039 * pass it along to other tags, before returning. To communicate values 040 * to/from a JSP fragment, tag handlers store/retrieve values in 041 * the JspContext associated with the fragment. 042 * <p> 043 * Note that tag library developers and page authors should not generate 044 * JspFragment implementations manually. 045 * <p> 046 * <i>Implementation Note</i>: It is not necessary to generate a 047 * separate class for each fragment. One possible implementation is 048 * to generate a single helper class for each page that implements 049 * JspFragment. Upon construction, a discriminator can be passed to 050 * select which fragment that instance will execute. 051 * 052 * @since 2.0 053 */ 054 public abstract class JspFragment { 055 056 /** 057 * Executes the fragment and directs all output to the given Writer, 058 * or the JspWriter returned by the getOut() method of the JspContext 059 * associated with the fragment if out is null. 060 * 061 * @param out The Writer to output the fragment to, or null if 062 * output should be sent to JspContext.getOut(). 063 * @throws javax.servlet.jsp.JspException Thrown if an error occured 064 * while invoking this fragment. 065 * @throws javax.servlet.jsp.SkipPageException Thrown if the page 066 * that (either directly or indirectly) invoked the tag handler that 067 * invoked this fragment is to cease evaluation. The container 068 * must throw this exception if a Classic Tag Handler returned 069 * Tag.SKIP_PAGE or if a Simple Tag Handler threw SkipPageException. 070 * @throws java.io.IOException If there was an error writing to the 071 * stream. 072 */ 073 public abstract void invoke( Writer out ) 074 throws JspException, IOException; 075 076 /** 077 * Returns the JspContext that is bound to this JspFragment. 078 * 079 * @return The JspContext used by this fragment at invocation time. 080 */ 081 public abstract JspContext getJspContext(); 082 083 }