View Javadoc

1   /*
2    * $Id: Push.java 454565 2006-10-10 00:02:56Z jmitchell $
3    *
4    * Copyright 2006 The Apache Software Foundation.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License");
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *      http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  package org.apache.struts2.components;
19  
20  import java.io.Writer;
21  
22  import com.opensymphony.xwork2.util.ValueStack;
23  
24  /***
25   * <!-- START SNIPPET: javadoc -->
26   * <p>Push value on stack for simplified usage.</p>
27   * <!-- END SNIPPET: javadoc -->
28   *
29   * <!-- START SNIPPET: params -->
30   * <ul>
31   * 		<li>value* (Object) - value to be pushed into the top of the stack</li>
32   * </ul>
33   * <!-- END SNIPPET: params -->
34   *
35   *
36   * <p/> <b>Examples</b>
37   * <pre>
38   * <!-- START SNIPPET: example1 -->
39   * &lt;s:push value="user"&gt;
40   *     &lt;s:propery value="firstName" /&gt;
41   *     &lt;s:propery value="lastName" /&gt;
42   * &lt;/s:push&gt;
43   * <!-- END SNIPPET: example1 -->
44   * </pre>
45   * 
46   * <!-- START SNIPPET: example1description -->
47   * Pushed user into the stack, and hence property tag could access user's properties 
48   * (firstName, lastName etc) since user is not at the top of the stack
49   * <!-- END SNIPPET: example1description -->
50   * 
51   * <pre>
52   * <!-- START SNIPPET: example2 -->
53   *  &lt;s:push value="myObject"&gt;                              ----- (1)
54   *       &lt;s:bean name="jp.SomeBean" id="myBean"/&gt;        ----- (2)
55   * 		    &lt;s:param name="myParam" value="top"/&gt;        ----- (3)
56   *       &lt;/s:bean&gt;
57   *   &lt;/s:push&gt;
58   * <!-- END SNIPPET: example2 -->
59   * </pre>
60   * 
61   * <pre>
62   * <!-- START SNIPPET: example2description -->
63   * when in (1), myObject is at the top of the stack
64   * when in (2), jp.SomeBean is in the top of stack, also in stack's context with key myBean
65   * when in (3), top will get the jp.SomeBean instance
66   * <!-- END SNIPPET: example2description -->
67   * </pre>
68   * 
69   * <pre>
70   * <!-- START SNIPPET: example3 -->
71   * &lt;s:push value="myObject"&gt;                                       ---(A)
72   *    &lt;s:bean name="jp.SomeBean" id="myBean"/&gt;                   ---(B)
73   *       &lt;s:param name="myParam" value="top.mySomeOtherValue"/&gt;  ---(C)
74   *    &lt;/s:bean&gt;
75   * &lt;/s:push&gt;
76   * <!-- END SNIPPET: example3 -->
77   * </pre>
78   * 
79   * <pre>
80   * <!-- START SNIPPET: example3description -->
81   * when in (A), myObject is at the top of the stack
82   * when in (B), jp.SomeBean is at the top of the stack, also in context with key myBean
83   * when in (C), top refers to jp.SomeBean instance. so top.mySomeOtherValue would invoke SomeBean's mySomeOtherValue() method
84   * <!-- END SNIPPET: example3description -->
85   * </pre>
86   * 
87   * <pre>
88   * <!-- START SNIPPET: example4 -->       
89   * &lt;s:push value="myObject"&gt;                                 ---- (i)
90   *    &lt;s:bean name="jp.SomeBean" id="myBean"/&gt;             ---- (ii)
91   *       &lt;s:param name="myParam" value="[1].top"/&gt;         -----(iii)
92   *    &lt;/s:bean&gt;
93   * &lt;/s:push&gt;
94   * <!-- END SNIPPET: example4 -->
95   * </pre>
96   * 
97   * <pre>
98   * <!-- START SNIPPET: example4description -->
99   * when in (i), myObject is at the top of the stack
100  * when in (ii), jp.SomeBean is at the top of the stack, followed by myObject
101  * when in (iii), [1].top will returned top of the cut of stack starting from myObject, namely myObject itself 
102  * <!-- END SNIPPET: example4description -->
103  * </pre>
104  * 
105  * @s.tag name="push" tld-body-content="JSP" tld-tag-class="org.apache.struts2.views.jsp.PushTag"
106  * description="Push value on stack for simplified usage."
107  */
108 public class Push extends Component {
109     protected String value;
110     protected boolean pushed;
111 
112     public Push(ValueStack stack) {
113         super(stack);
114     }
115 
116     public boolean start(Writer writer) {
117         boolean result = super.start(writer);
118 
119         ValueStack stack = getStack();
120 
121         if (stack != null) {
122             stack.push(findValue(value, "value", "You must specify a value to push on the stack. Example: person"));
123             pushed = true;
124         } else {
125             pushed = false; // need to ensure push is assigned, otherwise we may have a leftover value
126         }
127 
128         return result;
129     }
130 
131     public boolean end(Writer writer, String body) {
132         ValueStack stack = getStack();
133 
134         if (pushed && (stack != null)) {
135             stack.pop();
136         }
137 
138         return super.end(writer, body);
139     }
140 
141     /***
142      * Value to push on stack
143      * @s.tagattribute required="true"
144      */
145     public void setValue(String value) {
146         this.value = value;
147     }
148 }