View Javadoc

    1   /*
    2    * $Id: Push.java 497654 2007-01-19 00:21:57Z rgielen $
    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  package org.apache.struts2.components;
    22
    23  import java.io.Writer;
    24
    25  import org.apache.struts2.views.annotations.StrutsTag;
    26  import org.apache.struts2.views.annotations.StrutsTagAttribute;
    27
    28  import com.opensymphony.xwork2.util.ValueStack;
    29
    30  /***
    31   * <!-- START SNIPPET: javadoc -->
    32   * <p>Push value on stack for simplified usage.</p>
    33   * <!-- END SNIPPET: javadoc -->
    34   *
    35   * <!-- START SNIPPET: params -->
    36   * <ul>
    37   *      <li>value* (Object) - value to be pushed into the top of the stack</li>
    38   * </ul>
    39   * <!-- END SNIPPET: params -->
    40   *
    41   *
    42   * <p/> <b>Examples</b>
    43   * <pre>
    44   * <!-- START SNIPPET: example1 -->
    45   * &lt;s:push value="user"&gt;
    46   *     &lt;s:propery value="firstName" /&gt;
    47   *     &lt;s:propery value="lastName" /&gt;
    48   * &lt;/s:push&gt;
    49   * <!-- END SNIPPET: example1 -->
    50   * </pre>
    51   *
    52   * <!-- START SNIPPET: example1description -->
    53   * Pushed user into the stack, and hence property tag could access user's properties
    54   * (firstName, lastName etc) since user is not at the top of the stack
    55   * <!-- END SNIPPET: example1description -->
    56   *
    57   * <pre>
    58   * <!-- START SNIPPET: example2 -->
    59   *  &lt;s:push value="myObject"&gt;                              ----- (1)
    60   *       &lt;s:bean name="jp.SomeBean" id="myBean"/&gt;        ----- (2)
    61   *          &lt;s:param name="myParam" value="top"/&gt;        ----- (3)
    62   *       &lt;/s:bean&gt;
    63   *   &lt;/s:push&gt;
    64   * <!-- END SNIPPET: example2 -->
    65   * </pre>
    66   *
    67   * <pre>
    68   * <!-- START SNIPPET: example2description -->
    69   * when in (1), myObject is at the top of the stack
    70   * when in (2), jp.SomeBean is in the top of stack, also in stack's context with key myBean
    71   * when in (3), top will get the jp.SomeBean instance
    72   * <!-- END SNIPPET: example2description -->
    73   * </pre>
    74   *
    75   * <pre>
    76   * <!-- START SNIPPET: example3 -->
    77   * &lt;s:push value="myObject"&gt;                                       ---(A)
    78   *    &lt;s:bean name="jp.SomeBean" id="myBean"/&gt;                   ---(B)
    79   *       &lt;s:param name="myParam" value="top.mySomeOtherValue"/&gt;  ---(C)
    80   *    &lt;/s:bean&gt;
    81   * &lt;/s:push&gt;
    82   * <!-- END SNIPPET: example3 -->
    83   * </pre>
    84   *
    85   * <pre>
    86   * <!-- START SNIPPET: example3description -->
    87   * when in (A), myObject is at the top of the stack
    88   * when in (B), jp.SomeBean is at the top of the stack, also in context with key myBean
    89   * when in (C), top refers to jp.SomeBean instance. so top.mySomeOtherValue would invoke SomeBean's mySomeOtherValue() method
    90   * <!-- END SNIPPET: example3description -->
    91   * </pre>
    92   *
    93   * <pre>
    94   * <!-- START SNIPPET: example4 -->
    95   * &lt;s:push value="myObject"&gt;                                 ---- (i)
    96   *    &lt;s:bean name="jp.SomeBean" id="myBean"/&gt;             ---- (ii)
    97   *       &lt;s:param name="myParam" value="[1].top"/&gt;         -----(iii)
    98   *    &lt;/s:bean&gt;
    99   * &lt;/s:push&gt;
    100  * <!-- END SNIPPET: example4 -->
    101  * </pre>
    102  *
    103  * <pre>
    104  * <!-- START SNIPPET: example4description -->
    105  * when in (i), myObject is at the top of the stack
    106  * when in (ii), jp.SomeBean is at the top of the stack, followed by myObject
    107  * when in (iii), [1].top will returned top of the cut of stack starting from myObject, namely myObject itself
    108  * <!-- END SNIPPET: example4description -->
    109  * </pre>
    110  *
    111  */
    112 @StrutsTag(name="push", tldTagClass="org.apache.struts2.views.jsp.PushTag", description="Push value on stack for simplified usage.")
    113 public class Push extends Component {
    114     protected String value;
    115     protected boolean pushed;
    116
    117     public Push(ValueStack stack) {
    118         super(stack);
    119     }
    120
    121     public boolean start(Writer writer) {
    122         boolean result = super.start(writer);
    123
    124         ValueStack stack = getStack();
    125
    126         if (stack != null) {
    127             stack.push(findValue(value, "value", "You must specify a value to push on the stack. Example: person"));
    128             pushed = true;
    129         } else {
    130             pushed = false; // need to ensure push is assigned, otherwise we may have a leftover value
    131         }
    132
    133         return result;
    134     }
    135
    136     public boolean end(Writer writer, String body) {
    137         ValueStack stack = getStack();
    138
    139         if (pushed && (stack != null)) {
    140             stack.pop();
    141         }
    142
    143         return super.end(writer, body);
    144     }
    145
    146     @StrutsTagAttribute(description="Value to push on stack", required=true)
    147     public void setValue(String value) {
    148         this.value = value;
    149     }
    150 }