Java Server Pages 2nd Edition phần 10 ppsx

BodyContent The container creates an instance of the BodyContent class to encapsulate the element body of a custom action element if the corresponding tag handler implements the BodyTag

double quotes, slashes, question marks, at signs, colons, and semicolons Empty values may not behave the same way on all browsers

public void setVersion(int version)

Sets the version of the cookie protocol this cookie complies with A value of 0 means that the cookie must be sent to the browser as described by the original Netscape specification; 1 that the cookie must be sent as defined by RFC 2109

RequestDispatcher

The RequestDispatcher class defines an object that receives requests from the client and sends them to any resource (such as a servlet, HTML file, or JSP file) in the same web container The container creates the RequestDispatcher object, which is used as a wrapper around a resource located at a particular URI path or identified by a particular name

public void forward(ServletRequest req, ServletResponse res)

Forwards a request from a servlet to another resource (servlet, JSP file, or HTML file)

getRequestDispatcher( ), the ServletRequest object has its path elements and parameters adjusted to match the path of the target resource

This method must be called before the response has been committed to the client (before response body output has been flushed) If the response has already been committed, this method throws an IllegalStateException Uncommitted output

in the response buffer is automatically cleared before the forward

The request and response parameters must be the same objects as were passed to the calling servlet's service method or be subclasses of the ServletRequestWrapper

or ServletResponseWrapper classes that wrap them

public void include(ServletRequest req, ServletResponse res)

Includes the response generated by a resource (servlet, JSP page, HTML file) in the response

The ServletResponse object's path elements and parameters remain unchanged from the caller's The included servlet can't change the response status code or set headers; any attempt to make a change is ignored

The request and response parameters must be the same objects that were passed to the calling servlet's service method or be subclasses of the ServletRequestWrapper

or ServletResponseWrapper classes that wrap them

D.3 Tag Handler Types

The JSP specification defines a number of classes and interfaces in the javax.servlet.jsp.tagext package These classes are used to develop tag handler classes for JSP custom actions This section contains descriptions of each class and interfaces Chapter 20 and Chapter 21 show examples of how you can use these classes and interfaces to develop custom actions

BodyContent

The container creates an instance of the BodyContent class to encapsulate the element body

of a custom action element if the corresponding tag handler implements the BodyTaginterface The container makes the BodyContent instance available to the tag handler by calling the setBodyContent( ) method, so the tag handler can process the body content

public void clearBody( )

Removes all buffered content for this instance

public void flush( ) throws java.io.IOException

Overwrites the behavior inherited from JspWriter to always throw an IOException, because it's invalid to flush a BodyContent instance

public JspWriter getEnclosingWriter( )

Returns the enclosing JspWriter, i.e., either the top level JspWriter or the

JspWriter (BodyContent subclass) of the parent tag handler

public abstract java.io.Reader getReader( )

Returns the value of this BodyContent as a Reader with the content produced by

evaluating the element's body

public abstract String getString( )

Returns the value of this BodyContent as a String with the content produced by

evaluating the element's body

public abstract void writeOut(java.io.Writer out) throws java.io.IOException

Writes the content of this BodyContent into a Writer

BodyTag

The BodyTag interface extends the IterationTag interface It must be implemented by

tag handler classes that need access to the body contents of the corresponding custom action

element, for instance in order to perform a transformation of the contents before it's included

in the response A tag handler that implements this interface must return EVAL_BODY_BUFFERED from doStartTag( ) to tell the container to capture the result of

evaluating the body It also can return EVAL_BODY_AGAIN from doAfterBody( ) to tell

the container to evaluate the body again and capture the result

Methods

public void doInitBody( ) throws JspException

Prepares for evaluation of the body This method is invoked once per action invocation by the page implementation after a new BodyContent has been obtained and set on the tag handler via the setBodyContent( ) method and before the evaluation of the element's body

This method isn't invoked if the element body is empty or if doStartTag( ) returns SKIP_BODY

public void setBodyContent(BodyContent b)

