← Back to branch summary

~ubuntu-branches/ubuntu/trusty/libstruts1.2-java/trusty-proposed

« back to all changes in this revision

Viewing changes to legacy/api-1.1/org/apache/struts/taglib/bean/package-summary.html

  • Committer: Bazaar Package Importer
  • Author(s): Arnaud Vandyck
  • Date: 2004-11-19 15:35:25 UTC
  • Revision ID: james.westby@ubuntu.com-20041119153525-mdu08a76z4zo67xt
Tags: upstream-1.2.4
Import upstream version 1.2.4

Show diffs side-by-side

added added

removed removed

Lines of Context:
legacy/api-1.1/org/apache/struts/taglib/bean/package-summary.html
 
1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN""http://www.w3.org/TR/REC-html40/loose.dtd">
 
2
<!--NewPage-->
 
3
<HTML>
 
4
<HEAD>
 
5
<!-- Generated by javadoc on Fri Aug 22 03:43:54 EDT 2003 -->
 
6
<TITLE>
 
7
org.apache.struts.taglib.bean (Apache Struts API Documentation)
 
8
</TITLE>
 
9
<META NAME="keywords" CONTENT="org.apache.struts.taglib.bean package">
 
10
<LINK REL ="stylesheet" TYPE="text/css" HREF="../../../../../stylesheet.css" TITLE="Style">
 
11
</HEAD>
 
12
<SCRIPT>
 
13
function asd()
 
14
{
 
15
parent.document.title="org.apache.struts.taglib.bean (Apache Struts API Documentation)";
 
16
}
 
17
</SCRIPT>
 
18
<BODY BGCOLOR="white" onload="asd();">
 
19
 
 
20
<!-- ========== START OF NAVBAR ========== -->
 
21
<A NAME="navbar_top"><!-- --></A>
 
22
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0">
 
23
<TR>
 
24
<TD COLSPAN=3 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
 
25
<A NAME="navbar_top_firstrow"><!-- --></A>
 
26
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3">
 
27
  <TR ALIGN="center" VALIGN="top">
 
28
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
 
29
  <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT>&nbsp;</TD>
 
30
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <FONT CLASS="NavBarFont1">Class</FONT>&nbsp;</TD>
 
31
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-use.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A>&nbsp;</TD>
 
32
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
 
33
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
 
34
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
 
35
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
 
36
  </TR>
 
37
</TABLE>
 
38
</TD>
 
39
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
 
40
</EM>
 
41
</TD>
 
42
</TR>
 
43
 
 
44
<TR>
 
45
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
 
46
&nbsp;<A HREF="../../../../../org/apache/struts/plugins/package-summary.html"><B>PREV PACKAGE</B></A>&nbsp;
 
47
&nbsp;<A HREF="../../../../../org/apache/struts/taglib/html/package-summary.html"><B>NEXT PACKAGE</B></A></FONT></TD>
 
48
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
 
49
  <A HREF="../../../../../index.html" TARGET="_top"><B>FRAMES</B></A>  &nbsp;
 
50
&nbsp;<A HREF="package-summary.html" TARGET="_top"><B>NO FRAMES</B></A>  &nbsp;
 
51
&nbsp;
 
52
<SCRIPT>
 
53
  <!--
 
54
  if(window==top) {
 
55
    document.writeln('<A HREF="../../../../../allclasses-noframe.html" TARGET=""><B>All Classes</B></A>');
 
56
  }
 
57
  //-->
 
58
</SCRIPT>
 
59
<NOSCRIPT>
 
60
<A HREF="../../../../../allclasses-noframe.html" TARGET=""><B>All Classes</B></A>
 
61
</NOSCRIPT>
 
62
</FONT></TD>
 
63
</TR>
 
64
</TABLE>
 
65
<!-- =========== END OF NAVBAR =========== -->
 
66
 
 
67
<HR>
 
68
<H2>
 
69
Package org.apache.struts.taglib.bean
 
70
</H2>
 
71
The "struts-bean" tag library contains JSP custom tags useful in defining
 
72
new beans (in any desired scope) from a variety of possible sources, as well
 
73
as a tag to render a particular bean (or bean property) to the output response.
 
74
<P>
 
75
<B>See:</B>
 
76
<BR>
 
77
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#package_description"><B>Description</B></A>
 
78
<P>
 
79
 
 
80
<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
 
81
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
 
82
<TD COLSPAN=2><FONT SIZE="+2">
 
83
<B>Class Summary</B></FONT></TD>
 
84
</TR>
 
85
<TR BGCOLOR="white" CLASS="TableRowColor">
 
86
<TD WIDTH="15%"><B><A HREF="CookieTag.html">CookieTag</A></B></TD>
 
87
<TD>Define a scripting variable based on the value(s) of the specified
 
88
 cookie received with this request.</TD>
 
89
</TR>
 
90
<TR BGCOLOR="white" CLASS="TableRowColor">
 
91
<TD WIDTH="15%"><B><A HREF="CookieTei.html">CookieTei</A></B></TD>
 
