An internationalized connector is a connector that has been written so that it can be customized for a particular locale. A locale is the part of a user's environment that brings together information about how to handle data that is specific to the end user's particular country, language, or territory. The locale is typically installed as part of the operating system. Creating a connector that handles locale-sensitive data is called the internationalization (I18N) of the connector. Preparing an internationalized connector for a particular locale is called the localization (L10N) of the connector.
This section provides the following information on an internationalized connector:
A locale provides the following information for the user environment:
A locale name has the following format:
ll_TT.codeset
wherell is a two-character language code (usually in lower case), TT is a two-letter country and territory code (usually in upper case), and codeset is the name of the associated character code set. The codeset portion of the name is often optional. The locale is typically installed as part of the installation of the operating system.
This section provides the following categories of design considerations for internationalizing a connector:
To be internationalized, a connector must be coded to be locale-sensitive; that is, its behavior must take the locale setting into consideration and perform the task appropriate to that locale. For example, for locales that use English, the connector should obtain its error messages from an English-language message file. The WebSphere Business Integration Adapters product provides you with an internationalized version of the connector framework. To complete the internationalization (I18N) of a connector you develop, you must ensure that your application-specific component is internationalized.
Table 15 lists the locale-sensitive design principles that an internationalized application-specific component must follow.
Table 15. Locale-sensitive design principles for application-specific components
Design principle | For more information |
---|---|
The text of all error, status, and trace messages should be isolated from the application-specific component in a message file and translated into the language of the locale. | Text strings |
The locale of a business object must be preserved during execution of the connector. | Business object locales |
Properties of connector configuration properties must be handled to include possible inclusion of multibyte characters. | Connector configuration properties |
Other locale-specific tasks must be considered. | Other locale-sensitive tasks |
It is good programming practice to design a connector so that it refers to an external message file when it needs to obtain text strings rather than hardcoding text strings in the connector code. When a connector needs to generate a text message, it retrieves the appropriate message by its message number from the message file. Once all messages are gathered in a single message file, this file can be localized by having the text translated into the appropriate language or languages.
This section provides the following information on how to internationalize text strings:
To internationalize the logging and tracing, make sure that all these operations use message files to generate text messages. By putting message strings in a message file, you assign a unique identifier to each message. Table 16 lists the types of operations that use a message file and the associated C++ connector library methods in the GenGlobals class that the application-specific component uses to retrieve their messages from a message file.
Table 16. Methods to log and trace messages from a message file
Message-file operation | Connector library method |
---|---|
Logging | generateAndLogMsg() |
Tracing | generateAndTraceMsg() or traceWrite() |
Log messages should display in the language of the customer's locale. Therefore, log messages should always be isolated into a connector message file and retrieved with the generateAndLogMsg() method.
Because trace messages are intended for the product debugging process, they often do not need to display in the language of the customer's locale. Therefore, whether trace messages are contained in a message file is left at the discretion of the developer:
However, storing trace messages in the message file makes it easy to locate and maintain them.
In addition to handling the message-file operations in Table 16,, an internationalized connector must not contain any miscellaneous hardcoded strings. You must isolate these strings into the message file as well. Table 17 shows the method that the application-specific component can use to retrieve a message from a message file.
Table 17. Method to retrieve a message from the message file
Connector library class | Method |
---|---|
GenGlobals | generateMsg() |
To internationalize hardcoded strings, take the following steps:
For example, suppose your application-specific component contains the following hardcoded string in a line of code:
********Before updating the event status********
To isolate this hardcoded string from the connector code, create a message in the message file and assign it a unique message number (100):
100 ********Before updating the event status******** [EXPL] Hardcoded message in pollForEvents()
The application-specific component retrieves the isolated string (message 100) from the message file and replaces the hardcoded string with this retrieved string:
char * msg; //retrieve the message numbered '100' msg = generateMsg(100, CxMsgFormat::XRD_INFO, NULL, 0, NULL); MyClassObject::formatMsg(msg); // send retrieved message to a custom method
For more information on the use of message files, see Message logging.
The connector might need to perform locale-sensitive processing (such as data format conversions) when it converts from application data to the application-specific business object. During processing of a business object in a connector, there are two different locale settings:
Table 18 shows the method that the connector can use to retrieve the locale associated with the connector framework.
Table 18. Method to retrieve the connector framework's locale
Connector library class | Method |
---|---|
GenGlobals | getLocale() |
When a business object is created, it can have a locale associated with its data. Your connector can access this business-object locale in either of the following ways:
As discussed in Using connector configuration property values,, an application-specific component can use two types of configuration properties to customize its execution:
The names of all connector configuration properties must use only characters defined in the code set associated with the U.S English (en_US) locale. However, the values of these configuration properties can contain characters from the code set associated with the connector framework locale.
The application-specific component obtains the values of configuration properties with the methods described in Retrieving connector configuration properties.. These methods correctly handle characters from multibyte code sets. However, to ensure that your connector is internationalized, its code must correctly handle these configuration-property values once it retrieves them. The application-specific component must not assume that configuration-property values contain only single-byte characters.
An internationalized connector must also handle the following locale-sensitive tasks:
If data transfers from a location that uses one code set to a location that uses a different code set, some form of character conversion needs to be performed for the data to retain its meaning. The Java runtime environment within the Java Virtual Machine (JVM) represents data in Unicode. The Unicode character set is a universal character set that contains encodings for characters in most known character code sets (both single-byte and multibyte). There are several encoding formats of Unicode. The following encodings are used most frequently within the integration business system:
The UCS-2 encoding is the Unicode character set encoded in 2 bytes (octets).
The UTF-8 encoding is designed to address the use of Unicode character data in UNIX environments. It supports all ASCII code values (0...127) so that they are never interpreted as anything except a true ASCII code. Each code value is usually represented as a 1-, 2-, or 3- byte value.
Most components in the WebSphere business integration system, including the connector framework, are written in Java. Therefore, when data is transferred between most system components, it is encoded in the Unicode code set and there is no need for character conversion.
However, a C++ connector works with a C++ application (or technology). This application (or technology) might not have data already in the Unicode code set. Therefore, the application-specific component of the connector (written in C++, and converted by the connector framework to Java) might need to perform character conversion on application data for the application-specific business object. Figure 23 shows the character encoding for a C++ connector.
Figure
23. Character encoding with a C++ connector
To obtain the character encoding at runtime, Table 19 shows the method in the C++ connector library that the connector can use.
Table 19. Method to retrieve the connector framework's character encoding
Connector library class | Method |
---|---|
GenGlobals | getEncoding() |