View Javadoc

1   /*
2    * $Id: Text.java 757826 2009-03-24 14:53:29Z wesw $
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.IOException;
25  import java.io.Writer;
26  import java.util.ArrayList;
27  import java.util.Collections;
28  import java.util.List;
29  
30  import org.apache.struts2.views.annotations.StrutsTag;
31  import org.apache.struts2.views.annotations.StrutsTagAttribute;
32  import org.apache.struts2.util.TextProviderHelper;
33  import org.apache.commons.lang.xwork.StringUtils;
34  
35  import com.opensymphony.xwork2.util.ValueStack;
36  import com.opensymphony.xwork2.util.logging.Logger;
37  import com.opensymphony.xwork2.util.logging.LoggerFactory;
38  
39  /***
40   * <!-- START SNIPPET: javadoc -->
41   * Render a I18n text message.
42   *
43   * <p/>
44   *
45   * The message must be in a resource bundle
46   * with the same name as the action that it is associated with. In practice
47   * this means that you should create a properties file in the same package
48   * as your Java class with the same name as your class, but with .properties
49   * extension.
50   *
51   * <p/>
52   *
53   * If the named message is not found in a property file, then the body of the
54   * tag will be used as default message. If no body is used, then the stack will
55   * be searched, and if a value is returned, it will written to the output.
56   * If no value is found on the stack, the key of the message will be written out.
57   *
58   * <!-- END SNIPPET: javadoc -->
59   *
60   *
61   *
62   * <!-- START SNIPPET: params -->
63   *
64   * <ul>
65   *      <li>name* (String) - the i18n message key</li>
66   * </ul>
67   *
68   * <!-- END SNIPPET: params -->
69   *
70   * <p/>
71   *
72   * Example:
73   * <pre>
74   * <!-- START SNIPPET: exdescription -->
75   *
76   * Accessing messages from a given bundle (the i18n Shop example bundle in the first example) and using bundle defined through the framework in the second example.</p>
77   *
78   * <!-- END SNIPPET: exdescription -->
79   * </pre>
80   *
81   * <pre>
82   * <!-- START SNIPPET: example -->
83   *
84   * &lt;!-- First Example --&gt;
85   * &lt;s:i18n name="struts.action.test.i18n.Shop"&gt;
86   *     &lt;s:text name="main.title"/&gt;
87   * &lt;/s:i18n&gt;
88   *
89   * &lt;!-- Second Example --&gt;
90   * &lt;s:text name="main.title" /&gt;
91   *
92   * &lt;!-- Third Examlpe --&gt;
93   * &lt;s:text name="i18n.label.greetings"&gt;
94   *    &lt;s:param &gt;Mr Smith&lt;/s:param&gt;
95   * &lt;/s:text&gt;
96   *
97   * <!-- END SNIPPET: example -->
98   * </pre>
99   *
100  *
101  * <pre>
102  * <!-- START SNIPPET: i18nExample -->
103  *
104  * &lt;-- Fourth Example --&gt;
105  * &lt;s:text name="some.key" /&gt;
106  *
107  * &lt;-- Fifth Example --&gt;
108  * &lt;s:text name="some.invalid.key" &gt;
109  *    The Default Message That Will Be Displayed
110  * &lt;/s:text&gt;
111  *
112  * <!-- END SNIPPET: i18nExample -->
113  * </pre>
114  *
115  * @see Param
116  *
117  */
118 @StrutsTag(
119     name="text",
120     tldTagClass="org.apache.struts2.views.jsp.TextTag",
121     description="Render a I18n text message")
122 public class Text extends ContextBean implements Param.UnnamedParametric {
123     private static final Logger LOG = LoggerFactory.getLogger(Text.class);
124 
125     protected List values = Collections.EMPTY_LIST;
126     protected String actualName;
127     protected String name;
128     protected String searchStack;
129 
130     public Text(ValueStack stack) {
131         super(stack);
132     }
133 
134     @StrutsTagAttribute(description=" Name of resource property to fetch", required=true)
135     public void setName(String name) {
136         this.name = name;
137     }
138 
139     @StrutsTagAttribute(description="Search the stack if property is not found on resources", type = "Boolean", defaultValue = "true")
140     public void setSearchValueStack(String searchStack) {
141         this.searchStack = searchStack;
142     }
143 
144     public boolean usesBody() {
145         // overriding this to true such that EVAL_BODY_BUFFERED is return and
146         // bodyContent will be valid hence, text between start & end tag will
147         // be honoured as default message (WW-1268)
148         return true;
149     }
150 
151     public boolean end(Writer writer, String body) {
152         actualName = findString(name, "name", "You must specify the i18n key. Example: welcome.header");
153         String defaultMessage;
154         if (StringUtils.isNotEmpty(body)) {
155             defaultMessage = body;
156         } else {
157             defaultMessage = actualName;
158         }
159 
160         Boolean doSearchStack = searchStack != null ? (Boolean) findValue(searchStack, Boolean.class) : true;
161         String msg = TextProviderHelper.getText(actualName, defaultMessage, values, getStack(), doSearchStack == null || doSearchStack);
162 
163         if (msg != null) {
164             try {
165                 if (getVar() == null) {
166                     writer.write(msg);
167                 } else {
168                     putInContext(msg);
169                 }
170             } catch (IOException e) {
171                 LOG.error("Could not write out Text tag", e);
172             }
173         }
174 
175         return super.end(writer, "");
176     }
177 
178     public void addParameter(String key, Object value) {
179         addParameter(value);
180     }
181 
182     public void addParameter(Object value) {
183         if (values.isEmpty()) {
184             values = new ArrayList(4);
185         }
186 
187         values.add(value);
188     }
189 }