92
<TD>Implementation of <code>TagExtraInfo</code> for the <b>cookie</b>
 
93
 tag, identifying the scripting object(s) to be made visible.</TD>
 
94
</TR>
 
95
<TR BGCOLOR="white" CLASS="TableRowColor">
 
96
<TD WIDTH="15%"><B><A HREF="DefineTag.html">DefineTag</A></B></TD>
 
97
<TD>Define a scripting variable based on the value(s) of the specified
 
98
 bean property.</TD>
 
99
</TR>
 
100
<TR BGCOLOR="white" CLASS="TableRowColor">
 
101
<TD WIDTH="15%"><B><A HREF="DefineTei.html">DefineTei</A></B></TD>
 
102
<TD>Implementation of <code>TagExtraInfo</code> for the <b>define</b>
 
103
 tag, identifying the scripting object(s) to be made visible.</TD>
 
104
</TR>
 
105
<TR BGCOLOR="white" CLASS="TableRowColor">
 
106
<TD WIDTH="15%"><B><A HREF="HeaderTag.html">HeaderTag</A></B></TD>
 
107
<TD>Define a scripting variable based on the value(s) of the specified
 
108
 header received with this request.</TD>
 
109
</TR>
 
110
<TR BGCOLOR="white" CLASS="TableRowColor">
 
111
<TD WIDTH="15%"><B><A HREF="HeaderTei.html">HeaderTei</A></B></TD>
 
112
<TD>Implementation of <code>TagExtraInfo</code> for the <b>header</b>
 
113
 tag, identifying the scripting object(s) to be made visible.</TD>
 
114
</TR>
 
115
<TR BGCOLOR="white" CLASS="TableRowColor">
 
116
<TD WIDTH="15%"><B><A HREF="IncludeTag.html">IncludeTag</A></B></TD>
 
117
<TD>Define the contents of a specified intra-application request as a
 
118
 page scope attribute of type <code>java.lang.String</code>.</TD>
 
119
</TR>
 
120
<TR BGCOLOR="white" CLASS="TableRowColor">
 
121
<TD WIDTH="15%"><B><A HREF="IncludeTei.html">IncludeTei</A></B></TD>
 
122
<TD>Implementation of <code>TagExtraInfo</code> for the <b>include</b>
 
123
 tag, identifying the scripting object(s) to be made visible.</TD>
 
124
</TR>
 
125
<TR BGCOLOR="white" CLASS="TableRowColor">
 
126
<TD WIDTH="15%"><B><A HREF="MessageTag.html">MessageTag</A></B></TD>
 
127
<TD>Custom tag that retrieves an internationalized messages string (with
 
128
 optional parametric replacement) from the <code>ActionResources</code>
 
129
 object stored as a context attribute by our associated
 
130
 <code>ActionServlet</code> implementation.</TD>
 
131
</TR>
 
132
<TR BGCOLOR="white" CLASS="TableRowColor">
 
133
<TD WIDTH="15%"><B><A HREF="PageTag.html">PageTag</A></B></TD>
 
134
<TD>Define a scripting variable that exposes the requested page context
 
135
 item as a scripting variable and a page scope bean.</TD>
 
136
</TR>
 
137
<TR BGCOLOR="white" CLASS="TableRowColor">
 
138
<TD WIDTH="15%"><B><A HREF="PageTei.html">PageTei</A></B></TD>
 
139
<TD>Implementation of <code>TagExtraInfo</code> for the <b>page</b>
 
140
 tag, identifying the scripting object(s) to be made visible.</TD>
 
141
</TR>
 
142
<TR BGCOLOR="white" CLASS="TableRowColor">
 
143
<TD WIDTH="15%"><B><A HREF="ParameterTag.html">ParameterTag</A></B></TD>
 
144
<TD>Define a scripting variable based on the value(s) of the specified
 
145
 parameter received with this request.</TD>
 
146
</TR>
 
147
<TR BGCOLOR="white" CLASS="TableRowColor">
 
148
<TD WIDTH="15%"><B><A HREF="ParameterTei.html">ParameterTei</A></B></TD>
 
149
<TD>Implementation of <code>TagExtraInfo</code> for the <b>parameter</b>
 
150
 tag, identifying the scripting object(s) to be made visible.</TD>
 
151
</TR>
 
152
<TR BGCOLOR="white" CLASS="TableRowColor">
 
153
<TD WIDTH="15%"><B><A HREF="ResourceTag.html">ResourceTag</A></B></TD>
 
154
<TD>Define a scripting variable based on the contents of the specified
 
155
 web application resource.</TD>
 
156
</TR>
 
157
<TR BGCOLOR="white" CLASS="TableRowColor">
 
158
<TD WIDTH="15%"><B><A HREF="ResourceTei.html">ResourceTei</A></B></TD>
 
159
<TD>Implementation of <code>TagExtraInfo</code> for the <b>resource</b>
 
160
 tag, identifying the scripting object(s) to be made visible.</TD>
 
