View Javadoc

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