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