161
</TR>
 
162
<TR BGCOLOR="white" CLASS="TableRowColor">
 
163
<TD WIDTH="15%"><B><A HREF="SizeTag.html">SizeTag</A></B></TD>
 
164
<TD>Define a scripting variable that will contain the number of elements
 
165
 found in a specified array, Collection, or Map.</TD>
 
166
</TR>
 
167
<TR BGCOLOR="white" CLASS="TableRowColor">
 
168
<TD WIDTH="15%"><B><A HREF="SizeTei.html">SizeTei</A></B></TD>
 
169
<TD>Implementation of <code>TagExtraInfo</code> for the <b>size</b>
 
170
 tag, identifying the scripting object(s) to be made visible.</TD>
 
171
</TR>
 
172
<TR BGCOLOR="white" CLASS="TableRowColor">
 
173
<TD WIDTH="15%"><B><A HREF="StrutsTag.html">StrutsTag</A></B></TD>
 
174
<TD>Define a scripting variable that exposes the requested Struts
 
175
 internal configuraton object.</TD>
 
176
</TR>
 
177
<TR BGCOLOR="white" CLASS="TableRowColor">
 
178
<TD WIDTH="15%"><B><A HREF="StrutsTei.html">StrutsTei</A></B></TD>
 
179
<TD>Implementation of <code>TagExtraInfo</code> for the <b>struts</b>
 
180
 tag, identifying the scripting object(s) to be made visible.</TD>
 
181
</TR>
 
182
<TR BGCOLOR="white" CLASS="TableRowColor">
 
183
<TD WIDTH="15%"><B><A HREF="WriteTag.html">WriteTag</A></B></TD>
 
184
<TD>Tag that retrieves the specified property of the specified bean, converts
 
185
 it to a String representation (if necessary), and writes it to the current
 
186
 output stream, optionally filtering characters that are sensitive in HTML.</TD>
 
187
</TR>
 
188
</TABLE>
 
189
&nbsp;
 
190
 
 
191
<P>
 
192
<A NAME="package_description"><!-- --></A><H2>
 
193
Package org.apache.struts.taglib.bean Description
 
194
</H2>
 
195
 
 
196
<P>
 
197
The "struts-bean" tag library contains JSP custom tags useful in defining
 
198
new beans (in any desired scope) from a variety of possible sources, as well
 
199
as a tag to render a particular bean (or bean property) to the output response. 
 
200
<br>
 
201
<br>
 
202
 <a name="doc.Description"></a>
 
203
 
 
204
<div align="Center"> <a href="#doc.Intro">[Introduction]</a>
 
205
 <a href="#doc.Properties">[Bean Properties]</a>
 
206
 <a href="#doc.Creation">[Bean Creation]</a>
 
207
 <a href="#doc.Output">[Bean Output]</a>
 
208
 </div>
 
209
  
 
210
<hr>  <a name="doc.Intro"></a>
 
211
 
 
212
<h3>Introduction</h3>
 
213
  
 
214
<p>Much of the power of JavaServer Pages (JSP) technology comes from the
 
215
simple and powerful mechanisms by which the servlet that is generated automatically 
 
216
from your JSP source page can interact with JavaBeans that represent the computational
 
217
state of your application.  In standard JSP pages, the <code>&lt;jsp:useBean&gt;</code>
 
218
 tag is used create a bean (if necessary), as well as a "scripting variable"
 
219
that can be used within scriptlets to refer to these beans.</p>
 
220
  
 
221
<p>The "struts-bean" tag library provides substantial enhancements to the 
 
222
basic capability provided by <code>&lt;jsp:useBean&gt;</code>, as discussed 
 
223
in the following sections:</p>
 
224
 
 
225
<ul>
 
226
 <li><a href="#doc.Properties">Bean Properties</a>
 
227
 - Extended syntax to refer to     JavaBean properties with simple names
 
228
(same as the standard JSP tags     <code>&lt;jsp:getProperty&gt;</code> and 
 
229
    <code>&lt;jsp:setProperty&gt;</code>), nested names (a property named 
 
230
    <code>address.city</code> returns the value retrieved by the Java   
 
231
 expression <code>getAddress().getCity()</code>), and indexed names     (a
 
232
property named <code>address[3]</code> retrieves the fourth address     from
 
233
the indexed "address" property of a bean).</li>
 
234
 <li><a href="#doc.Creation">Bean Creation</a>
 
235
 - New JSP beans, in any scope,     can be created from a variety of objects
 
236
and APIs associated with the     current request, or with the servlet container
 
237
in which this page is     running.</li>
 
238
 <li><a href="#doc.Output">Bean Output</a>
 
239
 - Supports the rendering of textual     output from a bean (or bean property),
 
240
which will be included in the     response being created by your JSP page.</li>
 
241
 
 
242
</ul>
 
243
  
 
244
<p>See the <a href="../../../../../../userGuide/struts-bean.html">Bean Tags Reference</a>
 
