| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN""http://www.w3.org/TR/REC-html40/loose.dtd"> |
| <!--NewPage--> |
| <HTML> |
| <HEAD> |
| <!-- Generated by javadoc on Fri Aug 22 03:43:54 EDT 2003 --> |
| <TITLE> |
| org.apache.struts.taglib.bean (Apache Struts API Documentation) |
| </TITLE> |
| <META NAME="keywords" CONTENT="org.apache.struts.taglib.bean package"> |
| <LINK REL ="stylesheet" TYPE="text/css" HREF="../../../../../stylesheet.css" TITLE="Style"> |
| </HEAD> |
| <SCRIPT> |
| function asd() |
| { |
| parent.document.title="org.apache.struts.taglib.bean (Apache Struts API Documentation)"; |
| } |
| </SCRIPT> |
| <BODY BGCOLOR="white" onload="asd();"> |
| |
| <!-- ========== START OF NAVBAR ========== --> |
| <A NAME="navbar_top"><!-- --></A> |
| <TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0"> |
| <TR> |
| <TD COLSPAN=3 BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> |
| <A NAME="navbar_top_firstrow"><!-- --></A> |
| <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3"> |
| <TR ALIGN="center" VALIGN="top"> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD> |
| <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Class</FONT> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-use.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD> |
| </TR> |
| </TABLE> |
| </TD> |
| <TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM> |
| </EM> |
| </TD> |
| </TR> |
| |
| <TR> |
| <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> |
| <A HREF="../../../../../org/apache/struts/plugins/package-summary.html"><B>PREV PACKAGE</B></A> |
| <A HREF="../../../../../org/apache/struts/taglib/html/package-summary.html"><B>NEXT PACKAGE</B></A></FONT></TD> |
| <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> |
| <A HREF="../../../../../index.html" TARGET="_top"><B>FRAMES</B></A> |
| <A HREF="package-summary.html" TARGET="_top"><B>NO FRAMES</B></A> |
| |
| <SCRIPT> |
| <!-- |
| if(window==top) { |
| document.writeln('<A HREF="../../../../../allclasses-noframe.html" TARGET=""><B>All Classes</B></A>'); |
| } |
| //--> |
| </SCRIPT> |
| <NOSCRIPT> |
| <A HREF="../../../../../allclasses-noframe.html" TARGET=""><B>All Classes</B></A> |
| </NOSCRIPT> |
| </FONT></TD> |
| </TR> |
| </TABLE> |
| <!-- =========== END OF NAVBAR =========== --> |
| |
| <HR> |
| <H2> |
| Package org.apache.struts.taglib.bean |
| </H2> |
| The "struts-bean" tag library contains JSP custom tags useful in defining |
| new beans (in any desired scope) from a variety of possible sources, as well |
| as a tag to render a particular bean (or bean property) to the output response. |
| <P> |
| <B>See:</B> |
| <BR> |
| <A HREF="#package_description"><B>Description</B></A> |
| <P> |
| |
| <TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%"> |
| <TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor"> |
| <TD COLSPAN=2><FONT SIZE="+2"> |
| <B>Class Summary</B></FONT></TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="CookieTag.html">CookieTag</A></B></TD> |
| <TD>Define a scripting variable based on the value(s) of the specified |
| cookie received with this request.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="CookieTei.html">CookieTei</A></B></TD> |
| <TD>Implementation of <code>TagExtraInfo</code> for the <b>cookie</b> |
| tag, identifying the scripting object(s) to be made visible.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="DefineTag.html">DefineTag</A></B></TD> |
| <TD>Define a scripting variable based on the value(s) of the specified |
| bean property.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="DefineTei.html">DefineTei</A></B></TD> |
| <TD>Implementation of <code>TagExtraInfo</code> for the <b>define</b> |
| tag, identifying the scripting object(s) to be made visible.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="HeaderTag.html">HeaderTag</A></B></TD> |
| <TD>Define a scripting variable based on the value(s) of the specified |
| header received with this request.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="HeaderTei.html">HeaderTei</A></B></TD> |
| <TD>Implementation of <code>TagExtraInfo</code> for the <b>header</b> |
| tag, identifying the scripting object(s) to be made visible.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="IncludeTag.html">IncludeTag</A></B></TD> |
| <TD>Define the contents of a specified intra-application request as a |
| page scope attribute of type <code>java.lang.String</code>.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="IncludeTei.html">IncludeTei</A></B></TD> |
| <TD>Implementation of <code>TagExtraInfo</code> for the <b>include</b> |
| tag, identifying the scripting object(s) to be made visible.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="MessageTag.html">MessageTag</A></B></TD> |
| <TD>Custom tag that retrieves an internationalized messages string (with |
| optional parametric replacement) from the <code>ActionResources</code> |
| object stored as a context attribute by our associated |
| <code>ActionServlet</code> implementation.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="PageTag.html">PageTag</A></B></TD> |
| <TD>Define a scripting variable that exposes the requested page context |
| item as a scripting variable and a page scope bean.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="PageTei.html">PageTei</A></B></TD> |
| <TD>Implementation of <code>TagExtraInfo</code> for the <b>page</b> |
| tag, identifying the scripting object(s) to be made visible.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="ParameterTag.html">ParameterTag</A></B></TD> |
| <TD>Define a scripting variable based on the value(s) of the specified |
| parameter received with this request.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="ParameterTei.html">ParameterTei</A></B></TD> |
| <TD>Implementation of <code>TagExtraInfo</code> for the <b>parameter</b> |
| tag, identifying the scripting object(s) to be made visible.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="ResourceTag.html">ResourceTag</A></B></TD> |
| <TD>Define a scripting variable based on the contents of the specified |
| web application resource.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="ResourceTei.html">ResourceTei</A></B></TD> |
| <TD>Implementation of <code>TagExtraInfo</code> for the <b>resource</b> |
| tag, identifying the scripting object(s) to be made visible.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="SizeTag.html">SizeTag</A></B></TD> |
| <TD>Define a scripting variable that will contain the number of elements |
| found in a specified array, Collection, or Map.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="SizeTei.html">SizeTei</A></B></TD> |
| <TD>Implementation of <code>TagExtraInfo</code> for the <b>size</b> |
| tag, identifying the scripting object(s) to be made visible.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="StrutsTag.html">StrutsTag</A></B></TD> |
| <TD>Define a scripting variable that exposes the requested Struts |
| internal configuraton object.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="StrutsTei.html">StrutsTei</A></B></TD> |
| <TD>Implementation of <code>TagExtraInfo</code> for the <b>struts</b> |
| tag, identifying the scripting object(s) to be made visible.</TD> |
| </TR> |
| <TR BGCOLOR="white" CLASS="TableRowColor"> |
| <TD WIDTH="15%"><B><A HREF="WriteTag.html">WriteTag</A></B></TD> |
| <TD>Tag that retrieves the specified property of the specified bean, converts |
| it to a String representation (if necessary), and writes it to the current |
| output stream, optionally filtering characters that are sensitive in HTML.</TD> |
| </TR> |
| </TABLE> |
| |
| |
| <P> |
| <A NAME="package_description"><!-- --></A><H2> |
| Package org.apache.struts.taglib.bean Description |
| </H2> |
| |
| <P> |
| The "struts-bean" tag library contains JSP custom tags useful in defining |
| new beans (in any desired scope) from a variety of possible sources, as well |
| as a tag to render a particular bean (or bean property) to the output response. |
| <br> |
| <br> |
| <a name="doc.Description"></a> |
| |
| <div align="Center"> <a href="#doc.Intro">[Introduction]</a> |
| <a href="#doc.Properties">[Bean Properties]</a> |
| <a href="#doc.Creation">[Bean Creation]</a> |
| <a href="#doc.Output">[Bean Output]</a> |
| </div> |
| |
| <hr> <a name="doc.Intro"></a> |
| |
| <h3>Introduction</h3> |
| |
| <p>Much of the power of JavaServer Pages (JSP) technology comes from the |
| simple and powerful mechanisms by which the servlet that is generated automatically |
| from your JSP source page can interact with JavaBeans that represent the computational |
| state of your application. In standard JSP pages, the <code><jsp:useBean></code> |
| tag is used create a bean (if necessary), as well as a "scripting variable" |
| that can be used within scriptlets to refer to these beans.</p> |
| |
| <p>The "struts-bean" tag library provides substantial enhancements to the |
| basic capability provided by <code><jsp:useBean></code>, as discussed |
| in the following sections:</p> |
| |
| <ul> |
| <li><a href="#doc.Properties">Bean Properties</a> |
| - Extended syntax to refer to JavaBean properties with simple names |
| (same as the standard JSP tags <code><jsp:getProperty></code> and |
| <code><jsp:setProperty></code>), nested names (a property named |
| <code>address.city</code> returns the value retrieved by the Java |
| expression <code>getAddress().getCity()</code>), and indexed names (a |
| property named <code>address[3]</code> retrieves the fourth address from |
| the indexed "address" property of a bean).</li> |
| <li><a href="#doc.Creation">Bean Creation</a> |
| - New JSP beans, in any scope, can be created from a variety of objects |
| and APIs associated with the current request, or with the servlet container |
| in which this page is running.</li> |
| <li><a href="#doc.Output">Bean Output</a> |
| - Supports the rendering of textual output from a bean (or bean property), |
| which will be included in the response being created by your JSP page.</li> |
| |
| </ul> |
| |
| <p>See the <a href="../../../../../../userGuide/struts-bean.html">Bean Tags Reference</a> |
| for detailed information about the available tags in this tag library, and |
| the valid attributes for each tag.<br> |
| <img src="doc-files/beanUML.gif" alt="Bean Tag UML"> |
| <br> |
| </p> |
| <a name="doc.Properties"></a> |
| |
| <h3>Bean Properties</h3> |
| |
| <h5>Common Tag Attributes</h5> |
| |
| <p>The tags in the "struts-bean" tag library (and, generally, in all tag libraries |
| included with the Struts framework) share a common set of tag attributes |
| that have the same meaning, no matter what tag they are used on. These common |
| attributes include:</p> |
| |
| <ul> |
| <li><em>id</em> - Names the scripting variable that will be created |
| by this custom tag, as well as the key value used to locate this bean |
| in the scope defined by the <code>scope</code> attribute.</li> |
| <li><em>name</em> - Defines the key value by which an existing bean will |
| be looked up in the scope defined by the <code>scope</code> attribute |
| (if any), or by searching through the various scopes in the standard |
| order (page, request, session, application).</li> |
| <li><em>property</em> - Defines the name of a JavaBeans property, of the |
| JSP bean identified by the <code>name</code> and (optional) <code>scope</code> |
| attributes, whose value is to be used by this custom tag. If not |
| specified, the bean identified by <code>name</code> is itself used |
| as the value of interest. See below for more discussion about how a |
| property can be referenced.</li> |
| <li><em>scope</em> - Identifies the JSP scope ("page", "request", "session", |
| or "application" within which a particular bean will be searched for |
| (under the key specified by the <code>name</code> attribute) or created |
| (under the key specified by the <code>id</code> attribute). If not |
| specified, beans will generally be searched for in the order listed above, |
| or created in page scope.</li> |
| |
| </ul> |
| <a name="doc.Properties.References"></a> |
| |
| <h5>Property References</h5> |
| |
| <p>Struts tags that support the <code>property</code> tag generally also recognize |
| a rich syntax for getting and setting properties. There are three types |
| of references supported: simple, nested, and indexed.</p> |
| |
| <p><em>Simple References</em> - These are equivalent to the syntax you use |
| with the standard <code><jsp:getProperty></code> and <code><jsp:setProperty></code> |
| tags. A reference to a property named "foo" is converted into a method |
| call to <code>getFoo()</code> or <code>setFoo(value)</code> (as appropriate), |
| using the standard JavaBeans Specification naming conventions for bean properties. |
| Struts uses the standard Java introspection APIs to identify the names of |
| the actual property getter and setter methods, so your beans can provided |
| customized method names through the use of a <code>BeanInfo</code> class. |
| See the JavaBeans Specification, available at <a href="http://java.sun.com/products/javabeans/"> |
| http://java.sun.com/products/javabeans/</a> |
| , for more information.</p> |
| |
| <p><em>Nested References</em> - Nested references are used to access a property |
| through a hierarchy of property names separated by periods ("."), similar |
| to the way that nested properties are accessed in JavaScript. For example, |
| the following property reference in a getter (such as the <code><bean:define></code> |
| tag discussed below):</p> |
| |
| <pre> property="foo.bar.baz"<br></pre> |
| |
| <p>is translated into the equivalent the Java expression:</p> |
| |
| <pre> getFoo().getBar().getBaz()<br></pre> |
| |
| <p>If a nested reference is used in a setter (such as when an input form |
| is processed), the property setter is called on the <strong>last</strong> |
| property in the chain. For the above property reference, the equivalent |
| Java expression would be:</p> |
| |
| <pre> getFoo().getBar().setBaz(value)<br></pre> |
| |
| <p><em>Indexed References</em> - Subscripts can be used to access individual |
| elements of properties whose value is actually an array, or whose underlying |
| JavaBean offers indexed getter and setter methods. For example, the following |
| property reference in a getter (such as the <code><bean:define></code> |
| tag discussed below):</p> |
| |
| <pre> property="foo[2]"<br></pre> |
| |
| <p>is translated into the equivalent of the Java expression:</p> |
| |
| <pre> getFoo(2);<br></pre> |
| |
| <p>while the same property reference in a setter would call the equivalent |
| of:</p> |
| |
| <pre> setFoo(2, value)<br></pre> |
| |
| <p>As you can see from the above translations, the subscripts used in indexed |
| references are <strong>zero relative</strong> (that is, the first element |
| in an array is <code>foo[0]</code>), just as is true in the Java language.</p> |
| |
| <p><em>Combined References</em> - Nesting and indexing can be combined in |
| arbitrary ways, so that expressions like <code>foo.bar[0].baz[2]</code> are |
| legal. You must be careful, of course, to ensure that the actual beans being |
| accessed by these references have properties of the appropriate names and |
| types. Otherwise, JSP runtime exceptions will be thrown.</p> |
| |
| <p>See the JavaDocs for <a href="http://jakarta.apache.org/commons/beanutils/api/org/apache/commons/beanutils/PropertyUtils.html">PropertyUtils</a> |
| for more detailed information about the mechanisms that Struts uses to access |
| properties in a general way, through Java reflection APIs.</p> |
| |
| <hr> <a name="doc.Creation"></a> |
| |
| <h3>Bean Creation</h3> |
| |
| <h5>Introduction</h5> |
| |
| <p>New beans can be created, and introduced into one of the four standard |
| JSP scopes (page, request, session, and application) through a variety of |
| techniques. The following subsections describe the use of the following approaches:</p> |
| |
| <ul> |
| <li>Java Code in Action Classes</li> |
| <li>Java Code in Scriptlets</li> |
| <li>The Standard <code><jsp:useBean></code> Tag</li> |
| <li>The Struts <code><bean:define></code> Tag</li> |
| <li>Other Struts Copying Tags</li> |
| |
| </ul> |
| |
| <h5>Java Code in Action Classes</h5> |
| |
| <p>Because the JSP pages are compiled into Servlets, your <code>Action</code> |
| classes that are invoked by the Struts controller servlet have convenient |
| access to three of the four standard JSP scopes (request, session, and application). |
| It is very common practice for the business logic contained in your <code> |
| Action</code> class to create results that are stored in request or session |
| scope, which will be used by a JSP page you forward control to in rendering |
| the next page of the user interface.</p> |
| |
| <p><em>Request Scope</em> - To store a bean in request scope under name "cust", |
| your <code>Action</code> class would execute code similar to this:</p> |
| |
| <pre> Customer customer = ... create or acquire a customer reference ...;<br> request.setAttribute("cust", customer);<br></pre> |
| |
| <p><em>Session Scope</em> - To store a bean in session scope under name "user" |
| (perhaps in a logon action), your <code>Action</code> class would execute |
| code similar to this:</p> |
| |
| <pre> User user = ... look up valid user in the database ...;<br> HttpSession session = request.getSession();<br> session.setAttribute("user", user);<br></pre> |
| |
| <p><em>Application Scope</em> - Generally, application scope beans are initialized |
| in the <code>init()</code> method of a startup servlet. However, it is legal |
| for an <code>Action</code> class to create such beans, if this is appropriate, |
| like this:</p> |
| |
| <pre> Foo foo = ... create a Foo ...;<br> servlet.getServletContext().setAttribute("foo", foo);<br></pre> |
| |
| <h5>Java Code in Scriptlets</h5> |
| |
| <p>While it is not a recommended practice in Struts-based applications (because |
| developers will be tempted to mix business logic and presentation logic in |
| their JSP pages), it is legal for scriptlet code in a JSP page to create |
| new JavaBeans dynamically, and add them to any of the four possible scopes, |
| as demonstrated in the code examples below:</p> |
| |
| <p><em>Page Scope</em> - To store a bean in page scope under name "foo", your |
| scriptlet must execute code like this:</p> |
| |
| <pre><%<br> Foo foo = ... create a foo ...;<br> pageContext.setAttribute("foo", foo, PageContext.PAGE_SCOPE);<br>%><br></pre> |
| |
| <p><em>Request Scope</em> - To store a bean in request scope under name "cust", |
| your scriplet must execute code like this:</p> |
| |
| <pre><%<br> Customer customer = ... create or acquire a customer reference ...;<br> pageContext.setAttribute("cust", customer, PageContext.REQUEST_SCOPE);<br>%><br></pre> |
| |
| <p><em>Session Scope</em> - To store a bean in session scope under name "user", |
| (perhaps as a result of a validated login), your scriplet must execute code |
| like this:</p> |
| |
| <pre><%<br> User user = ... look up valid user in the database ...;<br> pageContext.setAttribute("user", user, PageContext.SESSION_SCOPE);<br>%><br></pre> |
| |
| <p><em>Application Scope</em> - Generally, application scope beans are initialized |
| in the <code>init()</code> method of a startup servlet. However, a scriptlet |
| can create such beans, if appropriate, like this:</p> |
| |
| <pre><%<br> Foo foo = ... create a Foo ...;<br> pageContext.setAttribute("foo", foo, PageContext.APPLICATION_SCOPE);<br>%><br></pre> |
| |
| <p><strong>NOTE</strong> - As mentioned above, using scriptlets in your JSP |
| pages is strongly discouraged in a Struts based application, unless you are |
| executing code that is <strong>only</strong> related to presentation of existing |
| data. In general, your application's processing logic should be encapsulated |
| in <code>Action</code> classes (or in beans or EJBs called by those classes), |
| rather than being intermixed in your JSP pages.</p> |
| |
| <h5>The Standard <code><jsp:useBean></code> Tag</h5> |
| |
| <p>JavaServer Pages (JSP) offers a standard tag, <code><jsp:useBean></code> |
| that can be used to create a new bean, or introduce a reference to an existing |
| bean, into a JSP page. Beans (or bean references) introduced through this |
| mechanism are completely interoperable with beans created by any of the Struts |
| creation techniques described in this section.</p> |
| |
| <p>You <strong>must</strong> use <code><jsp:useBean></code> to introduce |
| a reference to an existing bean, if you wish to reference that bean with |
| other standard JSP tags (such as <code><jsp:getProperty></code> or <code> |
| <jsp:setProperty></code>). If you only wish to reference such beans |
| with other Struts tags, use of <code><jsp:useBean></code> is not required.</p> |
| |
| <p>For more information about the <code><jsp:useBean></code> tag, see |
| the JavaServer Pages Specification, available at <a href="http://java.sun.com/products/jsp/download.html"> |
| http://java.sun.com/products/jsp/download.html</a> |
| .</p> |
| |
| <h5>The Struts <code><bean:define></code> Tag</h5> |
| |
| <p>Struts provides a powerful, general purpose, tag (<code><bean:define></code> |
| ) that can be used to create a new bean, in any scope, by copying another |
| bean (or the value of the property of another bean). This tag supports the |
| "property" attribute, and therefore all the power of property references, |
| as discused <a href="#doc.Properties.References">above</a> |
| . It can be used in a variety of different ways, described further below. |
| Unless you specify the "toScope" attribute, all defined beans will be created |
| in page scope.</p> |
| |
| <p><em>Introduce A String Constant</em> - You can create a new bean that |
| has a constant String value (or the result of calculating a runtime expression): |
| </p> |
| |
| <pre> <bean:define id="foo" value="This is a new String"/><br> <bean:define id="bar" value='<%= "Hello, " + user.getName() %>'/><br> <bean:define id="last" scope="session"<br> value='<%= request.getRequestURI() %>'/><br></pre> |
| |
| <p><em>Copy An Existing Bean</em> - You can create a new reference to an existing |
| bean object. You can specify the Java class or interface the new bean is |
| expected to conform to with the "type" attribute, or accept the default type |
| of <code>java.lang.Object</code> (this only affects the scripting variable |
| that is exposed to scriptlets, so it is not generally meaningful in Struts-based |
| applications).</p> |
| |
| <pre> <bean:define id="foo" name="bar"/><br> <bean:define id="baz" name="bop" type="com.mycompany.MyBopClass"/><br></pre> |
| |
| <p><em>Copy An Existing Bean Property</em> - You can create a new bean that |
| is initialized to the value returned by a property getter. The value of |
| the "property" attribute can be any simple, nested, or indexed property reference |
| that follows the rules described earlier. In the first example below, we |
| also illustrate accessing the property of a request scope bean, and creating |
| the new bean in session scope (rather than the default page scope).</p> |
| |
| <pre> <bean:define id="foo" name="bar" property="baz" scope="request"<br> toScope="session"/><br> <bean:define id="bop" name="user" property="role[3].name"/><br></pre> |
| |
| <h5>Other Struts Copying Tags</h5> |
| |
| <p>Struts offers a variety of bean creation tags that copy existing beans |
| (or bean properties) from the environment within which this page is running, |
| and the request that is currently being processed. Not all of the attributes |
| for each tag are illustrated in the examples below - see the <a href="../../../../../../userGuide/struts-bean.html"> |
| Bean Tags Reference</a> |
| for more information. Any bean created by these tags exists only in page |
| scope, for the remainder of the current page.</p> |
| |
| <p><em>Copy A Cookie</em> - You can create a new bean containing a <code> |
| javax.servlet.http.Cookie</code> that was included in the current request. |
| If no cookie of the specified name was included, a request time expression |
| will be thrown - therefore, it is common to nest the use of this tag inside |
| a <code><logic:present cookie="xxx"></code> tag to ensure that the |
| cookie was really included. If there is the possibility that more than one |
| cookie of the same name was included, specify the "multiple" attribute (and |
| the resulting bean will be an array of Cookies, instead of a single Cookie).</p> |
| |
| <pre> <bean:cookie id="foo" name="cookiename"/><br> <bean:cookie id="all" name="JSESSIONID" multiple="true"/><br></pre> |
| |
| <p><em>Copy A Request Header</em> - You can create a new bean containing |
| the value of an HTTP header included in this request. If no header of the |
| specified name was included, a request time exception will be thrown - therefore, |
| it is common to nest the use of this tag inside a <code><logic:present |
| header="xxx"></code> tag to ensure that the header was really included. |
| If there is the possibility that more than one header of the same name was |
| included, specify the "multiple" attribute (and the resulting value bean |
| will be an array of String values, instead of a single String).</p> |
| |
| <pre> <bean:header id="agent" name="User-Agent"/><br> <bean:header id="languages" name="Accept-Language" multiple="true"/><br></pre> |
| |
| <p><em>Copy A Dynamically Created Response</em> - You can generate an internal |
| request to the application you are running, and turn the response data that |
| is returned from that request into a bean (of type String). One possible |
| use for this technique is to acquire dynamically created XML formatted data |
| that will be stored in a bean and later manipulated (such as by applying |
| an XSLT stylesheet). If the current request is part of a session, the generated |
| request for the include will also include the session identifier (and thus |
| be considered part of the same session).</p> |
| |
| <pre> <bean:include id="text" name="/generateXml?param1=a&param2=b"/><br></pre> |
| |
| <p><em>Copy A JSP Implicitly Defined Object</em> - You can create a bean |
| that is one of the JSP implicitly defined objects (see the JSP spec for more |
| details). This is useful if you wish to perform property getter actions against |
| the implicit object with a custom tag instead of a scriptlet.</p> |
| |
| <pre> <bean:page id="app" property="application"/><br> <bean:page id="sess" property="session"/><br></pre> |
| |
| <p><em>Copy A Request Parameter</em> - You can create a new bean containing |
| the value of a parameter included in this request. If no parameter of the |
| specified name was included, a request time exception will be thrown - therefore, |
| it is common to nest the use of this tag inside a <code><logic:present |
| parameter="xxx"></code> tag to ensure that the parameter was really included. |
| If there is the possibility that more than one parameter of the same name |
| was included, specify the "multiple" attribute (and the resulting value bean |
| will be an array of String values, instead of a single String).</p> |
| |
| <pre> <bean:parameter id="name" name="name"/><br> <bean:header id="options" name="option" multiple="true"/><br></pre> |
| |
| <p><em>Copy a Web Application Resource</em> - You can create a new bean containing |
| either the value of a web application resource as a String, or a <code>java.io.InputStream</code> |
| for reading the content of that resource. The resource is accessed with |
| a context-relative path (beginning with "/"), using the <code>ServletContext.getResource()</code> |
| or <code>ServletContext.getResourceAsStream()</code> methods on the underlying |
| application object.</p> |
| |
| <pre> <bean:resource id="deployment" name="/WEB-INF/web.xml"/><br> <bean:resource id="stream" name="/WEB-INF/web.xml"<br> input="true"/><br></pre> |
| |
| <p><em>Copy A Struts Configuration Object</em> - You can create a new bean |
| containing one of the standard Struts framework configuration objects. Doing |
| this gives you access to the properties of the configuration object, if needed. |
| </p> |
| |
| <pre> <bean:struts id="form" formBean="CustomerForm"/><br> <bean:struts id="fwd" forward="success"/><br> <bean:struts id="map" mapping="/saveCustomer"/><br></pre> |
| |
| <hr> <a name="doc.Output"></a> |
| |
| <h3>Bean Output</h3> |
| |
| <p>None of the Struts Bean tags discussed so far render any output to the |
| response page that is being generated from this JSP page. They are executed |
| in order to make relevant Java objects visible as beans for further manipulation. |
| The following tags cause output to be written to the response, and therefore |
| made visible to the ultimate requester.</p> |
| |
| <p><em>Render An Internationalized Message</em> - You can specify a message |
| key (with optional parameter replacement objects) that are passed to a <a href="../../util/MessageResources.html"> |
| MessageResources</a> |
| object that returns the corresponding message text. The message text will |
| be copied to the response currently being created. By default, messages |
| are looked up in the application resources bundle that is initialized for |
| you (as an application scope bean) by the Struts controller servlet, using |
| the Locale must recently stored in the user's session. These defaults can |
| be overridden by setting values for the "bundle" and "locale" attributes, |
| as described in the <a href="../../../../../../userGuide/struts-bean.html#message"> |
| Bean Tags Reference</a> |
| . </p> |
| <pre> <bean:message key="label.Cancel"/><br> <bean:message key="message.hello" arg0='<%= user.getFullName() %>'/><br></pre> |
| |
| <p><em>Render A Bean or Bean Property</em> - The contents of a bean, or bean |
| property, are converted to a String and then copied to the response currently |
| being created. This tag understands the syntax for simple, nested, and indexed |
| property references described <a href="#doc.Properties.Reference"> above</a> |
| . Beans from any scope can be requested - by default, the scopes are searched |
| in expanding visibility order (page, request, session, and application) to |
| locate the requested bean.</p> |
| |
| <pre> <bean:write name="username"/><br> <bean:write name="user" property="fullName"/><br> <bean:write name="customer" property="orders[2].partNumber"<br> scope="session"/><br></pre> |
| <P> |
| |
| <P> |
| <HR> |
| |
| <!-- ========== START OF NAVBAR ========== --> |
| <A NAME="navbar_bottom"><!-- --></A> |
| <TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0"> |
| <TR> |
| <TD COLSPAN=3 BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> |
| <A NAME="navbar_bottom_firstrow"><!-- --></A> |
| <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3"> |
| <TR ALIGN="center" VALIGN="top"> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD> |
| <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Class</FONT> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-use.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD> |
| <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD> |
| </TR> |
| </TABLE> |
| </TD> |
| <TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM> |
| </EM> |
| </TD> |
| </TR> |
| |
| <TR> |
| <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> |
| <A HREF="../../../../../org/apache/struts/plugins/package-summary.html"><B>PREV PACKAGE</B></A> |
| <A HREF="../../../../../org/apache/struts/taglib/html/package-summary.html"><B>NEXT PACKAGE</B></A></FONT></TD> |
| <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> |
| <A HREF="../../../../../index.html" TARGET="_top"><B>FRAMES</B></A> |
| <A HREF="package-summary.html" TARGET="_top"><B>NO FRAMES</B></A> |
| |
| <SCRIPT> |
| <!-- |
| if(window==top) { |
| document.writeln('<A HREF="../../../../../allclasses-noframe.html" TARGET=""><B>All Classes</B></A>'); |
| } |
| //--> |
| </SCRIPT> |
| <NOSCRIPT> |
| <A HREF="../../../../../allclasses-noframe.html" TARGET=""><B>All Classes</B></A> |
| </NOSCRIPT> |
| </FONT></TD> |
| </TR> |
| </TABLE> |
| <!-- =========== END OF NAVBAR =========== --> |
| |
| <HR> |
| Copyright © 2000-2003 - Apache Software Foundation |
| </BODY> |
| </HTML> |