Sets the BodyContent created for this tag handler This method isn't invoked if the element body is empty or if doStartTag( ) returns SKIP_BODY

BodyTagSupport

BodyTagSupport is a support class that provides default implementations of all BodyTaginterface methods It's intended to be used as a superclass for tag handlers that need access to the body contents of the corresponding custom action element

public int doEndTag( )

Returns EVAL_PAGE

public void doInitBody( )

This method does nothing in the BodyTagSupport class

public int doStartTag( )

Returns EVAL_BODY_BUFFERED

public BodyContent getBodyContent( )

Returns the BodyContent object assigned to this instance

public JspWriter getPreviousOut( )

Returns the enclosing writer of the BodyContent object assigned to this instance

public void release( )

Removes the references to all objects held by this instance

public void setBodyContent(BodyContent b)

Saves a reference to the BodyContent in the bodyContent instance variable

IterationTag

The IterationTag interface extends the Tag interface It must be implemented by tag

handler classes that need their corresponding action element body evaluated more than once

but that don't need to access the result of the body evaluation

Methods

public int doAfterBody( ) throws JspException

Performs actions after the body has been evaluated This method is invoked after every body evaluation If this method returns EVAL_BODY_AGAIN, the body is evaluated again, typically after changing the value of variables used in the body If it returns SKIP_BODY, the processing continues with a call to doEndTag( )

This method isn't invoked if the element body is empty or if doStartTag( ) returns SKIP_BODY

Tag

The Tag interface is the main tag handler interface It should be implemented by tag handler classes that do not need the body of the corresponding action element evaluated more than once and that do not need access to the result of the body evaluation

public static final int EVAL_BODY_INCLUDE

public static final int EVAL_PAGE

public static final int SKIP_BODY

public static final int SKIP_PAGE

Methods

public int doEndTag( ) throws JspException

Performs actions when the end tag is encountered If this method returns SKIP_PAGE, execution of the rest of the page is aborted, and the _jspService( ) method of JSP page implementation class returns If EVAL_PAGE is returned, the code following the custom action in the _jspService( ) method is executed

public int doStartTag( ) throws JspException

Performs actions when the start tag is encountered This method is called by the JSP container after all property setter methods have been called The return value from this method controls how the action's body is handled, if any If it returns EVAL_BODY_INCLUDE, the JSP container evaluates the body and processes possible

JSP elements The result of the evaluation is added to the response If SKIP_BODY is returned, the body is ignored

A tag handler class that implements the BodyTag interface (extending the IterationTag interface, which extends the Tag interface) can return EVAL_BODY_BUFFERED instead of EVAL_BODY_INCLUDE The JSP container then creates a BodyContent instance and makes it available to the tag handler for special processing

public Tag getParent( )

Returns the tag handler's parent (the Tag instance for the enclosing action element, if any) or null if the tag handler doesn't have a parent

public void release( )

Removes the references to all objects held by this instance

public void setPageContext(PageContext pc)

Saves a reference to the current PageContext

public void setParent(Tag t)

Saves a reference to the tag handler's parent (the Tag instance for the enclosing action element)

TagAttributeInfo

TagAttributeInfo instances are created by the JSP container to provide information found in the Tag Library Descriptor (TLD) about each attribute supported by a custom action It's primarily intended to be used by the JSP container itself during the translation phase

Constructor

public TagAttributeInfo(String name, boolean required, boolean rtexprvalue,

String type, boolean reqTime)

Creates a new instance with the specified information from the TLD Instances of this class should be created only by the JSP container

Methods

public boolean canBeRequestTime( )

Returns true if a request time attribute value can be used for this attribute

public static TagAttributeInfo getIdAttribute(TagAttributeInfo[] a)

Convenience method that returns the TagAttributeInfo instance in the specified array that represents an attribute named id or null if not found

public String getName( )

Returns the attribute name

public String getTypeName( )

Returns the attribute's Java type (a fully qualified class or interface name)

public boolean isRequired( )

Returns true if this attribute is required, false otherwise

public String toString( )

Returns a String representation of the attribute info

TagData

TagData instances are created by the JSP container during the translation phase to provide information about the attribute values specified for a custom action to the TagExtraInfosubclass for the corresponding tag handler, if any

Synopsis

Class name: javax.servlet.jsp.tagext.TagData

Extends: None

Implements: Clonable

public TagData(Object[][] atts)

Creates a new instance with the attribute name/value pairs specified by the Object[][] Element 0 of each Object[] contains the name and element 1 the value or REQUEST_TIME_VALUE if the attribute value is defined as a request time value (a JSP expression)

public TagData(java.util.Hashtable attrs)

Creates a new instance with the attribute name/value pairs specified by the Hashtable

Methods

public Object getAttribute(String attName)

Returns the specified attribute value as a String or as the REQUEST_TIME_VALUEObject if the attribute value is defined as a request time value (a JSP expression)

public String getAttributeString(String attName)

Returns the specified attribute value as a String A ClassCastException is thrown if the attribute value is defined as a request time value (a JSP expression)

public String getId( )

Returns the attribute named id as a String, or null if not found

public void setAttribute(String attName, Object value)

Sets the specified attribute to the specified value

TagExtraInfo

For custom actions that use scripting variables and require additional translation time for validation of the tag attributes, a subclass of the TagExtraInfo class can be developed for the custom action and declared in the Tag Library Descriptor The JSP container creates an

Note that for most cases, the variable information can instead be declared in the TLD, and a TagLibraryValidator class can perform validation in a more flexible manner than a TagExtraInfo class can

public TagInfo getTagInfo( )

Returns the TagInfo instance for the custom action associated with this TagExtraInfo instance The TagInfo instance is set by the setTagInfo( )method (called by the container)

public VariableInfo[] getVariableInfo(TagData data)

Returns a VariableInfo[] with information about scripting variables created by the tag handler class associated with this TagExtraInfo instance The default implementation returns an empty array A subclass must override this method if the corresponding tag handler creates scripting variables

public boolean isValid(TagData data)

Returns true if the set of attribute values specified for the custom action associated with this TagExtraInfo instance is valid, false otherwise The default implementation returns true A subclass can override this method if the validation performed by the JSP container based on the Tag Library Descriptor information is not enough

public void setTagInfo(TagInfo tagInfo)

Sets the TagInfo for this instance This method is called by the JSP container before any of the other methods are called

TagInfo

TagInfo instances are created by the JSP container to provide information found in the Tag Library Descriptor (TLD) about a custom action as well as information about the attribute values used in a JSP page for an instance of the custom action It's primarily intended to be used by the JSP container itself during the translation phase

public static final String BODY_CONTENT_EMPTY

public static final String BODY_CONTENT_JSP

public static final String BODY_CONTENT_TAG_DEPENDENT

Constructor

public TagInfo(String tagName, String tagClassName,

String bodycontent, String infoString,

TagAttributeInfo[] attributeInfo)

Creates a new instance with the specified values, based on the information available in

a JSP 1.1 TLD