245
 for detailed information about the available tags in this tag library, and
 
246
the valid attributes for each tag.<br>
 
247
<img src="doc-files/beanUML.gif" alt="Bean Tag UML">
 
248
<br>
 
249
</p>
 
250
   <a name="doc.Properties"></a>
 
251
 
 
252
<h3>Bean Properties</h3>
 
253
  
 
254
<h5>Common Tag Attributes</h5>
 
255
  
 
256
<p>The tags in the "struts-bean" tag library (and, generally, in all tag libraries
 
257
included with the Struts framework) share a common set of tag attributes
 
258
that have the same meaning, no matter what tag they are used on. These common
 
259
attributes include:</p>
 
260
 
 
261
<ul>
 
262
 <li><em>id</em> - Names the scripting variable that will be     created
 
263
by this custom tag, as well as the key value used to locate this     bean
 
264
in the scope defined by the <code>scope</code> attribute.</li>
 
265
 <li><em>name</em> - Defines the key value by which an existing bean will
 
266
be     looked up in the scope defined by the <code>scope</code> attribute 
 
267
    (if any), or by searching through the various scopes in the standard 
 
268
   order (page, request, session, application).</li>
 
269
 <li><em>property</em> - Defines the name of a JavaBeans property, of the
 
270
JSP     bean identified by the <code>name</code> and (optional) <code>scope</code>
 
271
     attributes, whose value is to be used by this custom tag.  If not  
 
272
  specified, the bean identified by <code>name</code> is itself used    
 
273
as the value of interest.  See below for more discussion about how a    
 
274
property can be referenced.</li>
 
