1 chuck 1.5 <!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">
|
2 chuck 1.1 <html>
3 <head>
|
4 chuck 1.5 <meta http-equiv="Content-Type"
5 content="text/html; charset=iso-8859-1">
6 <meta name="GENERATOR"
7 content="Mozilla/4.78 [en] (X11; U; Linux 2.4.7-10 i686) [Netscape]">
|
8 chuck 1.1 </head>
|
9 chuck 1.5 <body text="#000000" bgcolor="#ffffff" link="#0000ef" vlink="#55188a"
10 alink="#ff0000">
11 <center><font size="+4">Globalization HOWTO</font>
12 <p>Release: Pegasus 2.3 </p>
13 <p>Author: Chuck Carmack (carmack@us.ibm.com) </p>
14 <p>July 28, 2003</p>
15 </center>
16 <p><br>
17 </p>
18 <h2> 1.0 Introduction</h2>
19 <p><br>
20 As part of the Pegasus 2.3 release, functions were added for
21 globalization support. Globalization involves two major
22 aspects: internationalization and localization. <br>
23 </p>
24 <p>Internationalization is the process of writing a program that is
25 locale-neutral. In other words, the program should be able to run
26 in any locale without change. There are several categories in a
27 locale, including the language of message strings, date format, time
28 format, etc. For release 2.3, the Pegasus server is concerned
29 with the language of the message strings it returns to its clients. <br>
30 chuck 1.5 </p>
31 <p>To support internationalization, a program is designed to do the
32 following: <br>
33 </p>
34 <blockquote> <li> Support character sets that can represent customer
35 data in any language. Typically, the program supports some
36 variation of Unicode for internal data. There is usually some
37 conversion between the supported character sets for external data, and
38 the internal character set. Since Unicode covers all characters,
39 and usually has converters on the platform, it is a good choice for the
40 'normalized' internal character set. The most
41 'interoperable' solution for external data is to support UTF-8 (eg.
42 network and file system data). The internal data is usually
|
43 chuck 1.1 UTF-16 (or UCS-2, but that is deprecated).</li>
|
44 chuck 1.5 <br>
45 <li> Extract locale-sensitive resources, such as message
46 strings, from the code to external resource files. Typically, the
47 resources are loaded based on the locale requested by the end-user, and
48 returned to the end-user for display.</li>
|
49 chuck 1.1 </blockquote>
|
50 chuck 1.5 <p><br>
51 Localization is the process of customizing a software product to
52 support particular locales. For example, a product that is
53 internationalized might want to only localize for certain
54 countries. This would mean that the localized resources (eg.
55 message files) would only be translated and shipped for the countries
56 that the product supports. Since the code for the product is
57 locale-neutral, it will be easy to drop in new translations as more
58 countries are supported. <br>
59 </p>
|
60 chuck 1.1 <p>The Pegasus 2.3 release added support for globalization. At a
|
61 chuck 1.5 high-level, the following additions were made to Pegasus 2.3: <br>
62 </p>
|
63 chuck 1.1 <ul>
|
64 chuck 1.5 <li> Support UTF-8 for external data.</li>
65 <br>
66
67 <ul>
68 <li> The CIM-XML documents contained in the HTTP messages</li>
69 <li> The files in the repository</li>
70 <li> Note: Pegasus 2.3 does NOT support UTF-8 in the MOF
71 files</li>
72 <br>
73
74 </ul>
75 <li> Support UTF-16 for internal data.</li>
76 <br>
77 <li> Extract the hardcoded messages from the Pegasus code into
78 message files. An API was added to load messages from the message
79 files.</li>
80 <br>
81 <li> APIs were added for clients to associate a language with
82 the CIM objects they are sending to Pegasus. Also, APIs were
83 added for clients to determine the language of the error message or CIM
84 object that Pegasus returns.</li>
85 chuck 1.5 <br>
86 <li> APIs were added for providers to determine the language of
87 CIM objects sent by the client. Also, APIs were added for
88 providers to associate a language with the CIM object, or error
89 message, they return to the client.</li>
|
90 chuck 1.1 </ul>
|
91 chuck 1.5 <p><br>
92 Please refer to PEPs 56 and 58 for details about the globalization
93 design in Pegasus 2.3. <br>
94 </p>
95 <p>This document provides a HOWTO guide to be used by developers to
96 globalize code that is being added to Pegasus. The audience for
97 this document are: <br>
98 </p>
|
99 chuck 1.1 <ul>
|
100 chuck 1.5 <li> Provider developers - both CMPI and C++</li>
101 <li> Client developers</li>
102 <li> Pegasus developers</li>
|
103 chuck 1.1 </ul>
|
104 chuck 1.5 <p><br>
105 The quickest way to approach this document is to read the General
106 section, and then the developer section that relates to what you are
107 doing. <br>
108 </p>
109 <h2> 2.0 General</h2>
|
110 chuck 1.1
|
111 chuck 1.5 <h3> 2.1 Unicode Support</h3>
112 <p><br>
113 Pegasus 2.3 supports Unicode throughout the processing of
114 requests. External data to Pegasus is encoded in UTF-8.
115 Internal data is encoded in UTF-16. <br>
116 </p>
|
117 chuck 1.4 <p>UTF-8 support for external data includes the CIM-XML messages passed
|
118 chuck 1.5 over the network, and the repository files. Note: UTF-8
119 support was NOT added to the MOF Compiler for MOF files in release
120 2.3. For the CIM-XML messages, Pegasus follows section 4.8 of
121 the <a
122 href="http://www.dmtf.org/standards/documents/WBEM/DSP200.html">CIM-HTTP
|
123 chuck 1.1 specification</a> Specifically, Pegasus supports the
124 "utf-8" setting for the charset parameter of the Content-Type header and
125 the XML encoding attribute. If no charset is specified, the 7-bit
|
126 chuck 1.5 ASCII is assumed. <br>
127 </p>
|
128 chuck 1.1 <p>The internal support of UTF-16 is encapsulated in the Pegasus String
|
129 chuck 1.5 class. This class has been updated to contain UTF-16
130 characters. Specifically, the Char16 objects inside the String
131 contain UTF-16 characters. Note: a UTF-16 surrogate pair is
132 contained in two consecutive Char16 objects. To keep backwards
133 compatibilty, the methods on the String class have not changed.
134 New methods have been added as needed. The following describes
135 this in more detail: </p>
|
136 chuck 1.1 <ul>
|
137 chuck 1.5 <li> The Pegasus 2.2 methods that take a char *, or return char *, are
138 unchanged. Code written to Pegasus 2.2 may have expected to store
139 8-bit ASCII (ISO-8859-1) characters into String. These methods
140 will convert the input to UTF-16 from 8-bit ASCII. (This is
141 simple because UTF-16 is a superset of 8-bit ASCII - simply need to
142 prepend '\0' to each char). The Pegasus 2.2 methods that return
143 char data will attempt to convert from the UTF-16 internal
144 representation to 8-bit ASCII. Characters that cannot be
|
145 chuck 1.1 converted will be replaced with a substitution character.</li>
|
146 chuck 1.5 <br>
147 <li> All methods that take or return Char16 data are
148 unchanged. The String class now supports UTF-16 data in Char16,
149 although surrogate pairs will require two consecutive Char16
150 objects. The String class does NO checking for unmatched
151 surrogate pairs.</li>
152 <br>
153 <li> New methods have been added to take and return UTF-8
154 data. The String class will convert between UTF-8 and the UTF-16
155 internal representation as needed. These new methods will use
156 char * parameters, but will be clearly labelled as UTF-8 methods.</li>
157 <br>
158
159 </ul>
160 PROGRAMMING NOTE: Putting EBCDIC data into the String class is
161 dangerous. The String class is designed for UTF-16, which is a
162 superset of 8-bit ASCII. Any String object containing EBCDIC data
163 will not work if it is used by Pegasus to read or write data from
164 external sources, such as the network or repository files. In
165 other words, any String containing EBCDIC data should not leave the
166 code using it. <br>
167 chuck 1.5 <br>
168
169 <h3> 2.2 Localization Support</h3>
|
170 chuck 1.1
|
171 chuck 1.5 <h4> 2.2.1 Language Headers</h4>
172 <p><br>
173 Pegasus 2.3 supports clients and providers that wish to localize.
174 There are two areas to be localized: <a
175 href="http://www.dmtf.org/standards/documents/WBEM/DSP201.html#SecERROR">ERROR</a>
176 elements in the CIM-XML; and <a
177 href="http://www.dmtf.org/standards/documents/WBEM/DSP201.html#SecObjectDefinitionElements">Object
178 Definition</a> elements in the CIM-XML. Clients can
179 request the server to return error messages and CIM objects in a
180 set of languages of their choosing. Clients can also tag a
181 language to the CIM objects they are sending to the server.
182 Providers and the server can return error messages and CIM objects that
183 are tagged with one of languages requested by the client. <br>
184 </p>
185 <p>The localization design is based on section 4.8 of the <a
186 href="http://www.dmtf.org/standards/documents/WBEM/DSP200.html">CIM-HTTP
187 specification</a> , which refers to <a
188 href="http://www.ietf.org/rfc/rfc2616.txt?number=2616">RFC 2616</a>.
189 The method used to tag a language to the CIM-XML is through the
190 Accept-Language and Content-Language HTTP headers. These headers
|
191 chuck 1.1 are basically lists of language tags. An HTTP request can contain
|
192 chuck 1.5 an Accept-Language header, which indicates the list of preferred
193 languages that the client wants in the response. This list can be
194 prioritized by using the quality numbers. An HTTP request or
195 response can contain a Content-Language header, which indicates the
196 language(s) of the content in the message. In the Pegasus case,
197 this would be the CIM-XML. Note that the Content-Language header
198 is a list of language tags. This allows the content of an HTTP
199 message to contain more than one translation. However, in the
200 Pegasus case, there is only one CIM-XML document in the HTTP message,
201 and thus one translation. <br>
202 </p>
203 <p>CIM clients may use the Accept-Language HTTP header to specify the
204 languages they wish to be returned in the CIM response message.
205 CIM clients may also use the Content-Language header to tag the
206 language of any CIM objects they are sending to the server in the CIM
207 request message. The server, and providers, should attempt to
208 return error messages and CIM objects in one of the accept languages
209 requested by the client. The server and providers should set the
210 Content-Language header in the CIM response message to indicate which
211 of the requested languages they are returning. <br>
212 </p>
|
213 chuck 1.1 <p>NOTE: Localization support was not added for the MOF files and
|
214 chuck 1.5 repository in Pegasus 2.3. The #pragma locale, #pragma
215 instancelocale, and translatable qualifier flavor are not supported in
216 the Pegasus 2.3 MOF compiler. From the client perspective,
217 classes, qualifiers, and instances stored in the repository are not
218 tagged with a language. The Accept-Language and Content-Language
219 headers will be ignored for repository operations. However, since
220 the repository will support UTF-8, characters for any language
221 may be stored there. <br>
222 </p>
|
223 chuck 1.1 <p>NOTE: Since the Content-Language header applies to the entire
|
224 chuck 1.5 HTTP message, it applies to the entire CIM-XML document. This
225 includes all the objects in the document, including enumerated objects,
226 and all the values in the objects. This is a limitation that will
227 remain until the CIM standard has been updated to support language tags
228 tied to individual CIM values. From the client perspective, it is
229 possible for Pegasus to send a CIM response with NO Content-Language,
230 even if the client had sent Accept-Language. This can
231 happen if Pegasus does not know the language of the response. An
232 example is a request that was sent to a Pegasus 2.2 provider.
233 Another example is an enumerated response where each provider returned
234 a different language. Please refer to PEP58 for details on these
235 provider scenarios. <br>
236 </p>
237 <p>Pegasus 2.3 has added classes for the localization support.
238 There are new classes called AcceptLanguages and ContentLanguages that
239 encapsulate the Accept-Language and Content-Language headers,
240 respectively. These classes are basically containers of
241 AcceptLanguageElement and ContentLanguageElement, where a language
242 element represents one language tag. The AcceptLanguages class
243 will keep the AcceptLanguageElement's prioritized based on quality,
244 according to RFC 2616. <br>
245 chuck 1.5 </p>
246 <p>AcceptLanguages and ContentLanguages are the objects used by code
247 throughout the request/response processing, from the client to the
248 server to the providers and back. The server handles the creation
249 of these objects from the HTTP headers. Code at each point in the
250 process will have access to these objects. <br>
251 </p>
252 <p>Please refer to the following files for details on the new Pegasus
253 classes. <br>
254 </p>
|
255 chuck 1.1 <ul>
|
256 chuck 1.5 <li> pegasus/src/Pegasus/Common/AcceptLanguages.h</li>
257 <li> pegasus/src/Pegasus/Common/AcceptLanguageElement.h</li>
258 <li> pegasus/src/Pegasus/Common/ContentLanguages.h</li>
259 <li> pegasus/src/Pegasus/Common/ContentLanguageElement.h</li>
260 <li> pegasus/src/Pegasus/Common/LanguageElementContainer.h</li>
261 <li> pegasus/src/Pegasus/Common/LanguageElement.h</li>
|
262 chuck 1.1 </ul>
|
263 chuck 1.5 <p><br>
264 See the sections below for details on how to write clients and
265 providers to use these classes. <br>
266 <br>
267 </p>
268 <h4> 2.2.2 Message Bundles</h4>
269 <p><br>
270 One of the goals of globalization for Pegasus 2.3 is the extraction of
271 hardcoded messages into translated message files, loading
272 translated messages from those files, and returning those messages to
273 the client. The topics to be discussed here are: how to
274 create message files, how to compile message files, and how to load
275 messages into Pegasus. <br>
276 </p>
|
277 chuck 1.1 <p>At the time of writing, the message loading function in Pegasus 2.3
|
278 chuck 1.5 used the International Components for Unicode (<a
279 href="http://oss.software.ibm.com/icu">ICU)</a> libraries. This
280 is expected to be the future direction for Pegasus. <a
281 href="http://oss.software.ibm.com/icu">ICU </a>uses a resource bundle
282 format for their message files. In order to load the
283 messages, ICU requires that the resource bundles are compiled into a
284 binary form (.res file) using their genrb tool. <br>
285 </p>
286 <p>Platform Maintainers Note: Please refer to PEP 58 for
287 information about how to build Pegasus to use the ICU libraries. <br>
288 </p>
289 <p>The documentation for ICU resource bundles is in the <a
290 href="http://oss.software.ibm.com/icu/userguide/ResourceManagement.html">Resource
291 Management</a> section of the <a
292 href="http://oss.software.ibm.com/icu/userguide/">ICU User Guide</a>
293 . This section will tell you how to <br>
294 create and organize your resource bundles for different
295 languages. Note: your resource bundles should be organized
296 in a tree structure similiar to the one shown in the Resource
297 Management section, including the empty bundles in the tree. It
298 is recommended that you ship a root resource bundle to be used as the
299 chuck 1.5 fallback in case the client requests a language that you are not
300 supporting. The Pegasus make files are set up to automatically
301 create and compile a root resource bundle for you. For Pegasus
302 2.3, the make will use your "en" bundle, upper case all the messages,
303 and then put the uppercased messages into the root bundle. The
304 uppercasing of the messages is necessary to create a "fallback" root
305 bundle that contains invariant characters across all EBCIC and
306 ASCII codepages. <br>
307 </p>
308 <p>NOTE: When creating your resource bundles, the name of the
309 table resource should contain the package name. For
310 example, if you have a bundle with a package name of "xyz", then the
311 "en" bundle should start like this: </p>
312 <p>xyz_en:table { <br>
313 ..... messages here <br>
314
315 } <br>
316 </p>
317 <p><i>not</i> like this: </p>
318 <p>en:table { <br>
319 ..... messages here <br>
320 chuck 1.5
321 } </p>
322 <p>This is different than some of the examples in the <a
323 href="http://oss.software.ibm.com/icu/userguide/ResourceManagement.html">Resource
|
324 chuck 1.4 Management</a> section, but is needed because the -p option is not used
|
325 chuck 1.5 on genrb by the make files. <br>
326 </p>
|
327 chuck 1.1 <p>NOTE: Pegasus 2.3 only supports simple string resources in the
|
328 chuck 1.5 ICU resource bundles. String resources may only be loaded by
329 key. Tables, arrays, and other complex resource types, are not
330 supported. <br>
331 </p>
|
332 chuck 1.2 <p>In order to compile your resource bundles, support has been added to
|
333 chuck 1.5 the Pegasus make files to run genrb. A new make target,
334 "messages", has been added that will call genrb and put the compiled
335 bundles (.res) in a directory of your choosing. An example of ICU
336 resource bundles and the make files to compile them are located in: <br>
337 </p>
|
338 chuck 1.2 <ul>
|
339 chuck 1.5 <li> pegasus/src/Providers/sample/LocalizedProvider/Makefile (just
340 causes the make to recurse to the msg sub-directory)</li>
341 <li> pegasus/src/Providers/sample/LocalizedProvider/msg/Makefile
342 (compiles the bundles in the msg/ directory)</li>
343 <li> pegasus/src/Providers/sample/LocalizedProvider/msg/*.txt (the
344 resource bundles to compile, using the recommended ICU language tree
345 structure)</li>
|
346 chuck 1.2 </ul>
|
347 chuck 1.5 <p><br>
348 NOTE: At the time of writing, only the Linux make files have been
349 updated to compile ICU resource bundles. <br>
350 </p>
351 <p>It is important to place the compiled resource bundles in a
352 directory where your code can find them . The make files above
353 compile the resource bundles into
354 $PEGASUS_HOME/msg/provider/localizedProvider. The code that loads
355 these messages uses the MessageLoader class (next section) to load
356 messages from this directory. <br>
357 <br>
358 </p>
359 <h4> 2.2.3 Message Loading</h4>
360 <p><br>
361 Code that needs to load a message in Pegasus does not call ICU
362 directly. Two message loading classes were added for Pegasus
363 2.3: MessageLoader and MessageLoaderParms. These classes
364 are abstractions designed to hide of the actual loader used (but note
365 that at the time of writing, only ICU is supported). The
366 MessageLoader is used to load a message using a list of preferrred
367 languages. The parameters to MessageLoader are encapsulated in a
368 chuck 1.5 MessageLoaderParms object. <br>
369 </p>
370 <p>The MessageLoader is the place where the Accept-Language header,
371 Content-Language header, and the ICU resource bundles, join up.
372 The MessageLoader class is designed to receive an AcceptLanguages
373 object, and a set of parameters indicating the bundle base-name and
374 message ID to use. The AcceptLanguages object contains the list
375 of requested languages sent by the client. The MessageLoader
376 searches for the message in the set of bundles named with the
377 base-name, using the AcceptLanguages for the list of specific
378 translated bundles to search. The MessageLoader returns the
379 message that it found, along with a ContentLanguages object indicating
380 the language of the message. The ContentLanguages object should
381 be used to indicate the language of the response sent back to the
382 client. <br>
383 </p>
384 <p>The MessageLoaderParms object contains the parameters to load the
385 message. There are many parameters, but many can be allowed to
386 default. Here is a description of the parameters: <br>
387 <br>
388
389 chuck 1.5 <table border="1" cols="3" width="100%" nosave="">
390 <tbody>
391 <tr>
392 <td>String msg_id; </td>
393 <td>Input. <br>
394 Required.</td>
395 <td>Message ID of the message to load from the resource
396 bundle. This is the key that ICU will use to load the message.</td>
397 </tr>
398 <tr>
399 <td>String default_msg;</td>
400 <td>Input. <br>
401 Required</td>
402 <td>Message to return if the no message can be loaded for msg_id
403 from any resource bundle. Note: The args parameters below
404 are substituted into this string. <br>
405 Note: For the args into this string, use the Pegasus '$'
406 form, as described in pegasus/src/Pegasus/Common/Formatter.h.
407 Don't use the ICU substitution format for the default message string.</td>
408 </tr>
409 <tr>
410 chuck 1.5 <td>String msg_src_path; </td>
411 <td>Input. <br>
412 Optional <br>
413 Default: $PEGASUS_HOME/msg/pegasus/pegasusServer</td>
414 <td>Path to the root resource bundle file which contains the
415 msg_id. <br>
416 Note: Only specify the path down to the bundle base-name. Do not
417 append a language tag, such as "_root" or "_en". Do not append a
418 file extension. <br>
419 Note: relative paths start at $PEGASUS_HOME/msg. <br>
420 Note: defaults to the bundle containing the Pegasus server messages.</td>
421 </tr>
422 <tr>
423 <td>AcceptLanguages acceptlanguages;</td>
424 <td>Input. <br>
425 Optional <br>
426 Default: AcceptLanguages::EMPTY</td>
427 <td>Contains the list of preferred languages, in priority
428 order. This is combined with msg_src_path to determine which
429 resource bundles to search for for the msg_id. If not
430 empty, overrides useThreadLocale and useProcessLocale.</td>
431 chuck 1.5 </tr>
432 <tr>
433 <td>ContentLanguages contentlanguages;</td>
434 <td>Output</td>
435 <td>Contains the language that MessageLoader found for the
436 msg_id. </td>
437 </tr>
438 <tr>
439 <td>Boolean useProcessLocale;</td>
440 <td>Input <br>
441 Optional <br>
442 Default = false</td>
443 <td>If true, MessageLoader will use the default locale of the
444 process. If true, overrides useThreadLocale.</td>
445 </tr>
446 <tr>
447 <td>Boolean useThreadLocale;</td>
448 <td>Input <br>
449 Optional <br>
450 Default = <font color="#ff0000">true</font></td>
451 <td>If true, MessageLoader will use the AcceptLanguages set by
452 chuck 1.5 Pegasus into the caller's Thread. See the Note below for
453 details. </td>
454 </tr>
455 <tr>
456 <td>Boolean useICUfallback</td>
457 <td>Input <br>
458 Optional <br>
459 Default = false</td>
460 <td>If true, use ICU's fallback mechnism to search more general
461 resource bundles if the msg_id cannot be found. Note: the
462 recommended setting is false if you are using an AcceptLanguages from a
463 CIM client. The Accept-Languages HTTP header from the client
464 contains the fallback specifications.</td>
465 </tr>
466 <tr>
467 <td>Formatter::Arg arg0; <br>
468 Formatter::Arg arg1; <br>
469 Formatter::Arg arg2; <br>
470 Formatter::Arg arg3; <br>
471 Formatter::Arg arg4; <br>
472 Formatter::Arg arg5; <br>
473 chuck 1.5 Formatter::Arg arg6; <br>
474 Formatter::Arg arg7; <br>
475 Formatter::Arg arg8; <br>
476 Formatter::Arg arg9;</td>
477 <td>Input <br>
478 Optional <br>
479 Default: Formatter::Arg( ) // empty arg</td>
480 <td>These are the substitution variables, using the Pegasus
481 Formatter::Arg class.</td>
482 </tr>
483 </tbody>
|
484 chuck 1.1 </table>
|
485 chuck 1.5 </p>
486 <p>Notes: <br>
487 </p>
488 <p>The "useThreadLocale" parameter defaults to true. This flag
489 indicates to use the AcceptLanguages object set by Pegasus into the
490 Pegasus Thread in which the caller's code is running. This
491 AcceptLanguages object reflects the languages requested by the
492 client. This is useful for code that may not have access to the
493 AcceptLanguages from the client. Pegasus sets this
494 AcceptLanguages object into the Thread of providers and internal
495 Pegasus code. For this reason, it is recommended that provider
496 and internal Pegasus code use the "useThreadLocale" flag instead of
497 explicity passing in an AcceptLanguages object. See the Provider
498 Developer and Pegasus Developer sections for details. <br>
499 </p>
|
500 chuck 1.2 <p>The "useProcessLocale" flag can be used to tell MessageLoader to use
501 the default locale of the process, as determined by ICU. This is
|
502 chuck 1.5 useful for situations where the caller is not localizing for a client
503 request. The caller may itself be a client (eg. cimconfig), or
504 may need to log messages to the system log in the locale of the Pegasus
505 server process. See the CLI Messages and Logger Messages sections
506 below. <br>
507 </p>
508 <p>"Master switch" <br>
509 The MessageLoader class has a public static Boolean variable called
|
510 chuck 1.2 _useProcessLocale that may be used to override all the AcceptLanguages
|
511 chuck 1.5 and useThreadLocale settings in the MessageLoaderParms objects passed
512 in. This is useful for CLI code (eg cimconfig) that needs to
513 localize its messages based on the locale of its process, which refects
514 the locale set by the user running the CLI (eg. $LANG on Unix).
515 The CLI code may call Pegasus APIs that are coded to use the Thread's
516 AcceptLanguages, which will not be set in this case. The
517 _useProcessLocale static variable tells the MessageLoader to ignore the
518 AcceptLanguages, useThreadLocale, and useProcessLocale settings in
519 MessageLoaderParms that it gets. The MessageLoader will use the
520 default process locale, as determined by ICU, in this case. <br>
521 </p>
|
522 chuck 1.2 <p><i>Important Note:</i> The MessageLoader defaults to <i>not </i>use
|
523 chuck 1.5 the "fallback" mechanism described in the ICU Resource Management
524 section. This is because the Accept-Language header itself
525 describes the fallback that the client wants. However, the
526 MessageLoader does "fallback" to the root resource bundle if none of
527 the languages in AcceptLanguages can be found. If the root
528 resource bundle cannot be found, then the default_msg is
529 returned. The "useICUFallback" flag can be set to have
530 MessageLoader use ICU fallback on all message load attempts.
531 However, usage of this flag for client requests may lead to incorrect
532 results. For example, a client sets Accept-Language to french,
533 german, and spanish, in that order, but there is no french resource
534 bundle. A call to MessageLoader with useICUfallback == true would
535 cause the root resource bundle string to be returned on the attempt to
536 load from the french bundle. But the client requested german to
537 be the fallback after french. <br>
538 </p>
539 <p>Please refer to the following files for details on the new Pegasus
540 classes. <br>
541 </p>
|
542 chuck 1.1 <ul>
|
543 chuck 1.5 <li> pegasus/src/Pegasus/Common/MessageLoader.h</li>
|
544 chuck 1.1 </ul>
|
545 chuck 1.5 <h4> 2.2.4 Message Loading Example</h4>
546 <p><br>
547 The following example shows how a message may be loaded using the
|
548 chuck 1.2 classes described above. Note: this a generic example. Each
|
549 chuck 1.5 of the developer sections below have 'real-life' examples that are
550 better suited to each type of code. </p>
551 <p>// Build an AcceptLanguages with some language elements <br>
552 AcceptLanguages acceptLangs; <br>
553 acceptLangs.add(AcceptLanguageElement("fr", 0.5)); <br>
554 acceptLangs.add(AcceptLanguageElement("de", 0.8)); <br>
555 acceptLangs.add(AcceptLanguageElement("es", 0.4)); </p>
556 <p>// Construct a MessageLoaderParms <br>
557 MessageLoaderParms parms("msgID", "default message"); <br>
558 parms. msg_src_path = "/my_msg_dir/my_bundle"; <br>
559 parms.acceptlanguages = acceptLangs; </p>
560 <p>// Note: If you have args, set them into MessageLoaderParms </p>
561 <p>// Load the localized String <br>
562 String localizedMsg = MessageLoader::getMessage(parms); <br>
563 <br>
564 </p>
565 <h4> 2.2.4 Message Writing Guidelines</h4>
566 <p><br>
567 Here are some basic rules for writing messages: <br>
568 </p>
|
569 chuck 1.1 <ul>
|
570 chuck 1.5 <li> If you want to claim that you are globalized, no hardcoded
571 messages!</li>
572 <li> Avoid combining messages in the code from other messages.
573 When you do this you are assuming that you know the grammar for every
574 language.</li>
575 <li> String substitutions into messages are generally untranslated,
576 ie. not loaded from the resource bundle. Example: a file
577 name.</li>
578 <li> Avoid jargon, humour, and cultural idioms. Use full
579 sentences. Have your messages reviewed by your globalization
580 team. Your messages need to make sense to the translators, and
581 ultimately the customer.</li>
582 <li> <b>TODO </b>- find a good message writing guide to link to</li>
|
583 chuck 1.1 </ul>
|
584 chuck 1.5 <h4> 2.2.5 Localized Exceptions</h4>
585 <p><br>
586 The base Exception class, and derived classes, have been updated to
587 support localization. Constructors have been added that take a
588 MessageLoaderParms object. These constructors will use the
589 MessageLoaderParms object to call the MessageLoader to load the
590 localized exception message. The localized message is saved in
591 the Exception. The ContentLanguages object returned by
592 MessageLoader is also saved in the Exception. This indicates the
593 language of the message. The ContentLanguages object is used
594 later to set the Content-Language header in the HTTP message to the
595 client. <br>
596 </p>
|
597 chuck 1.2 <p>The old Exception constructors that take a String will remain.
598 These should be used in cases where the code throwing the exception is
|
599 chuck 1.5 not localized, or the String is not localized (for example, a file
600 name). Also, there are several exceptions in Pegasus where the
601 String parameter is meant to be a non-localized substitution in a
602 localized message owned by the Exception (see InternalException.h,
603 ClassNotResolved for an example). The old constructors for these
604 have been kept. <br>
605 <br>
606 </p>
607 <h2> 3.0 Provider Developers</h2>
|
608 chuck 1.1
|
609 chuck 1.5 <h3> 3.1 Design Issues</h3>
610 <p><br>
611 Providers that wish to globalize should consider the following in their
612 design: <br>
613 </p>
|
614 chuck 1.1 <ul>
|
615 chuck 1.5 <li> Are there localized string properties that need to be
616 supported? If so, then the client will use Accept-Language to
617 request specific languages for these properties. If the
618 properties are read-only, use MessageLoader to load the localized
619 strings for the properties.</li>
620 <li> If you have a localized read/write string property, then the
621 client will use Content-Language to set the property with an associated
622 language. The client will expect to be able to retrieve the
623 property in that same language later (using Accept-Language).</li>
624 <li> Note: only the string property types in CIM are candidates for
625 localization. The other types, including datetime, are
626 locale-neutral.</li>
627 <li> Are there error messages that need to returned to the client in
628 different languages? The client will use Accept-Language to
629 request specific languages for the error messages.</li>
630 <li> What resource bundle translations, if any, will be shipped with
631 the provider?</li>
632 <li> Do any codepage conversions need to be done between the UTF-16
633 characters in the String objects and the codepage of data stored on the
634 system? This is a concern for EBCDIC platforms. All EBCDIC
635 data needs to be converted to at least 7-bit ASCII before it is passed
636 chuck 1.5 into the String object.</li>
|
637 chuck 1.1 </ul>
|
638 chuck 1.5 <p><br>
639 To help providers handle the situations described above, Pegasus 2.3
640 will pass the Accept-Language received from the client to the
641 provider. The provider should load strings from its resource
642 bundle based on the client's Accept-Language. The client's
643 Accept-Language is passed to the provider in two ways: <br>
644 </p>
|
645 chuck 1.1 <ul>
|
646 chuck 1.5 <li> Pegasus will set the Accept-Language from the client into the
647 thread in which the provider is running. By using the
648 useThreadLocale setting in MessageLoaderParms, providers can easily
649 load strings using the client's requested Accept-Language. The
650 provider does not need to know what the Accept-Language is. This
651 is the recommended method to load messages based on the client's
652 request.</li>
653 <br>
654 <li> The OperationContext will contain an AcceptLanguages object
655 that has the Accept-Language requested by the client. The
656 provider can use this AcceptLanguages object to load strings with
657 MessageLoader.</li>
|
658 chuck 1.1 </ul>
|
659 chuck 1.5 <p><br>
660 The OperationContext will also contain a ContentLanguages object that
661 is set from the Content-Language in the client request. This is
662 the language of the CIM objects being passed to the provider on that
663 request. A localized provider should store the content language
664 along with the data from the CIM objects. This will allow the
665 client to use Accept-Language later to retreive the data in that
666 language. <br>
667 </p>
668 <p>The provider should indicate the language of CIM objects it is
669 returning by calling setContext( ) on the ResponseHandler. This
670 will be used to set the Content-Language in the CIM response message
671 sent back to the client. If setContext( ) is not called, then no
672 Content-Language will be returned to the client. setContext( )
673 should only be called once per response. <br>
674 </p>
675 <h3> 3.2 Sample Code</h3>
676 <p><br>
677 The following sample code shows a localized getInstance( ) where the
678 instance returned is localized based on the Accept-Language of the
679 client request. Note that this example also throws a localized
680 chuck 1.5 exception. <br>
681 </p>
682 <p>void LocalizedProvider::getInstance( <br>
683 const OperationContext & context, <br>
684 const CIMObjectPath & instanceReference, <br>
685 const Boolean includeQualifiers, <br>
686 const Boolean includeClassOrigin, <br>
687 const CIMPropertyList & propertyList, <br>
688 InstanceResponseHandler & handler) <br>
689 { <br>
690 // convert a potential fully qualified
691 reference into a local reference <br>
692 // (class name and keys only). <br>
693 CIMObjectPath localReference = CIMObjectPath( <br>
694 String(), <br>
695 String(), <br>
696
697 instanceReference.getClassName(), <br>
698
699 instanceReference.getKeyBindings()); </p>
700 <p> // begin processing the request <br>
701 chuck 1.5 handler.processing(); </p>
702 <p> // Find the instance to be returned. <br>
703 Uint32 i; <br>
704 Uint32 n = _instances.size(); <br>
705 for (i = 0; i < n; i++) <br>
706 { <br>
707
708 if(localReference == _instanceNames[i]) <br>
709 { <br>
710
711 // We found the instance to return </p>
|
712 chuck 1.1 <p>
|
713 chuck 1.5 // Build the parameters for loading the localized string property. <br>
714
715 // We are going to let the message loader parameters default to use the <br>
716
717 // AcceptLanguages that Pegasus set into our thread. <br>
718
719 // (this equals the AcceptLanguages requested by the client) <br>
720
721 // Note: This parms object could be constructed once and <br>
722
723 // reused. <br>
724
725 MessageLoaderParms parms("myMsgID", "myDefaultString"); <br>
726
727 parms.msg_src_path = "/myprovider/msg/myResourceBundle"; </p>
|
728 chuck 1.1 <p>
|
729 chuck 1.5 // Load the string for the localized property from the resource bundle <br>
730
731 String localizedString = MessageLoader::getMessage(parms); </p>
|
732 chuck 1.1 <p>
|
733 chuck 1.5 // Remove the old property from the instance to be returned <br>
734
735 Uint32 index = instances[i].findProperty("myProperty"); <br>
736
737 if (index != PEG_NOT_FOUND) <br>
738
739 { <br>
740
741 _instances[i].removeProperty(index); <br>
742
743 } </p>
|
744 chuck 1.1 <p>
|
745 chuck 1.5 // Add the localized string property to the instance <br>
746
747 instances[i].addProperty(CIMProperty("myProperty", localizedString)); </p>
|
748 chuck 1.1 <p>
|
749 chuck 1.5 // The MessageLoader set the contentlanguages member <br>
750
751 // of parms to the language that it found for the message. <br>
752
753 ContentLanguages rtnLangs = parms.contentlanguages; </p>
|
754 chuck 1.1 <p>
|
755 chuck 1.5 // We need to tag the instance we are returning with the <br>
756 // the
757 content language. <br>
758
759 OperationContext context;<br>
760
761 context.insert(ContentLanguageListContainer(rtnLangs));<br>
762
763 handler.setContext(context);<br>
764 </p>
765
766 // deliver requested instance<br>
767
|
768 chuck 1.1 handler.deliver(_instances[i]);
769 <p>
|
770 chuck 1.5 break; <br>
771
772 } // end if <br>
773
774 } //
775 end for </p>
|
776 chuck 1.1 <p> // throw an exception if
|
777 chuck 1.5 the instance wasn't found <br>
778 if (i == n) <br>
779 { <br>
780
781 // Build the parameters for loading the localized error message. <br>
782
783 // We are going to let the message loader parameters default to use the <br>
784
785 // AcceptLanguages that Pegasus set into our thread. <br>
786
787 // (this equals the AcceptLanguages requested by the client) <br>
788
789 // Note: This parms object could be constructed once and <br>
790
791 // reused. <br>
792
793 MessageLoaderParms errParms("myErrorMsgID", "myErrorDefaultString"); <br>
794
795 errParms.msg_src_path = "/myprovider/msg/myResourceBundle"; </p>
|
796 chuck 1.1 <p>
|
797 chuck 1.5 // Note: the exception calls MessageLoader::getMessage( ) <br>
798
799 // Note: no need to call handler.setContext( ) in this case <br>
800
801 throw CIMObjectNotFoundException(errParms); <br>
802 } <br>
803 </p>
804 <p> // complete processing
805 the request <br>
806 handler.complete(); <br>
807 } <br>
808 </p>
|
809 chuck 1.1 <p>NOTE: A sample provider has been written that fully demonstates the
|
810 chuck 1.5 design issues described above. This provider is located at: <br>
811 </p>
|
812 chuck 1.1 <ul>
|
813 chuck 1.5 <li> pegasus/src/Providers/sample/LocalizedProvider/</li>
|
814 chuck 1.1 </ul>
|
815 chuck 1.5 <p><br>
816 This sample provider also demonstrates how some of the special issues
817 can be handled. The special issues are caused by having a
818 read/only localized property and a read/write localized property.
819 What happens if the client sets the read/write property with a
820 Content-Language that is not one of the supported languages for the
821 read/only property? This provider allows the client to set any
822 language into the read/write property, and get that property back in
823 the same language. This becomes an issue when the client does a
824 getInstance( ) later, because the Content-Language on the returned
825 instance applies to all the properties. A related issue is what
826 to return for Content-Language when the client does enumerateInstances,
827 but the instances have different languages. Recall that
828 Content-Language applies to the entire response (a limitation in the
829 CIM specification). <br>
830 </p>
831 <p>NOTE: Indication Providers have other special considerations
832 for language support. Please refer to PEP58. <br>
833 </p>
834 <p>NOTE: The CMPI interface has been updated for language
835 support. Please refer to the CMPI documentation for details. <br>
836 chuck 1.5 </p>
837 <p>NOTE: SPECIAL ISSUES FOR OS/400 PROVIDERS: </p>
|
838 chuck 1.1 <ul>
|
839 chuck 1.5 <li> Convert between UTF-16 in the String objects and EBCDIC system
840 data as needed. The converters in
841 Pegasus/Common/OS400ConvertChar.h may be used to convert between EBCDIC
842 CCSID 37 and ASCII CCSID 819 (a subset of UTF-16).</li>
843 <li> The Pegasus program, and all bound service programs, will
844 run in a UTF-8 locale even though the job CCSID is 37. The
845 C-runtime library (printf, fopen, isalpha, strcmp, etc) will expect
846 UTF-8, or at least 7-bit ASCII, characters.</li>
847 <li> Consideration should be given to the codepage for the compiled
848 string literals. Use #pragma convert as needed. But,
849 remember that the C-runtime will expect UTF-8.</li>
850 <li> For more details, refer to "Unicode support" in chapter 3 of the <u>ILE
|
851 chuck 1.1 C/C++ for iSeries Run-Time Functions, Version 5</u> publication for V5R3
852 (SC41-5607-02). The Pegasus string literals will be compiled with
|
853 chuck 1.5 the UTF-8 compile switch described in this section. OS/400
854 provider developers should strongly consider using the same compile
855 switch for their string literals. This would allow the literals
856 to match the UTF-8 encoding expected by the C-runtime.</li>
|
857 chuck 1.1 </ul>
|
858 chuck 1.5 <h2> 4. 0 Client Developers</h2>
859 <p><br>
860 Methods have been added to CIMClient to set the Accept-Language and
861 Content-Language on the request, and retrieve Content-Language on the
862 response. The language tags in the Accept-Language header must
863 meet the ISO-639 and ISO-3166 standards. <br>
864 </p>
865 <p>Please refer to <br>
866 </p>
|
867 chuck 1.1 <ul>
|
868 chuck 1.5 <li> pegasus/src/Pegasus/Client/CIMClient.h</li>
869 <br>
870
871 </ul>
872 for the new methods on CIMClient. <br>
873
874 <p>Here is a code fragment that uses the new methods on CIMClient </p>
875 <p> // <br>
876 // Get a localized instance in French <br>
877 // </p>
878 <p> // Language priority is martian, pig-latin, and
879 french. We should <br>
880 // get french back, even though its the lowest priority <br>
881 AcceptLanguages acceptLangs; <br>
882 acceptLangs.add(AcceptLanguageElement("x-martian")); <br>
883 acceptLangs.add(AcceptLanguageElement("fr", 0.1)); <br>
884 acceptLangs.add(AcceptLanguageElement("x-pig-latin", 0.4)); </p>
885 <p> // Set the requested languages into the CIMClient <br>
886 client.setRequestAcceptLanguages(acceptLangs); </p>
887 <p> // Get the instance <br>
888 CIMInstance instance = client.getInstance( <br>
889 chuck 1.5 NAMESPACE, <br>
890 cimNInstances[0].buildPath(sampleClass), <br>
891 localOnly, <br>
892 includeQualifiers, <br>
893 includeClassOrigin); </p>
894 <p> // Get the string property that should be french <br>
895 String returnedString; <br>
896 instance.getProperty ( <br>
897 instance.findProperty("myProp")). <br>
898
899 getValue(). <br>
900
901 get(returnedString); </p>
902 <p> // Check that we got back french <br>
903 ContentLanguages CL_FR("fr"); <br>
904 String expectedFRString = "oui"; <br>
905 PEGASUS_ASSERT(CL_FR == client.getResponseContentLanguages()); <br>
906 PEGASUS_ASSERT(expectedFRString == returnedString); </p>
907 <p> // <br>
908 // Create an instance in French <br>
909 // </p>
910 chuck 1.5 <p> String oui = "Oui"; <br>
911 CIMInstance frInstance(CLASSNAME); <br>
912 frInstance.addProperty(CIMProperty( <br>
913
914 CIMName("myProp"), <br>
915
916 oui)); </p>
917 <p> CIMObjectPath frInstanceName =
918 frInstance.buildPath(sampleClass); </p>
919 <p> client.setRequestContentLanguages(CL_FR); </p>
920 <p> client.createInstance(NAMESPACE, frInstance); <br>
921 <br>
922 <br>
923 </p>
924 <p>Also, refer to </p>
|
925 chuck 1.1 <ul>
|
926 chuck 1.5 <li> pegasus/src/Clients/g11ntest/</li>
|
927 chuck 1.1 </ul>
|
928 chuck 1.5 for more examples of a client that uses Accept-Language and
929 Content-Language. <br>
930
|
931 chuck 1.1 <p>NOTE: Consideration should be given for converting the UTF-16
932 characters in the String objects passed over the CIMClient interface to
|
933 chuck 1.5 a platform codepage. This is especially needed for EBCDIC
934 platforms. See the Provider developer section for details of the
935 EBCDIC considerations. <br>
936 <br>
937 </p>
938 <h3> 4.1 Default Process Locale</h3>
939 <p><br>
940 A method has been added to CIMClient to set the Accept-Language for the
941 requests based on the default locale of the process, as determined by
942 ICU. If ICU is installed on the client system then CIMClient will
943 set the Accept-Language from the default ICU process locale. If
944 ICU is not installed then the caller is required to set an
945 AcceptLanguages into CIMClient that meets the ISO-639 and IS0-3166
946 standards. Note: this is useful for local clients, such as
947 the Pegasus CLIs, where ICU would be installed on both the client and
948 server sides. <br>
949 <br>
950 </p>
951 <h2> 5. 0 Pegasus Developers</h2>
952 <p><br>
953 The design for Pegasus releases beyond 2.3 is to avoid using hardcoded
954 chuck 1.5 messages. All new messages should be loaded from a Pegasus
955 resource bundle. This section describes the process to follow if
956 you are creating a new message. The process depends on where you
957 are in the code. <br>
958 <br>
959 </p>
960 <h3> <b>5.1 Pegasus Resource Bundles</b></h3>
961 <p><br>
962 Place any new Pegasus messages into one of the following resource
963 bundles: <br>
964 </p>
|
965 chuck 1.1 <ul>
|
966 chuck 1.5 <li> pegasus/src/Pegasus/msg/Server/pegasusServer_*.txt for
967 server and MOF compiler (cimmof, cimmofl) messages</li>
968 <li> pegasus/src/Pegasus/msg/CLI/pegasusCLI_*.txt for all CLI messages
969 (except the MOF compiler)</li>
|
970 chuck 1.1 </ul>
|
971 chuck 1.5 <p><br>
972 The make messages target will compile these resource bundles. </p>
973 <p>Note: As described above, the resource bundle path in
974 MessageLoaderParms defaults to the server resource bundle. For
975 CLI messages, you will need to specify the bundle for your CLI. <br>
976 </p>
977 <h3> 5.2 Server Messages</h3>
978 <p><br>
979 For messages returned from one of the services in the Pegasus server
|
980 chuck 1.1 (eg. CIMOperationRequestDispatcher, or ProviderManagerService), the goal
981 is to make it easy for any code in the call chain to throw an exception
|
982 chuck 1.5 with a localized error string. The code throwing the exception
983 will not need to know the Accept-Language that the client
984 requested. To understand how this works, some design points need
985 to described: <br>
986 </p>
987 <p><b>Server Design Points:</b> <br>
988 </p>
989 <p>The CIMMessage object has been expanded to include an
990 AcceptLanguages object and a ContentLanguages object. For
991 CIMRequestMessage, these objects contain the Accept-Language and
992 Content-Language headers that were built from the client request.
993 For CIMResponseMessage, the ContentLanguages object is used to build
994 the Content-Language header associated with the CIM <i>objects </i>in
995 the response message. The AcceptLanguages object in the
996 CIMResponseMessage is ignored. <br>
997 </p>
998 <p>The localization of the cimException object in the
999 CIMResponseMessage is handled separately from the CIM objects.
1000 The message string in the cimException object is assumed to have been
1001 localized by the time it is built into the XML. For this reason,
1002 the localization of the exception is the responsibility of the code
1003 chuck 1.5 throwing the exception. (The goal of the design is to make that
1004 easy - see below). The ContentLanguages object in the
1005 CIMResponseMessage has NO relation to this exception. The
1006 cimException object keeps its own localization information once it is
1007 created. <br>
1008 </p>
|
1009 chuck 1.1 <p>To enable exceptions to be localized, the ability was added to set a
|
1010 chuck 1.5 global language for all the code running from a Pegasus Thread
1011 object. The top level code for a Thread can set a global
1012 AcceptLanguages object that can be accessed by all the low-level
1013 functions that it calls. This will allow an exception thrown by
1014 the low-level function to be localized based on this global
1015 AcceptLanguages object. Note: This applies only to Threads
1016 that are managed by a ThreadPool. <br>
1017 </p>
1018 <p>Each service in the request path of the Pegasus server sets the
1019 AcceptLanguages into its Thread from the AcceptLanguages in the
1020 CIMRequestMessage object that it dequeues. This sets the global
1021 langauge for all the functions in the same thread that are called below
1022 handleEnqueue. <i>If you are writing a new service that
1023 processes requests, or discover a request service that was missed,
1024 please do this. </i> The CIMOperationRequestDispatcher service is
1025 an example. <br>
1026 </p>
1027 <p><b>How to Throw a Localized Exception from Server code:</b> <br>
1028 </p>
1029 <p>With all that background, here is how code running in a Pegasus
1030 service can throw a localized exception: <br>
1031 chuck 1.5 This example assumes that the top-level code in the service had set the
1032 global thread AcceptLanguages beforehand. As described above,
1033 every service in Pegasus should do that. The code here may be
1034 buried several layers deep in the call chain, but does not need to know
1035 the AcceptLanguage of the current client request. </p>
1036 <p>// First, construct a MessageLoaderParms <br>
1037 // <br>
1038 // Notes: <br>
1039 // 1) The errorMessageID must be in the Pegasus server resource
1040 bundle. <br>
1041 // 2) The default message is the old "hardcoded" message. <br>
1042 // 3) The MessageLoaderParms will default to use the Pegasus
1043 server resource bundle <br>
1044 // 4) The MessageLoaderParms will default to use the
1045 AcceptLanguages set into the current Thread. Don't change this! <br>
1046 // 5) You might need to set the arguments for the message into
1047 the MessageLoaderParms <br>
1048 MessageLoaderParms parms("errorMessageID", "default message"); </p>
1049 <p>// Second, throw the Exception <br>
1050 // Note: this applies to all the derived classes from Exception,
1051 including the CIMException's <br>
1052 chuck 1.5 throw new Exception(parms); <br>
1053 </p>
|
1054 chuck 1.1 <p>NOTE: If you are throwing an Exception with un-localized data,
1055 use the constructor that takes a String. An example of this would
1056 be an Exception where you are passing in a file name. Most of the
1057 "non-CIM" exceptions defined in Exception.h and InternalException.h take
|
1058 chuck 1.5 un-localized data. <br>
1059 </p>
1060 <p><b>The Exception Macros</b> <br>
1061 </p>
1062 <p>There are many spots in the server code that use the
1063 PEGASUS_CIM_EXCEPTION macro to throw a TraceableCIMException. The
1064 use of this macro in the code like the following example presented a
1065 design problem: </p>
1066 <p>.... <br>
1067 } catch (Exception & e) <br>
1068 { <br>
1069 throw PEGASUS_CIM_EXCEPTION(CIM_ERR_FAILED,
1070 e.getMessage()); <br>
1071 } <br>
1072 </p>
|
1073 chuck 1.2 <p>This type of code would have lost the ContentLanguages saved in "e",
|
1074 chuck 1.5 so that the Content-Language would not be set in HTTP response to the
1075 client. <br>
1076 </p>
1077 <p>For Pegasus 2.3, these types of macro calls can stay. The
1078 TraceableCIMException constructed by the macro will
1079 "re-localize". That is, the "CIM" part of the message (the part
1080 based on the error code) will be localized at throw time, and the
1081 ContentLanguages re-established. A key is to avoid a "language
1082 mismatch" problem between the CIM part of the message and the extra
1083 part of the message. The design point here is that all internal
1084 exceptions thrown by Pegasus code are localized using the global
1085 AcceptLanguages of the Thread...see above. <br>
1086 </p>
1087 <p>In the future, it will be safer and more maintainable to use of
1088 the new "localized" flavors of the macro. For example: <br>
1089 </p>
1090 <p>When the message from a caught Exception needs to be become
1091 the extra message in a thrown CIMException: </p>
1092 <p>.... <br>
1093 } catch (Exception & e) <br>
1094 { <br>
1095 chuck 1.5 throw
1096 PEGASUS_CIM_EXCEPTION_LANG(e.getContentLanguages( ), <br>
1097
1098 CIM_ERR_FAILED, <br>
1099
1100 e.getMessage( )); <br>
1101 } <br>
1102 </p>
1103 <p>This guarantees that the ContentLanguages in "e" is copied to the
1104 newly created TraceableCIMException. <br>
1105 </p>
1106 <p>In the case where the extra message for the CIMException is
1107 determined by the throwing code: <br>
1108 </p>
1109 <p>throw PEGASUS_CIM_EXCEPTION_L(CIM_ERR_FAILED, <br>
1110
1111 MessageLoaderParms("Repository.CIMRepository.COMPACT_FAILED",
1112 "compact failed")); <br>
1113 </p>
1114 <p>(example from CIMRepository.cpp) <br>
1115 This uses a MessageLoaderParms object to localize the extra message in
1116 chuck 1.5 the newly created TraceableCIMException. <br>
1117 </p>
1118 <h3> 5.2 Logger Messages</h3>
1119 <p><br>
1120 New methods have been added to Logger to take a message ID of a message
1121 to be loaded from the Pegasus server resource bundle. The caller
1122 is only required to pass in the message ID, the old "hardcoded"
|
1123 chuck 1.1 message, and the args. The Logger will use MessageLoader to load
|
1124 chuck 1.5 the message in the locale of the Pegasus server <i>process</i>, using
1125 the hardcoded message as the default string. Please refer to
1126 pegasus/src/Pegasus/Logger.h. </p>
|
1127 chuck 1.2 <p>Note: Messages sent to the "logs", whether the system logs or
|
1128 chuck 1.5 the Pegasus log file, are converted to UTF-8 before being sent. <br>
1129 </p>
1130 <h3> 5.3 CLI Messages</h3>
1131 <p><br>
1132 The goal for messages returned by the Pegasus CLIs is to localize in
1133 the locale of the user running the CLI. This should be automatic
1134 -- the user should not be required to tell the CLI what the locale
1135 is. For the CLIs that are CIM clients (cimconfing,
1136 cimprovider) there are two sets of messages to localize --
1137 messages generated in the CLI process itself, and messages returned
1138 from the Pegasus server . For CLIs that are directly linked into
1139 Pegasus (cimmofl), all the messages are generated in the CLI's process,
1140 but the CLI may call Pegasus APIs that are coded to localize based on a
1141 client's requested languages. <br>
1142 </p>
1143 <p>Code in the client side of the client/server CLIs (eg. cimconfig,
1144 cimmof), or in directly linked CLIs (cimmofl), should use the
1145 _useProcessLocale "master switch" described in the Message Loading
1146 section. This will cause all messages, including exceptions
1147 thrown by Pegasus APIs, to be loaded in the locale based on the
1148 environment in which the program is running. This locale can be
1149 chuck 1.5 set by the user before running the program. <br>
1150 </p>
1151 <p>Code in the client side of the client/server CLIs need to send an
1152 Accept-Language to the Pegasus server that reflects the default locale
1153 of the CLI's process. See the Client Developer section for
1154 details. <br>
1155 </p>
1156 <p>An example of these considerations can be seen in the source code
1157 for cimconfig. <br>
1158 </p>
1159 <p> </p>
|
1160 chuck 1.1 <hr>
|
1161 chuck 1.5 <p><i>Copyright (c) 2003 BMC Software; Hewlett-Packard Development
1162 Company, L.P.; IBM Corp.; The Open Group</i> </p>
1163 <p><i>Permission is hereby granted, free of charge, to any person
1164 obtaining a copy of this software and associated documentation
1165 files (the "Software"), to deal in the Software without restriction,
1166 including without limitation the rights to use, copy, modify, merge,
1167 publish, distribute, sublicense, and/or sell copies of the Software,
1168 and to permit persons to whom the Software is furnished to do so,
1169 subject to the following conditions:</i> </p>
1170 <p><i>THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE
1171 INCLUDED IN ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE
1172 SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
1173 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
1174 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
1175 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
1176 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
1177 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
1178 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</i> <br>
1179 <br>
1180 </p>
|
1181 chuck 1.1 </body>
1182 </html>
|
Return to
Globalization_HOWTO.htm
CVS log
Up to [Pegasus] / pegasus / doc