001: /*
002: * Copyright (c) 2002-2006 by OpenSymphony
003: * All rights reserved.
004: */
005: package com.opensymphony.xwork;
006:
007: import com.opensymphony.xwork.util.OgnlValueStack;
008:
009: import java.util.List;
010: import java.util.ResourceBundle;
011:
012: /**
013: * Provides access to {@link ResourceBundle}s and their underlying text messages.
014: * Implementing classes can delegate {@link TextProviderSupport}. Messages will be
015: * searched in multiple resource bundles, starting with the one associated with
016: * this particular class (action in most cases), continuing to try the message
017: * bundle associated with each superclass as well. It will stop once a bundle is
018: * found that contains the given text. This gives a cascading style that allow
019: * global texts to be defined for an application base class.
020: * <p/>
021: * You can override {@link LocaleProvider#getLocale()} to change the behaviour of how
022: * to choose locale for the bundles that are returned. Typically you would
023: * use the {@link LocaleProvider} interface to get the users configured locale.
024: *
025: * @author Jason Carreira
026: * @author Rainer Hermanns
027: * @see LocaleProvider
028: * @see TextProviderSupport
029: */
030: public interface TextProvider {
031:
032: /**
033: * Checks if a message key exists.
034: *
035: * @param key
036: * @return boolean true if key exists, false otherwise.
037: */
038: boolean hasKey(String key);
039:
040: /**
041: * Gets a message based on a message key, or null if no message is found.
042: *
043: * @param key the resource bundle key that is to be searched for
044: * @return the message as found in the resource bundle, or null if none is found.
045: */
046: String getText(String key);
047:
048: /**
049: * Gets a message based on a key, or, if the message is not found, a supplied
050: * default value is returned.
051: *
052: * @param key the resource bundle key that is to be searched for
053: * @param defaultValue the default value which will be returned if no message is found
054: * @return the message as found in the resource bundle, or defaultValue if none is found
055: */
056: String getText(String key, String defaultValue);
057:
058: /**
059: * Gets a message based on a key using the supplied obj, as defined in
060: * {@link java.text.MessageFormat}, or, if the message is not found, a supplied
061: * default value is returned.
062: *
063: * @param key the resource bundle key that is to be searched for
064: * @param defaultValue the default value which will be returned if no message is found
065: * @param obj obj to be used in a {@link java.text.MessageFormat} message
066: * @return the message as found in the resource bundle, or defaultValue if none is found
067: */
068: String getText(String key, String defaultValue, String obj);
069:
070: /**
071: * Gets a message based on a key using the supplied args, as defined in
072: * {@link java.text.MessageFormat}, or null if no message is found.
073: *
074: * @param key the resource bundle key that is to be searched for
075: * @param args a list args to be used in a {@link java.text.MessageFormat} message
076: * @return the message as found in the resource bundle, or null if none is found.
077: */
078: String getText(String key, List args);
079:
080: /**
081: * Gets a message based on a key using the supplied args, as defined in
082: * {@link java.text.MessageFormat}, or null if no message is found.
083: *
084: * @param key the resource bundle key that is to be searched for
085: * @param args an array args to be used in a {@link java.text.MessageFormat} message
086: * @return the message as found in the resource bundle, or null if none is found.
087: */
088: String getText(String key, String[] args);
089:
090: /**
091: * Gets a message based on a key using the supplied args, as defined in
092: * {@link java.text.MessageFormat}, or, if the message is not found, a supplied
093: * default value is returned.
094: *
095: * @param key the resource bundle key that is to be searched for
096: * @param defaultValue the default value which will be returned if no message is found
097: * @param args a list args to be used in a {@link java.text.MessageFormat} message
098: * @return the message as found in the resource bundle, or defaultValue if none is found
099: */
100: String getText(String key, String defaultValue, List args);
101:
102: /**
103: * Gets a message based on a key using the supplied args, as defined in
104: * {@link java.text.MessageFormat}, or, if the message is not found, a supplied
105: * default value is returned.
106: *
107: * @param key the resource bundle key that is to be searched for
108: * @param defaultValue the default value which will be returned if no message is found
109: * @param args an array args to be used in a {@link java.text.MessageFormat} message
110: * @return the message as found in the resource bundle, or defaultValue if none is found
111: */
112: String getText(String key, String defaultValue, String[] args);
113:
114: /**
115: * Gets a message based on a key using the supplied args, as defined in
116: * {@link java.text.MessageFormat}, or, if the message is not found, a supplied
117: * default value is returned. Instead of using the value stack in the ActionContext
118: * this version of the getText() method uses the provided value stack.
119: *
120: * @param key the resource bundle key that is to be searched for
121: * @param defaultValue the default value which will be returned if no message is found
122: * @param args a list args to be used in a {@link java.text.MessageFormat} message
123: * @param stack the value stack to use for finding the text
124: * @return the message as found in the resource bundle, or defaultValue if none is found
125: */
126: String getText(String key, String defaultValue, List args,
127: OgnlValueStack stack);
128:
129: /**
130: * Gets a message based on a key using the supplied args, as defined in
131: * {@link java.text.MessageFormat}, or, if the message is not found, a supplied
132: * default value is returned. Instead of using the value stack in the ActionContext
133: * this version of the getText() method uses the provided value stack.
134: *
135: * @param key the resource bundle key that is to be searched for
136: * @param defaultValue the default value which will be returned if no message is found
137: * @param args an array args to be used in a {@link java.text.MessageFormat} message
138: * @param stack the value stack to use for finding the text
139: * @return the message as found in the resource bundle, or defaultValue if none is found
140: */
141: String getText(String key, String defaultValue, String[] args,
142: OgnlValueStack stack);
143:
144: /**
145: * Get the named bundle, such as "com/acme/Foo".
146: *
147: * @param bundleName the name of the resource bundle, such as "com/acme/Foo"
148: */
149: ResourceBundle getTexts(String bundleName);
150:
151: /**
152: * Get the resource bundle associated with the implementing class (usually an action).
153: */
154: ResourceBundle getTexts();
155: }
|