275
 <li><em>scope</em> - Identifies the JSP scope ("page", "request", "session", 
 
276
    or "application" within which a particular bean will be searched for 
 
277
   (under the key specified by the <code>name</code> attribute) or created 
 
278
    (under the key specified by the <code>id</code> attribute).  If not 
 
279
   specified, beans will generally be searched for in the order listed above, 
 
280
    or created in page scope.</li>
 
281
 
 
282
</ul>
 
283
  <a name="doc.Properties.References"></a>
 
284
 
 
285
<h5>Property References</h5>
 
286
  
 
287
<p>Struts tags that support the <code>property</code> tag generally also recognize
 
288
a rich syntax for getting and setting properties.  There are three types
 
289
of references supported:  simple, nested, and indexed.</p>
 
290
  
 
291
<p><em>Simple References</em> - These are equivalent to the syntax you use
 
292
with the standard <code>&lt;jsp:getProperty&gt;</code> and <code>&lt;jsp:setProperty&gt;</code>
 
293
 tags.  A reference to a property named "foo" is converted into a method
 
294
call to <code>getFoo()</code> or <code>setFoo(value)</code> (as appropriate),
 
295
using the standard JavaBeans Specification naming conventions for bean properties.
 
296
 Struts uses the standard Java introspection APIs to identify the names of
 
297
the actual property getter and setter methods, so your beans can provided
 
298
customized method names through the use of a <code>BeanInfo</code> class.
 
299
 See the JavaBeans Specification, available at <a href="http://java.sun.com/products/javabeans/">
 
300
 http://java.sun.com/products/javabeans/</a>
 
301
, for more information.</p>
 
302
  
 
303
<p><em>Nested References</em> - Nested references are used to access a property
 
304
through a hierarchy of property names separated by periods ("."), similar
 
305
to the way that nested properties are accessed in JavaScript.  For example,
 
306
the following property reference in a getter (such as the <code>&lt;bean:define&gt;</code>
 
307
 tag discussed below):</p>
 
308
 
 
309
<pre>    property="foo.bar.baz"<br></pre>
 
310
 
 
311
<p>is translated into the equivalent the Java expression:</p>
 
312
 
 
313
<pre>    getFoo().getBar().getBaz()<br></pre>
 
314
 
 
315
<p>If a nested reference is used in a setter (such as when an input form
 
316
is processed), the property setter is called on the <strong>last</strong>
 
317
 property in the chain.  For the above property reference, the equivalent
 
318
Java expression would be:</p>
 
319
 
 
320
<pre>    getFoo().getBar().setBaz(value)<br></pre>
 
321
  
 
322
<p><em>Indexed References</em> - Subscripts can be used to access individual 
 
323
elements of properties whose value is actually an array, or whose underlying 
 
324
JavaBean offers indexed getter and setter methods.  For example, the following 
 
325
property reference in a getter (such as the <code>&lt;bean:define&gt;</code>
 
326
 tag discussed below):</p>
 
327
 
 
328
<pre>    property="foo[2]"<br></pre>
 
329
 
 
330
<p>is translated into the equivalent of the Java expression:</p>
 
331
 
 
332
<pre>    getFoo(2);<br></pre>
 
333
 
 
334
<p>while the same property reference in a setter would call the equivalent
 
335
of:</p>
 
336
 
 
337
<pre>    setFoo(2, value)<br></pre>
 
338
 
 
339
<p>As you can see from the above translations, the subscripts used in indexed 
 
340
references are <strong>zero relative</strong> (that is, the first element
 
341
in an array is <code>foo[0]</code>), just as is true in the Java language.</p>
 
342
  
 
343
<p><em>Combined References</em> - Nesting and indexing can be combined in 
 
344
arbitrary ways, so that expressions like <code>foo.bar[0].baz[2]</code> are 
 
345
legal.  You must be careful, of course, to ensure that the actual beans being 
 
346
accessed by these references have properties of the appropriate names and 
 
347
types.  Otherwise, JSP runtime exceptions will be thrown.</p>
 
348
  
 
349
<p>See the JavaDocs for <a href="http://jakarta.apache.org/commons/beanutils/api/org/apache/commons/beanutils/PropertyUtils.html">PropertyUtils</a>
 
350
 for more detailed information about the mechanisms that Struts uses to access 
 
351
properties in a general way, through Java reflection APIs.</p>
 
352
  
 
353
<hr>  <a name="doc.Creation"></a>
 
354
 
 
355
<h3>Bean Creation</h3>
 
356
  
 
357
<h5>Introduction</h5>
 
358
  
 
359
<p>New beans can be created, and introduced into one of the four standard 
 
360
JSP scopes (page, request, session, and application) through a variety of 
 
361
techniques.  The following subsections describe the use of the following approaches:</p>
 
362
 
 
363
<ul>
 
364
 <li>Java Code in Action Classes</li>
 
365
 <li>Java Code in Scriptlets</li>
 
366
 <li>The Standard <code>&lt;jsp:useBean&gt;</code> Tag</li>
 
367
 <li>The Struts <code>&lt;bean:define&gt;</code> Tag</li>
 
368
 <li>Other Struts Copying Tags</li>
 
369
 
 
370
</ul>
 
371
  
 
372
<h5>Java Code in Action Classes</h5>
 
373
  
 
374
<p>Because the JSP pages are compiled into Servlets, your <code>Action</code>
 
375
 classes that are invoked by the Struts controller servlet have convenient 
 
376
access to three of the four standard JSP scopes (request, session, and application).
 
377
 It is very common practice for the business logic contained in your <code>
 
378
Action</code> class to create results that are stored in request or session
 
379
scope, which will be used by a JSP page you forward control to in rendering
 
380
the next page of the user interface.</p>
 
381
  
 
382
<p><em>Request Scope</em> - To store a bean in request scope under name "cust", 
 
383
your <code>Action</code> class would execute code similar to this:</p>
 
384
 
 
385
<pre>    Customer customer = ... create or acquire a customer reference ...;<br>    request.setAttribute("cust", customer);<br></pre>
 
386
  
 
387
<p><em>Session Scope</em> - To store a bean in session scope under name "user" 
 
388
(perhaps in a logon action), your <code>Action</code> class would execute
 
389
code similar to this:</p>
 
390
 
 
391
<pre>    User user = ... look up valid user in the database ...;<br>    HttpSession session = request.getSession();<br>    session.setAttribute("user", user);<br></pre>
 
392
  
 
393
<p><em>Application Scope</em> - Generally, application scope beans are initialized
 
394
in the <code>init()</code> method of a startup servlet.  However, it is legal
 
395
for an <code>Action</code> class to create such beans, if this is appropriate,
 
396
like this:</p>
 
397
 
 
398
<pre>    Foo foo = ... create a Foo ...;<br>    servlet.getServletContext().setAttribute("foo", foo);<br></pre>
 
399
  
 
400
<h5>Java Code in Scriptlets</h5>
 
401
  
 
402
<p>While it is not a recommended practice in Struts-based applications (because
 
403
developers will be tempted to mix business logic and presentation logic in
 
404
their JSP pages), it is legal for scriptlet code in a JSP page to create
 
405
new JavaBeans dynamically, and add them to any of the four possible scopes,
 
406
as demonstrated in the code examples below:</p>
 
407
  
 
408
<p><em>Page Scope</em> - To store a bean in page scope under name "foo", your
 
409
scriptlet must execute code like this:</p>
 
410
 
 
411
<pre>&lt;%<br>    Foo foo = ... create a foo ...;<br>    pageContext.setAttribute("foo", foo, PageContext.PAGE_SCOPE);<br>%&gt;<br></pre>
 
412
  
 
413
<p><em>Request Scope</em> - To store a bean in request scope under name "cust", 
 
414
your scriplet must execute code like this:</p>
 
415
 
 
416
<pre>&lt;%<br>    Customer customer = ... create or acquire a customer reference ...;<br>    pageContext.setAttribute("cust", customer, PageContext.REQUEST_SCOPE);<br>%&gt;<br></pre>
 
417
  
 
418
<p><em>Session Scope</em> - To store a bean in session scope under name "user", 
 
419
(perhaps as a result of a validated login), your scriplet must execute code 
 
420
like this:</p>
 
421
 
 
422
<pre>&lt;%<br>    User user = ... look up valid user in the database ...;<br>    pageContext.setAttribute("user", user, PageContext.SESSION_SCOPE);<br>%&gt;<br></pre>
 
423
  
 
424
<p><em>Application Scope</em> - Generally, application scope beans are initialized
 
425
in the <code>init()</code> method of a startup servlet.  However, a scriptlet
 
426
can create such beans, if appropriate, like this:</p>
 
427
 
 
428
<pre>&lt;%<br>    Foo foo = ... create a Foo ...;<br>    pageContext.setAttribute("foo", foo, PageContext.APPLICATION_SCOPE);<br>%&gt;<br></pre>
 
429
  
 
430
<p><strong>NOTE</strong> - As mentioned above, using scriptlets in your JSP 
 
431
pages is strongly discouraged in a Struts based application, unless you are 
 
432
executing code that is <strong>only</strong> related to presentation of existing
 
433
data.  In general, your application's processing logic should be encapsulated
 
434
in <code>Action</code> classes (or in beans or EJBs called by those classes),
 
435
rather than being intermixed in your JSP pages.</p>
 
436
  
 
437
<h5>The Standard <code>&lt;jsp:useBean&gt;</code> Tag</h5>
 
438
  
 
439
<p>JavaServer Pages (JSP) offers a standard tag, <code>&lt;jsp:useBean&gt;</code>
 
440
 that can be used to create a new bean, or introduce a reference to an existing
 
441
bean, into a JSP page.  Beans (or bean references) introduced through this
 
442
mechanism are completely interoperable with beans created by any of the Struts
 
443
creation techniques described in this section.</p>
 
444
  
 
445
<p>You <strong>must</strong> use <code>&lt;jsp:useBean&gt;</code> to introduce 
 
446
a reference to an existing bean, if you wish to reference that bean with
 
447
other standard JSP tags (such as <code>&lt;jsp:getProperty&gt;</code> or <code>
 
448
&lt;jsp:setProperty&gt;</code>).  If you only wish to reference such beans
 
449
with other Struts tags, use of <code>&lt;jsp:useBean&gt;</code> is not required.</p>
 
450
  
 
451
<p>For more information about the <code>&lt;jsp:useBean&gt;</code> tag, see 
 
452
the JavaServer Pages Specification, available at <a href="http://java.sun.com/products/jsp/download.html">
 
453
 http://java.sun.com/products/jsp/download.html</a>
 
454
.</p>
 
455
  
 
456
<h5>The Struts <code>&lt;bean:define&gt;</code> Tag</h5>
 
457
  
 
458
<p>Struts provides a powerful, general purpose, tag (<code>&lt;bean:define&gt;</code>
 
459
) that can be used to create a new bean, in any scope, by copying another
 
460
bean (or the value of the property of another bean).  This tag supports the
 
461
"property" attribute, and therefore all the power of property references,
 
462
as discused <a href="#doc.Properties.References">above</a>
 
463
.  It can be used in a variety of different ways, described further below.
 
464
 Unless you specify the "toScope" attribute, all defined beans will be created
 
465
in page scope.</p>
 
466
  
 
467
<p><em>Introduce A String Constant</em> - You can create a new bean that
 
468
has a constant String value (or the result of calculating a runtime expression): 
 
469
</p>
 
470
 
 
471
<pre>    &lt;bean:define id="foo" value="This is a new String"/&gt;<br>    &lt;bean:define id="bar" value='&lt;%= "Hello, " + user.getName() %&gt;'/&gt;<br>    &lt;bean:define id="last" scope="session"<br>                 value='&lt;%= request.getRequestURI() %&gt;'/&gt;<br></pre>
 
472
  
 
473
<p><em>Copy An Existing Bean</em> - You can create a new reference to an existing
 
474
bean object.  You can specify the Java class or interface the new bean is
 
475
expected to conform to with the "type" attribute, or accept the default type
 
476
of <code>java.lang.Object</code> (this only affects the scripting variable
 
477
that is exposed to scriptlets, so it is not generally meaningful in Struts-based
 
478
applications).</p>
 
479
 
 
480
<pre>    &lt;bean:define id="foo" name="bar"/&gt;<br>    &lt;bean:define id="baz" name="bop" type="com.mycompany.MyBopClass"/&gt;<br></pre>
 
481
  
 
482
<p><em>Copy An Existing Bean Property</em> - You can create a new bean that 
 
483
is initialized to the value returned by a property getter.  The value of
 
484
the "property" attribute can be any simple, nested, or indexed property reference 
 
485
that follows the rules described earlier.  In the first example below, we 
 
486
also illustrate accessing the property of a request scope bean, and creating 
 
487
the new bean in session scope (rather than the default page scope).</p>
 
488
 
 
489
<pre>    &lt;bean:define id="foo" name="bar" property="baz" scope="request"<br>     toScope="session"/&gt;<br>    &lt;bean:define id="bop" name="user" property="role[3].name"/&gt;<br></pre>
 
490
  
 
491
<h5>Other Struts Copying Tags</h5>
 
492
  
 
493
<p>Struts offers a variety of bean creation tags that copy existing beans
 
494
(or bean properties) from the environment within which this page is running,
 
495
and the request that is currently being processed.  Not all of the attributes 
 
496
for each tag are illustrated in the examples below - see the <a href="../../../../../../userGuide/struts-bean.html">
 
497
Bean Tags Reference</a>
 
498
 for more information.  Any bean created by these tags exists only in page 
 
499
scope, for the remainder of the current page.</p>
 
500
  
 
501
<p><em>Copy A Cookie</em> - You can create a new bean containing a <code>
 
502
javax.servlet.http.Cookie</code> that was included in the current request.
 
503
 If no cookie of the specified name was included, a request time expression
 
504
will be thrown - therefore, it is common to nest the use of this tag inside
 
505
a <code>&lt;logic:present cookie="xxx"&gt;</code> tag to ensure that the
 
506
cookie was really included.  If there is the possibility that more than one
 
507
cookie of the same name was included, specify the "multiple" attribute (and
 
508
the resulting bean will be an array of Cookies, instead of a single Cookie).</p>
 
509
 
 
510
<pre>    &lt;bean:cookie id="foo" name="cookiename"/&gt;<br>    &lt;bean:cookie id="all" name="JSESSIONID" multiple="true"/&gt;<br></pre>
 
511
  
 
512
<p><em>Copy A Request Header</em> - You can create a new bean containing
 
513
the value of an HTTP header included in this request.  If no header of the 
 
514
specified name was included, a request time exception will be thrown - therefore,
 
515
it is common to nest the use of this tag inside a <code>&lt;logic:present
 
516
header="xxx"&gt;</code> tag to ensure that the header was really included.
 
517
 If there is the possibility that more than one header of the same name was
 
518
included, specify the "multiple" attribute (and the resulting value bean
 
519
will be an array of String values, instead of a single String).</p>
 
520
 
 
521
<pre>    &lt;bean:header id="agent" name="User-Agent"/&gt;<br>    &lt;bean:header id="languages" name="Accept-Language" multiple="true"/&gt;<br></pre>
 
522
  
 
523
<p><em>Copy A Dynamically Created Response</em> - You can generate an internal 
 
524
request to the application you are running, and turn the response data that
 
525
is returned from that request into a bean (of type String).  One possible
 
526
use for this technique is to acquire dynamically created XML formatted data
 
527
that will be stored in a bean and later manipulated (such as by applying
 
528
an XSLT stylesheet).  If the current request is part of a session, the generated 
 
529
request for the include will also include the session identifier (and thus
 
530
be considered part of the same session).</p>
 
531
 
 
532
<pre>    &lt;bean:include id="text" name="/generateXml?param1=a&amp;param2=b"/&gt;<br></pre>
 
533
  
 
534
<p><em>Copy A JSP Implicitly Defined Object</em> - You can create a bean
 
535
that is one of the JSP implicitly defined objects (see the JSP spec for more 
 
536
details).  This is useful if you wish to perform property getter actions against
 
537
the implicit object with a custom tag instead of a scriptlet.</p>
 
538
 
 
539
<pre>    &lt;bean:page id="app" property="application"/&gt;<br>    &lt;bean:page id="sess" property="session"/&gt;<br></pre>
 
540
  
 
541
<p><em>Copy A Request Parameter</em> - You can create a new bean containing
 
542
the value of a parameter included in this request.  If no parameter of the 
 
543
specified name was included, a request time exception will be thrown - therefore,
 
544
it is common to nest the use of this tag inside a <code>&lt;logic:present
 
545
parameter="xxx"&gt;</code> tag to ensure that the parameter was really included.
 
546
 If there is the possibility that more than one parameter of the same name
 
547
was included, specify the "multiple" attribute (and the resulting value bean
 
548
will be an array of String values, instead of a single String).</p>
 
549
 
 
550
<pre>    &lt;bean:parameter id="name" name="name"/&gt;<br>    &lt;bean:header id="options" name="option" multiple="true"/&gt;<br></pre>
 
551
  
 
552
<p><em>Copy a Web Application Resource</em> - You can create a new bean containing
 
553
either the value of a web application resource as a String, or a <code>java.io.InputStream</code>
 
554
 for reading the content of that resource. The resource is accessed with
 
555
a context-relative path (beginning with "/"), using the <code>ServletContext.getResource()</code>
 
556
 or <code>ServletContext.getResourceAsStream()</code> methods on the underlying 
 
557
application object.</p>
 
558
 
 
559
<pre>    &lt;bean:resource id="deployment" name="/WEB-INF/web.xml"/&gt;<br>    &lt;bean:resource id="stream" name="/WEB-INF/web.xml"<br>                   input="true"/&gt;<br></pre>
 
560
  
 
561
<p><em>Copy A Struts Configuration Object</em> - You can create a new bean 
 
562
containing one of the standard Struts framework configuration objects.  Doing 
 
563
this gives you access to the properties of the configuration object, if needed. 
 
564
</p>
 
565
 
 
566
<pre>    &lt;bean:struts id="form" formBean="CustomerForm"/&gt;<br>    &lt;bean:struts id="fwd" forward="success"/&gt;<br>    &lt;bean:struts id="map" mapping="/saveCustomer"/&gt;<br></pre>
 
567
   
 
568
<hr>  <a name="doc.Output"></a>
 
569
 
 
570
<h3>Bean Output</h3>
 
571
  
 
572
<p>None of the Struts Bean tags discussed so far render any output to the 
 
573
response page that is being generated from this JSP page.  They are executed 
 
574
in order to make relevant Java objects visible as beans for further manipulation.
 
575
 The following tags cause output to be written to the response, and therefore
 
576
made visible to the ultimate requester.</p>
 
577
  
 
578
<p><em>Render An Internationalized Message</em> - You can specify a message 
 
579
key (with optional parameter replacement objects) that are passed to a <a href="../../util/MessageResources.html">
 
580
MessageResources</a>
 
581
 object that returns the corresponding message text.  The message text will
 
582
be copied to the response currently being created.  By default, messages
 
583
are looked up in the application resources bundle that is initialized for
 
584
you (as an application scope bean) by the Struts controller servlet, using
 
585
the Locale must recently stored in the user's session.  These defaults can
 
586
be overridden by setting values for the "bundle" and "locale" attributes,
 
587
as described in the <a href="../../../../../../userGuide/struts-bean.html#message">
 
588
Bean Tags Reference</a>
 
589
. </p>
 
590
<pre>    &lt;bean:message key="label.Cancel"/&gt;<br>    &lt;bean:message key="message.hello" arg0='&lt;%= user.getFullName() %&gt;'/&gt;<br></pre>
 
591
  
 
592
<p><em>Render A Bean or Bean Property</em> - The contents of a bean, or bean 
 
593
property, are converted to a String and then copied to the response currently 
 
594
being created.  This tag understands the syntax for simple, nested, and indexed
 
595
property references described <a href="#doc.Properties.Reference"> above</a>
 
596
.  Beans from any scope can be requested - by default, the scopes are searched
 
597
in expanding visibility order (page, request, session, and application) to
 
598
locate the requested bean.</p>
 
599
 
 
600
<pre>    &lt;bean:write name="username"/&gt;<br>    &lt;bean:write name="user" property="fullName"/&gt;<br>    &lt;bean:write name="customer" property="orders[2].partNumber"<br>                scope="session"/&gt;<br></pre>
 
601
<P>
 
602
 
 
603
<P>
 
604
<HR>
 
605
 
 
606
<!-- ========== START OF NAVBAR ========== -->
 
607
<A NAME="navbar_bottom"><!-- --></A>
 
608
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0">
 
609
<TR>
 
610
<TD COLSPAN=3 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
 
611
<A NAME="navbar_bottom_firstrow"><!-- --></A>
 
612
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3">
 
613
  <TR ALIGN="center" VALIGN="top">
 
614
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
 
615
  <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT>&nbsp;</TD>
 
616
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <FONT CLASS="NavBarFont1">Class</FONT>&nbsp;</TD>
 
617
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-use.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A>&nbsp;</TD>
 
618
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
 
619
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
 
620
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
 
621
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
 
622
  </TR>
 
623
</TABLE>
 
624
</TD>
 
625
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
 
626
</EM>
 
627
</TD>
 
628
</TR>
 
629
 
 
630
<TR>
 
631
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
 
632
&nbsp;<A HREF="../../../../../org/apache/struts/plugins/package-summary.html"><B>PREV PACKAGE</B></A>&nbsp;
 
633
&nbsp;<A HREF="../../../../../org/apache/struts/taglib/html/package-summary.html"><B>NEXT PACKAGE</B></A></FONT></TD>
 
634
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
 
635
  <A HREF="../../../../../index.html" TARGET="_top"><B>FRAMES</B></A>  &nbsp;
 
636
&nbsp;<A HREF="package-summary.html" TARGET="_top"><B>NO FRAMES</B></A>  &nbsp;
 
637
&nbsp;
 
638
<SCRIPT>
 
639
  <!--
 
640
  if(window==top) {
 
641
    document.writeln('<A HREF="../../../../../allclasses-noframe.html" TARGET=""><B>All Classes</B></A>');
 
642
  }
 
643
  //-->
 
644
</SCRIPT>
 
645
<NOSCRIPT>
 
646
<A HREF="../../../../../allclasses-noframe.html" TARGET=""><B>All Classes</B></A>
 
647
</NOSCRIPT>
 
648
</FONT></TD>
 
649
</TR>
 
650
</TABLE>
 
651
<!-- =========== END OF NAVBAR =========== -->
 
652
 
 
653
<HR>
 
654
Copyright � 2000-2003 - Apache Software Foundation
 
655
</BODY>
 
656
</HTML>