LocalizationService


1   package org.apache.turbine.services.localization;
2   
3   /*
4    * Copyright 2001-2004 The Apache Software Foundation.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License")
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  import java.util.Locale  ;
20  import java.util.ResourceBundle  ;
21  import javax.servlet.http.HttpServletRequest  ;
22  
23  import org.apache.turbine.services.Service;
24  
25  /**
26   * <p>Provides localization functionality using the interface provided
27   * by <code>ResourceBundle</code>, plus leverages a "search path"
28   * style traversal of the <code>ResourceBundle</code> objects named by
29   * the <code>locale.default.bundles</code> to discover a value for a
30   * given key.</p>
31   *
32   * <p>It is suggested that one handle
33   * <a HREF="http://www.math.fu-berlin.de/~rene/www/java/tutorial/i18n/message/messageFormat.html">dealing with concatenated messages</a>
34   * using <code>MessageFormat</code> and properties files.</p>
35   *
36   * @author <a HREF="mailto:jon@latchkey.com">Jon S. Stevens</a>
37   * @author <a HREF="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
38   * @author <a HREF="mailto:leonardr@collab.net">Leonard Richardson</a>
39   * @version $Id: LocalizationService.java,v 1.8.2.2 2004/05/20 03:06:51 seade Exp $
40   */
41  public interface LocalizationService
42          extends Service
43  {
44      /**
45       * The name of this service.
46       */
47      String   SERVICE_NAME = "LocalizationService";
48  
49      /**
50       * A constant for the HTTP <code>Accept-Language</code> header.
51       */
52      String   ACCEPT_LANGUAGE = "Accept-Language";
53  
54      /**
55       * Retrieves the default language (as specified in the config
56       * file).
57       */
58      String   getDefaultLanguage();
59  
60      /**
61       * Retrieves the default country (as specified in the config
62       * file).
63       */
64      String   getDefaultCountry();
65  
66      /**
67       * Retrieves the name of the default bundle (as specified in the
68       * config file), or the first in the list if there are more than
69       * one.
70       */
71      String   getDefaultBundleName();
72  
73      /**
74       * Retrieves the list of names of bundles to search by default for
75       * <code>ResourceBundle</code> keys (as specified in the config
76       * file).
77       *
78       * @return The list of configured bundle names.
79       */
80      String  [] getBundleNames();
81  
82      /**
83       * Convenience method to get a default ResourceBundle.
84       *
85       * @return A localized ResourceBundle.
86       */
87      ResourceBundle   getBundle();
88  
89      /**
90       * Returns a ResourceBundle given the bundle name and the default
91       * locale information supplied by the configuration.
92       *
93       * @param bundleName Name of bundle.
94       * @return A localized ResourceBundle.
95       */
96      ResourceBundle   getBundle(String   bundleName);
97  
98      /**
99       * Convenience method to get a ResourceBundle based on name and
100      * HTTP Accept-Language header.
101      *
102      * @param bundleName Name of bundle.
103      * @param languageHeader A String with the language header.
104      * @return A localized ResourceBundle.
105      */
106     ResourceBundle   getBundle(String   bundleName, String   languageHeader);
107 
108     /**
109      * Convenience method to get a ResourceBundle based on HTTP
110      * Accept-Language header in HttpServletRequest.
111      *
112      * @param req The HTTP request to parse the
113      * <code>Accept-Language</code> of.
114      * @return A localized ResourceBundle.
115      */
116     ResourceBundle   getBundle(HttpServletRequest   req);
117 
118     /**
119      * Convenience method to get a ResourceBundle based on name and
120      * HTTP Accept-Language header in HttpServletRequest.
121      *
122      * @param bundleName Name of bundle.
123      * @param req The HTTP request to parse the
124      * <code>Accept-Language</code> of.
125      * @return A localized ResourceBundle.
126      */
127     ResourceBundle   getBundle(String   bundleName, HttpServletRequest   req);
128 
129     /**
130      * Convenience method to get a ResourceBundle based on name and
131      * Locale.
132      *
133      * @param bundleName Name of bundle.
134      * @param locale A Locale.
135      * @return A localized ResourceBundle.
136      */
137     ResourceBundle   getBundle(String   bundleName, Locale   locale);
138 
139     /**
140      * Attempts to pull the <code>Accept-Language</code> header out of
141      * the <code>HttpServletRequest</code> object and then parse it.
142      * If the header is not present, it will return a
143      * <code>null</code> <code>Locale</code>.
144      *
145      * @param req The HTTP request to parse the
146      * <code>Accept-Language</code> of.
147      * @return The parsed locale.
148      */
149     Locale   getLocale(HttpServletRequest   req);
150 
151     /**
152      * This method parses the <code>Accept-Language</code> header and
153      * attempts to create a <code>Locale</code> out of it.
154      *
155      * @param languageHeader The <code>Accept-Language</code> HTTP
156      * header.
157      * @return The parsed locale.
158      */
159     Locale   getLocale(String   languageHeader);
160 
161     /**
162      * This method sets the name of the defaultBundle.
163      *
164      * @param defaultBundle Name of default bundle.
165      */
166     void setBundle(String   defaultBundle);
167 
168     /**
169      * Tries very hard to return a value, looking first in the
170      * specified bundle, then searching list of default bundles
171      * (giving precedence to earlier bundles over later bundles).
172      *
173      * @param bundleName Name of the bundle to look in first.
174      * @param locale Locale to get text for.
175      * @param key Name of the text to retrieve.
176      * @return Localized text.
177      */
178     String   getString(String   bundleName, Locale   locale, String   key);
179 
180 }
181
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags