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