public TagInfo(String tagName, String tagClassName,

String bodycontent, String infoString,

Creates a new instance with the specified values, based on the information available in

a JSP 1.2 TLD

Methods

public TagAttributeInfo[] getAttributes( )

Returns information from the TLD about all attribute values or null if no attributes are declared

public String getBodyContent( )

BODY_CONTENT_TAG_DEPENDENT based on the value in the TLD

public String getDisplayName( )

Returns the display name value from the TLD or null if no value is specified

public String getInfoString( )

Returns the tag information value from the TLD or null if no value is specified

public String getLargeIcon( )

Returns the large icon path from the TLD or null if no value is specified

public String getSmallIcon( )

Returns the small icon path from the TLD or null if no value is specified

public String getTagClassName( )

Returns the tag handler class name declared in the TLD

public TagExtraInfo getTagExtraInfo( )

Returns an instance of the TagExtraInfo subclass for the tag or null if no class is declared in the TLD

public TagLibraryInfo getTagLibrary( )

Returns a TagLibraryInfo instance for the library the tag is part of

public String getTagName( )

Returns the name for the tag declared in the TLD

public TagVariableInfo[] getTagVariableInfos( )

Returns an array with a TagVariableInfo instance for each variable declaration in the TLD

public VariableInfo[] getVariableInfo(TagData data)

Returns information about scripting variables created by the tag handler or null if no variables are created This information is obtained from the TagExtraInfo for the tag, if any

public boolean isValid(TagData data)

Returns true if the set of attributes specified for the custom action associated with this TagExtraInfo instance is valid, false otherwise This information is obtained from the TagExtraInfo for the tag, if any

public void setTagExtraInfo(TagExtraInfo tei)

Sets the TagExraInfo value held by the instance

public void setTagLibrary(TagLibrary tl)

Sets the TagLibrary value held by the instance

public String toString( )

Returns a String representation of all information held by the instance

TagLibraryInfo

TagLibraryInfo instances are created by the JSP container to provide information found

in the Tag Library Descriptor (TLD) about a tag library as well as information from the taglib directive used in a JSP page It's primarily intended to be used by the JSP container itself during the translation phase

protected String info

protected String jspversion

protected String prefix

protected String shortname

protected TagInfo[] tags

protected String tlibversion

protected String uri

protected String urn

Constructor

protected TagLibraryInfo(String prefix, String uri)

Creates a new instance with the specified prefix and URI (from the taglib directive

in the JSP page)

Methods

public java.lang.String getInfoString( )

Returns the information string from the TLD for the library

public String getPrefixString( )

Returns the prefix assigned by the taglib directive for the library

public String getReliableURN( )

Returns URI value from the TLD for the library

public String getRequiredVersion( )

Returns the required JSP version from the TLD for the library

public String getShortName( )

Returns the short name (prefix) from the TLD for the library

public TagInfo getTag(String shortname)

Returns a TagInfo instance for the specified tag in the library

public TagInfo[] getTags( )

Returns a TagInfo[] for all tags in the library

public String getURI( )

Returns the URI assigned by the taglib directive for the library

TagSupport

TagSupport is a support class that provides default implementations of all IterationTaginterface methods It's intended to be used as a superclass for tag handlers that don't need to evaluate the corresponding action element body or need access to the evaluation result

public static final Tag findAncestorWithClass(Tag from, Class class)

Returns the instance of the specified class, found by testing for a match of each parent

in a tag handler nesting structure (corresponding to nested action elements) starting with the specified Tag instance or null if not found

public String getId( )

Returns the id attribute value or null if not set

public Tag getParent( )

Returns the parent of this Tag instance (representing the action element that contains the action element corresponding to this Tag instance) or null if the instance has no parent (at the top level in the JSP page)

public Object getValue(String k)

Returns the value for the specified attribute that has been set with the setValue( )method or null if not found

public java.util.Enumeration getValues( )

Returns an Enumeration of all attribute names for values set with the setValue( ) method

public void release( )

Removes the references to all objects held by this instance

public void removeValue(String k)

Removes a value set with the setValue( ) method

public void setId(String id)

Sets the id attribute value

public void setPageContext(PageContext pageContext)

Saves a reference to the current PageContext

public void setParent(Tag t)

Saves a reference to the parent for this instance

public void setValue(String k, Object o)

Saves the specified attribute with the specified value Subclasses can use this method

to save attribute values as an alternative to instance variables

TagVariableInfo

The TagVariableInfo instance represents a variable declaration in the TLD The container creates instances of this class during the translation phase, and it's used to generate variable declarations in the JSP page implementation class

by: implementation of the class (developed in the Apache Jakarta project)

Constructor

public TagVariableInfo(String nameGiven, String nameFromAttribute,

String className, boolean declare, int scope)

Creates a new instance with the specified values

Methods

public String getClassName( )

Returns the declared class name

public boolen getDeclare( )

Returns true if the variable is defined as one to be declared

public String getNameFromAttribute( )

Returns the name of the attribute declared to hold the name of the variable at translation time

public String getNameGiven( )

Returns the declared variable name

public int getScope( )

Returns the declared scope, as one of VariableInfo.AT_BEGIN, VariableInfo.AT_END, or VariableInfo.NESTED

TryCatchFinally

The TryCatchFinally interface provides methods for handling exceptions thrown while evaluating the body of an action element and can be implemented a tag handler in addition to one of the main tag handler interfaces: Tag, IterationTag, and BodyTag

Methods

public void doCatch(Throwable exception) throws Throwable

Handles the specified exception and may optionally rethrow the same exception or a new exception This method is invoked by the container if an exception is thrown when evaluating the body or by doStartTag( ), doEndTag( ), doInitBody( ), or doAfterBody( )

public void doFinally( )

Typically clears per-invocation state, such as closing expensive resources used only while processing one occurrence of the corresponding action element This method is invoked after doEndTag( ) or after doCatch( ) if an exception is thrown when evaluating the body or by doStartTag( ), doEndTag( ), doInitBody( ), or doAfterBody( )

public static final int AT_BEGIN

public static final int AT_END

public static final int NESTED

Constructor

public VariableInfo(String varName, String className, boolean declare, int scope)

Creates a new instance with the specified values

Methods

public String getClassName( )

Returns the scripting variable Java type

public boolean getDeclare( )

Returns true if the JSP container should create a declaration statement for scripting variable, otherwise false This is used if the variable has already been declared by another tag handler and is only updated by the tag handler corresponding to the TagExtraInfo subclass creating this VariableInfo instance

public int getScope( )

Returns one of AT_BEGIN (make the scripting variable available from the start tag to the end of the JSP page), AT_END (make the variable available after the end tag to the end of the JSP page), or NESTED (make the variable available only between the start and the stop tag

public String getVarName( )

Returns the variable name

D.4 Tag Library Validation Types

This section describes the classes and interfaces used by the new tag library validation mechanism introduced in JSP 1.2

Methods

public abstract java.io.InputStream getInputStream( )

Returns an input stream for the XML View of the JSP page, in which all includedirectives have been expanded

TagLibraryValidator

A subclass of the TagLibraryValidator class can be declared as the validator for a tag library The container invokes it at translation time, providing it with the XML View of the page through a PageData instance

public java.util.Map getInitParameters( )

Returns a Map containing all initialization parameters declared in the TLD for the validator, with the parameter names as keys

public void release( )

Releases any resources kept as instance data

public void setInitParameters(java.util.Map)

Sets the Map containing all initialization parameters declared in the TLD for the validator, with the parameter names as keys

public ValidationMessage[] validate(String prefix, String uri, PageData page)

Validates the specified page data, and returns null or an empty array if the page is valid If errors are found, descriptions of the errors are returned as an array of

ValidationMessage instances The prefix and uri arguments have the values

of the corresponding taglib directive attributes

public ValidationMessage(String id, String message)

Creates a new instance with the specified values

Methods

public String getId( )

Returns the value of the jsp:id attribute for the element associated with this validation message or null if no jsp:id attribute is available

public String getMessage( )

Returns the validation message text, describing the problem

D.5 Other JSP Types

The JSP specification defines a number of other classes and interfaces that don't fit into the previous categories The exception classes, the interface for JSP page implementation classes, and the classes that let a JSP container vendor hide implementation details are described in this section

Constructor

public JspEngineInfo( )

Creates a new JspEngineInfo instance

Methods

public abstract String getSpecificationVersion( )

Returns the version of the JSP specification implemented by the container, for instance

"1.2" for a JSP 1.2-compliant container

Creates a new JspException instance with the specified message

public JspException(String msg, Throwable rootCause)

Creates a new JspException instance with the specified message and root cause

public JspException(Throwable rootCause)

Creates a new JspException instance with the specified root cause

Methods

public Throwable getRootCause( )

Returns the root cause for this exception

JspFactory

The JspFactory is an abstract class that defines a number of factory methods available to a JSP page at runtime for the purposes of creating instances of various interfaces and classes used to support the JSP implementation

A JSP container creates an instance of a concrete subclass during its initialization phase and makes it globally available for use by JSP implementation classes It does so by registering the instance created with this class via the static setDefaultFactory( ) method

public static synchronized JspFactory getDefaultFactory( )

Returns the default JspFactory for the container

public abstract JspEngineInfo getEngineInfo( )

Returns the JspEngineInfo for the container

public abstract getPageContext getPageContext(javax.servlet.Servlet servlet,

javax.servlet.ServletRequest request,

javax.servlet.ServletResponse response,

String errorPageURL, boolean needsSession, int buffer, boolean autoflush)

Returns a properly initialized instance of an implementation-dependent PageContext subclass This method is typically called early in the processing of the _jspService( ) method of a JSP implementation class to get a PageContextobject for the request being processed Calling this method results in the PageContext.initialize( ) method being invoked

public abstract void releasePageContext(PageContext pc)

Releases a previously allocated PageContext object Calling this method results in PageContext.release( ) being invoked This method should be invoked prior

to returning from the _jspService( ) method of a JSP implementation class

public static synchronized void setDefaultFactory(JspFactory deflt)

Sets the default factory for this implementation It is illegal for any other than the JSP container to call this method

JspPage

The JspPage interface must be implemented by the generated JSP page-implementation classes The interface defines a protocol with 3 methods; only two of them, jspInit( ) and jspDestroy( ), are part of this interface as the signature of the third method: _jspService( ) _jspservice( ) depends on the specific protocol used and cannot be expressed in a generic way in Java See also HttpJspPage

The JspPage interface represents the basic, protocol-independent contract between the container and a JSP page-implementation object A protocol-dependent subinterface, such as HttpJspPage, must be implemented by the class generated from a JSP page

The jspInit( ) and jspDestroy( ) methods can be defined by a JSP page author

public void jspDestroy( )

This method is invoked when the JSP page-implementation instance is about to be destroyed It can perform clean-up, such as saving the state of instance variables to permanent storage

public void jspInit( )

This method is invoked when the JSP page implementation instance is initialized It can be used to perform tasks such as restoring the state of instance variables from permanent storage

Appendix E Book Example Custom Actions and API

The actions are described using the same conventions as for the JSP standard actions in Appendix A and the JSTL actions in Appendix B Most of the custom actions accept JSTL EL expressions for dynamic values, indicated by "EL expression" in the "Dynamic value accepted" column in the Attributes tables

E.1 Generic Custom Actions

<ora:addCookie>

The <ora:addCookie> action sets response headers for creating or deleting a cookie It must be used before the response is committed, for instance before a <jsp:include> action with the flush attribute set to true

Description

name String EL expression The cookie name

value String EL expression The cookie value

maxAge String EL expression

The number of seconds before the cookie expires Default is -1, meaning that the cookie expires when the browser is closed Use 0 to delete the cookie from the browser

Example

<%

Add a cookie named "userName", using the value from a

request parameter with the same name, that expires in

fileName String No

Either an absolute file path or log to write to the application log file If omitted, writes to System.out

Syntax 1: Without parameters

<ora:forward page="pageOrContextRelativePath" />

Syntax 2: With nested <ora:param> actions

<ora:forward page="pageOrContextRelativePath" />

One or more <ora:param> actions

</ora:forward>

Attributes

Attributename Java

type

Dynamic valueaccepted Description

page String EL expression The forward target resource, as a page- or

Syntax 1: Conditionally evaluate the body

<ora:ifContains value="testValue" substring="substring">

Evaluated if the testValue contains the substring

</ora:ifContains>

Syntax 2: Saving the test result

<ora:ifContains value="testValue" substring="substring"

var="var" [scope="page|request|session|application"] />

Attributes

Attributename Java

type

Dynamic valueaccepted Description

value String EL expression The main string value to test if it contains the substring

substring String EL expression The substring