001: package org.apache.velocity.tools.struts;
002:
003: /*
004: * Licensed to the Apache Software Foundation (ASF) under one
005: * or more contributor license agreements. See the NOTICE file
006: * distributed with this work for additional information
007: * regarding copyright ownership. The ASF licenses this file
008: * to you under the Apache License, Version 2.0 (the
009: * "License"); you may not use this file except in compliance
010: * with the License. You may obtain a copy of the License at
011: *
012: * http://www.apache.org/licenses/LICENSE-2.0
013: *
014: * Unless required by applicable law or agreed to in writing,
015: * software distributed under the License is distributed on an
016: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017: * KIND, either express or implied. See the License for the
018: * specific language governing permissions and limitations
019: * under the License.
020: */
021:
022: import java.util.List;
023:
024: import org.apache.struts.util.MessageResources;
025:
026: /**
027: * <p>View tool that provides methods to render Struts
028: * application resources for internationalized text.</p>
029: *
030: * <p><pre>
031: * Template example(s):
032: * #if( $text.greeting.exists )
033: * $text.greeting
034: * #end
035: *
036: * Toolbox configuration:
037: * <tool>
038: * <key>text</key>
039: * <scope>request</scope>
040: * <class>org.apache.velocity.tools.struts.MessageTool</class>
041: * </tool>
042: * </pre></p>
043: *
044: * <p>This tool should only be used in the request scope.</p>
045: *
046: * @author <a href="mailto:sidler@teamup.com">Gabe Sidler</a>
047: * @since VelocityTools 1.0
048: * @version $Id: MessageTool.java 477914 2006-11-21 21:52:11Z henning $
049: */
050: public class MessageTool extends MessageResourcesTool {
051:
052: /**
053: * Default constructor. Tool must be initialized before use.
054: */
055: public MessageTool() {
056: }
057:
058: /**
059: * Looks up and returns the localized message for the specified key.
060: * The user's locale is consulted to determine the language of the
061: * message.
062: *
063: * <p><pre>Example use: $text.forms.profile.title</pre></p>
064: *
065: * @param key message key
066: */
067: public TextKey get(String key) {
068: return new TextKey(this , key);
069: }
070:
071: /**
072: * Looks up and returns the localized message for the specified key.
073: * The user's locale is consulted to determine the language of the
074: * message.
075: *
076: * @param key message key
077: * @param bundle The bundle name to look for.
078: *
079: * @return the localized message for the specified key or
080: * <code>null</code> if no such message exists
081: * @since VelocityTools 1.1
082: */
083: public String get(String key, String bundle) {
084: return get(key, bundle, (Object[]) null);
085: }
086:
087: /**
088: * Looks up and returns the localized message for the specified key.
089: * Replacement parameters passed with <code>args</code> are
090: * inserted into the message. The user's locale is consulted to
091: * determine the language of the message.
092: *
093: * @param key message key
094: * @param args replacement parameters for this message
095: *
096: * @return the localized message for the specified key or
097: * <code>null</code> if no such message exists
098: */
099: public String get(String key, Object args[]) {
100: return get(key, null, args);
101: }
102:
103: /**
104: * Looks up and returns the localized message for the specified key.
105: * Replacement parameters passed with <code>args</code> are
106: * inserted into the message. The user's locale is consulted to
107: * determine the language of the message.
108: *
109: * @param key message key
110: * @param bundle The bundle name to look for.
111: * @param args replacement parameters for this message
112: * @since VelocityTools 1.1
113: * @return the localized message for the specified key or
114: * <code>null</code> if no such message exists
115: */
116: public String get(String key, String bundle, Object args[]) {
117: MessageResources res = getResources(bundle);
118: if (res == null) {
119: return null;
120: }
121:
122: // return the requested message
123: if (args == null) {
124: return res.getMessage(this .locale, key);
125: } else {
126: return res.getMessage(this .locale, key, args);
127: }
128: }
129:
130: /**
131: * Same as {@link #get(String key, Object[] args)}, but takes a
132: * <code>java.util.List</code> instead of an array. This is more
133: * Velocity friendly.
134: *
135: * @param key message key
136: * @param args replacement parameters for this message
137: *
138: * @return the localized message for the specified key or
139: * <code>null</code> if no such message exists
140: */
141: public String get(String key, List args) {
142: return get(key, null, args);
143: }
144:
145: /**
146: * Same as {@link #get(String key, Object[] args)}, but takes a
147: * <code>java.util.List</code> instead of an array. This is more
148: * Velocity friendly.
149: *
150: * @param key message key
151: * @param bundle The bundle name to look for.
152: * @param args replacement parameters for this message
153: * @since VelocityTools 1.1
154: * @return the localized message for the specified key or
155: * <code>null</code> if no such message exists
156: */
157: public String get(String key, String bundle, List args) {
158: return get(key, bundle, args.toArray());
159: }
160:
161: /**
162: * Checks if a message string for a specified message key exists
163: * for the user's locale.
164: *
165: * @param key message key
166: *
167: * @return <code>true</code> if a message strings exists,
168: * <code>false</code> otherwise
169: */
170: public boolean exists(String key) {
171: return exists(key, null);
172: }
173:
174: /**
175: * Checks if a message string for a specified message key exists
176: * for the user's locale.
177: *
178: * @param key message key
179: * @param bundle The bundle name to look for.
180: * @since VelocityTools 1.1
181: * @return <code>true</code> if a message strings exists,
182: * <code>false</code> otherwise
183: */
184: public boolean exists(String key, String bundle) {
185: MessageResources res = getResources(bundle);
186: if (res == null) {
187: return false;
188: }
189:
190: // Return the requested message presence indicator
191: return res.isPresent(this .locale, key);
192: }
193:
194: /**
195: * Helper class to simplify tool usage when retrieving
196: * no-arg messages from the default bundle that have periods
197: * in their key.
198: *
199: * <p>So instead of <code>$text.get("forms.profile.title")</code>,1
200: * you can just type <code>$text.forms.profile.title</code>. Also,
201: * this lets you do things like:
202: * <pre>
203: * #if( $text.forms.profile.exists )
204: * #set( $profiletext = $text.forms.profile )
205: * <h1>$profiletext.title</h1>
206: * <h3>$profiletext.subtitle</h3>
207: * #end
208: * </pre>
209: * </p>
210: *
211: * @since VelocityTools 1.2
212: */
213: public class TextKey {
214: private MessageTool tool;
215: private String key;
216: private String bundle;
217: private Object[] args;
218:
219: /**
220: * @deprecated This will be removed after VelocityTools 1.3
221: */
222: public TextKey(MessageTool tool, String key) {
223: this (tool, key, null, null);
224: }
225:
226: /**
227: * @since VelocityTools 1.3
228: */
229: public TextKey(MessageTool tool, String key, String bundle,
230: Object[] args) {
231: this .tool = tool;
232: this .key = key;
233: this .bundle = bundle;
234: this .args = args;
235: }
236:
237: /**
238: * Appends a period and the new key to the current
239: * key and returns a new TextKey instance with the
240: * combined result as its key.
241: */
242: public TextKey get(String appendme) {
243: StringBuffer sb = new StringBuffer(this .key);
244: sb.append('.');
245: sb.append(appendme);
246: return new TextKey(this .tool, sb.toString(), this .bundle,
247: this .args);
248: }
249:
250: /**
251: * Returns a new TextKey with the specified resource bundle set.
252: * @since VelocityTools 1.3
253: */
254: public TextKey bundle(String setme) {
255: return new TextKey(this .tool, this .key, setme, this .args);
256: }
257:
258: /**
259: * Returns a new TextKey with the specified argument
260: * to be inserted into the text output. If arguments already
261: * exist for this TextKey, the new arguments will be appended
262: * to the old ones in the new TextKey that is returned.
263: *
264: * @since VelocityTools 1.3
265: */
266: public TextKey insert(Object addme) {
267: return insert(new Object[] { addme });
268: }
269:
270: /**
271: * Returns a new TextKey with the specified arguments
272: * to be inserted into the text output. If arguments already
273: * exist for this TextKey, the new arguments will be appended
274: * to the old ones in the new TextKey that is returned.
275: *
276: * @since VelocityTools 1.3
277: */
278: public TextKey insert(Object addme, Object metoo) {
279: return insert(new Object[] { addme, metoo });
280: }
281:
282: /**
283: * Returns a new TextKey with the specified arguments
284: * to be inserted into the text output. If arguments already
285: * exist for this TextKey, the new arguments will be appended
286: * to the old ones in the new TextKey that is returned.
287: *
288: * @since VelocityTools 1.3
289: */
290: public TextKey insert(Object addme, Object metoo, Object methree) {
291: return insert(new Object[] { addme, metoo, methree });
292: }
293:
294: /**
295: * Returns a new TextKey with the specified List of arguments
296: * to be inserted into the text output. If arguments already
297: * exist for this TextKey, the new arguments will be appended
298: * to the old ones in the new TextKey that is returned.
299: *
300: * @since VelocityTools 1.3
301: */
302: public TextKey insert(List addme) {
303: // convert the list to an array
304: Object[] newargs = ((List) addme).toArray();
305: return insert(newargs);
306: }
307:
308: /**
309: * Returns a new TextKey with the specified array of arguments
310: * to be inserted into the text output. If arguments already
311: * exist for this TextKey, the new arguments will be appended
312: * to the old ones in the new TextKey that is returned.
313: *
314: * @since VelocityTools 1.3
315: */
316: public TextKey insert(Object[] addme) {
317: Object[] newargs;
318: if (this .args == null) {
319: // we can just use the ones we're adding
320: newargs = addme;
321: } else {
322: // create the new array to hold both the new and old ones
323: newargs = new Object[this .args.length + addme.length];
324: // copy the old args into the newargs array
325: System.arraycopy(this .args, 0, newargs, 0,
326: this .args.length);
327: // copy the args to be inserted into the newargs array
328: System.arraycopy(addme, 0, newargs, this .args.length,
329: addme.length);
330: }
331: // return an new TextKey
332: return new TextKey(this .tool, this .key, this .bundle,
333: newargs);
334: }
335:
336: /**
337: * This will return a new TextKey that has <b>no</b> arguments to
338: * be inserted into the text output.
339: *
340: * @since VelocityTools 1.3
341: */
342: public TextKey clearArgs() {
343: return new TextKey(this .tool, this .key, this .bundle, null);
344: }
345:
346: /**
347: * Convenience method to allow <code>$text.key.exists</code> syntax.
348: * @since VelocityTools 1.3
349: */
350: public boolean getExists() {
351: return exists();
352: }
353:
354: /**
355: * Checks for the existence of the key that we've built up.
356: * @since VelocityTools 1.3
357: */
358: public boolean exists() {
359: return tool.exists(key, bundle);
360: }
361:
362: /**
363: * Renders the text output according to the collected key value,
364: * bundle, and arguments.
365: */
366: public String toString() {
367: return tool.get(key, bundle, args);
368: }
369: }
370:
371: }
|